From 94aeccf18eca83ce8c983695059d56f66127a0fd Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Fri, 6 Apr 2007 04:39:24 +0000 Subject: newforms-admin: Merged to [4939] git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@4940 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/add_ons.txt | 24 ++++++++++++++---- docs/cache.txt | 17 ++++++++++--- docs/django-admin.txt | 2 +- docs/faq.txt | 11 ++++---- docs/fastcgi.txt | 38 +++++++++++++++++++++------ docs/forms.txt | 8 +++--- docs/generic_views.txt | 2 +- docs/model-api.txt | 38 +++++++++++++++++++++------ docs/modpython.txt | 21 ++++++++++++--- docs/release_notes_0.96.txt | 4 +-- docs/request_response.txt | 4 +++ docs/sessions.txt | 2 +- docs/templates.txt | 28 ++++++++++++++++---- docs/testing.txt | 5 ++-- docs/tutorial01.txt | 16 ++++++++---- docs/url_dispatch.txt | 62 ++++++++++++++++++++++++++++++++++++++++++--- docs/webdesign.txt | 53 ++++++++++++++++++++++++++++++++++++++ 17 files changed, 278 insertions(+), 57 deletions(-) create mode 100644 docs/webdesign.txt (limited to 'docs') diff --git a/docs/add_ons.txt b/docs/add_ons.txt index 9809cf46f8..b92ae0bd17 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -9,6 +9,13 @@ problems. This code lives in ``django/contrib`` in the Django distribution. Here's a rundown of the packages in ``contrib``: +.. admonition:: Note + + For most of these add-ons -- specifically, the add-ons that include either + models or template tags -- you'll need to add the package name (e.g., + ``'django.contrib.admin'``) to your ``INSTALLED_APPS`` setting and re-run + ``manage.py syncdb``. + .. _"batteries included" philosophy: http://docs.python.org/tut/node12.html#batteries-included admin @@ -147,13 +154,20 @@ contains a ``USZipCodeField`` that you can use to validate U.S. zip codes. markup ====== -A collection of template filters that implement these common markup languages: +A collection of template filters that implement common markup languages: + + * ``textile`` -- implements `Textile`_ + * ``markdown`` -- implements `Markdown`_ + * ``restructuredtext`` -- implements `ReST (ReStructured Text)`_ - * `Textile`_ - * `Markdown`_ - * `ReST (ReStructured Text)`_ +In each case, the filter expects formatted markup as a string and returns a +string representing the marked-up text. For example, the ``textile`` filter +converts text that is marked-up in Textile format to HTML. -For documentation, read the source code in django/contrib/markup/templatetags/markup.py. +To activate these filters, add ``'django.contrib.markup'`` to your +``INSTALLED_APPS`` setting. Once you've done that, use ``{% load markup %}`` in +a template, and you'll have access to these filters. For more documentation, +read the source code in django/contrib/markup/templatetags/markup.py. .. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 .. _Markdown: http://en.wikipedia.org/wiki/Markdown diff --git a/docs/cache.txt b/docs/cache.txt index 054d99819d..e245e100e7 100644 --- a/docs/cache.txt +++ b/docs/cache.txt @@ -66,10 +66,19 @@ deleting arbitrary data in the cache. All data is stored directly in memory, so there's no overhead of database or filesystem usage. After installing Memcached itself, you'll need to install the Memcached Python -bindings. They're in a single Python module, memcache.py, available at -ftp://ftp.tummy.com/pub/python-memcached/ . If that URL is no longer valid, -just go to the Memcached Web site (http://www.danga.com/memcached/) and get the -Python bindings from the "Client APIs" section. +bindings. Two versions of this are available. Choose and install *one* of the +following modules: + + * The fastest available option is a module called ``cmemcache``, available + at http://gijsbert.org/cmemcache/ . (This module is only compatible with + the Django development version. Django 0.96 is only compatible with the + second option, below.) + + * If you can't install ``cmemcache``, you can install ``python-memcached``, + available at ftp://ftp.tummy.com/pub/python-memcached/ . If that URL is + no longer valid, just go to the Memcached Web site + (http://www.danga.com/memcached/) and get the Python bindings from the + "Client APIs" section. To use Memcached with Django, set ``CACHE_BACKEND`` to ``memcached://ip:port/``, where ``ip`` is the IP address of the Memcached diff --git a/docs/django-admin.txt b/docs/django-admin.txt index b6028dc2a0..388eaf98ac 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -366,7 +366,7 @@ Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames. sqlsequencereset [appname appname ...] ---------------------------------------------- -Prints the SQL statements for resetting PostgreSQL sequences for the given +Prints the SQL statements for resetting sequences for the given appnames. See http://simon.incutio.com/archive/2004/04/21/postgres for more information. diff --git a/docs/faq.txt b/docs/faq.txt index 33e8ef01b4..202b73c6be 100644 --- a/docs/faq.txt +++ b/docs/faq.txt @@ -328,8 +328,9 @@ Do I have to use mod_python? Although we recommend mod_python for production use, you don't have to use it, thanks to the fact that Django uses an arrangement called WSGI_. Django can -talk to any WSGI-enabled server. The most common non-mod_python deployment -setup is FastCGI. See `How to use Django with FastCGI`_ for full information. +talk to any WSGI-enabled server. Other non-mod_python deployment setups are +FastCGI, SCGI or AJP. See `How to use Django with FastCGI, SCGI or AJP`_ for +full information. Also, see the `server arrangements wiki page`_ for other deployment strategies. @@ -337,7 +338,7 @@ If you just want to play around and develop things on your local computer, use the development Web server that comes with Django. Things should Just Work. .. _WSGI: http://www.python.org/peps/pep-0333.html -.. _How to use Django with FastCGI: ../fastcgi/ +.. _How to use Django with FastCGI, SCGI or AJP: ../fastcgi/ .. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements How do I install mod_python on Windows? @@ -381,9 +382,9 @@ Why do I get an error about importing DJANGO_SETTINGS_MODULE? Make sure that: * The environment variable DJANGO_SETTINGS_MODULE is set to a fully-qualified - Python module (i.e. "mysite.settings.main"). + Python module (i.e. "mysite.settings"). - * Said module is on ``sys.path`` (``import mysite.settings.main`` should work). + * Said module is on ``sys.path`` (``import mysite.settings`` should work). * The module doesn't contain syntax errors (of course). diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt index 5ecaac8666..119688096f 100644 --- a/docs/fastcgi.txt +++ b/docs/fastcgi.txt @@ -1,11 +1,17 @@ -============================== -How to use Django with FastCGI -============================== +=========================================== +How to use Django with FastCGI, SCGI or AJP +=========================================== Although the `current preferred setup`_ for running Django is Apache_ with -`mod_python`_, many people use shared hosting, on which FastCGI is the only -viable option. In some setups, FastCGI also allows better security -- and, -possibly, better performance -- than mod_python. +`mod_python`_, many people use shared hosting, on which protocols such as +FastCGI, SCGI or AJP are the only viable options. In some setups, these protocols +also allow better security -- and, possibly, better performance -- than mod_python. + +.. admonition:: Note + + This document primarily focuses on FastCGI. Other protocols, such as SCGI + and AJP, are also supported, through the ``flup`` Python package. See the + "Protocols" section below for specifics about SCGI and AJP. Essentially, FastCGI is an efficient way of letting an external application serve pages to a Web server. The Web server delegates the incoming Web requests @@ -74,10 +80,26 @@ your ``manage.py`` is), and then run ``manage.py`` with the ``runfcgi`` option:: If you specify ``help`` as the only option after ``runfcgi``, it'll display a list of all the available options. -You'll need to specify either a ``socket`` or both ``host`` and ``port``. Then, -when you set up your Web server, you'll just need to point it at the host/port +You'll need to specify either a ``socket``, ``protocol`` or both ``host`` and ``port``. +Then, when you set up your Web server, you'll just need to point it at the host/port or socket you specified when starting the FastCGI server. +Protocols +--------- + +Django supports all the protocols that flup_ does, namely fastcgi_, `SCGI`_ and +`AJP1.3`_ (the Apache JServ Protocol, version 1.3). Select your preferred +protocol by using the ``protocol=`` option with +``./manage.py runfcgi`` -- where ```` may be one of: ``fcgi`` +(the default), ``scgi`` or ``ajp``. For example:: + + ./manage.py runfcgi --protocol=scgi + +.. _flup: http://www.saddi.com/software/flup/ +.. _fastcgi: http://www.fastcgi.com/ +.. _SCGI: http://python.ca/scgi/protocol.txt +.. _AJP1.3: http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html + Examples -------- diff --git a/docs/forms.txt b/docs/forms.txt index f76f6d27ef..ce1010235f 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -517,10 +517,10 @@ to put punctuation at the end of your validation messages. When are validators called? --------------------------- -After a form has been submitted, Django first checks to see that all the -required fields are present and non-empty. For each field that passes that -test *and if the form submission contained data* for that field, all the -validators for that field are called in turn. The emphasized portion in the +After a form has been submitted, Django validates each field in turn. First, +if the field is required, Django checks that it is present and non-empty. Then, +if that test passes *and the form submission contained data* for that field, all +the validators for that field are called in turn. The emphasized portion in the last sentence is important: if a form field is not submitted (because it contains no data -- which is normal HTML behavior), the validators are not run against the field. diff --git a/docs/generic_views.txt b/docs/generic_views.txt index 7659a428c5..0496a58691 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -222,7 +222,7 @@ In addition to ``extra_context``, the template's context will be: by ``date_field``. For example, if ``num_latest`` is ``10``, then ``latest`` will be a list of the latest 10 objects in ``queryset``. -.. _RequestContext docs: ../templates_python/#subclassing-context-djangocontext +.. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext ``django.views.generic.date_based.archive_year`` ------------------------------------------------ diff --git a/docs/model-api.txt b/docs/model-api.txt index 155ef63271..a03ed09eb2 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -1307,13 +1307,13 @@ A few special cases to note about ``list_display``: * Usually, elements of ``list_display`` that aren't actual database fields can't be used in sorting (because Django does all the sorting at the database level). - + However, if an element of ``list_display`` represents a certain database field, you can indicate this fact by setting the ``admin_order_field`` attribute of the item. - + For example:: - + class Person(models.Model): first_name = models.CharField(maxlength=50) color_code = models.CharField(maxlength=6) @@ -1325,7 +1325,7 @@ A few special cases to note about ``list_display``: return '%s' % (self.color_code, self.first_name) colored_first_name.allow_tags = True colored_first_name.admin_order_field = 'first_name' - + The above will tell Django to order by the ``first_name`` field when trying to sort by ``colored_first_name`` in the admin. @@ -1758,16 +1758,38 @@ slightly violates the DRY principle: the URL for this object is defined both in the URLConf file and in the model. You can further decouple your models from the URLconf using the ``permalink`` -decorator. This decorator is passed the view function and any parameters you -would use for accessing this instance directly. Django then works out the -correct full URL path using the URLconf. For example:: +decorator. This decorator is passed the view function, a list of positional +parameters and (optionally) a dictionary of named parameters. Django then +works out the correct full URL path using the URLconf, substituting the +parameters you have given into the URL. For example, if your URLconf +contained a line such as:: + + (r'^/people/(\d+)/$', 'people.views.details'), + +...your model could have a ``get_absolute_url`` method that looked like this:: from django.db.models import permalink def get_absolute_url(self): - return ('people.views.details', str(self.id)) + return ('people.views.details', [str(self.id)]) get_absolute_url = permalink(get_absolute_url) +Similarly, if you had a URLconf entry that looked like:: + + (r'/archive/(?P\d{4})/(?P\d{1,2})/(?P\d{1,2})/$', archive_view) + +...you could reference this using ``permalink()`` as follows:: + + def get_absolute_url(self): + return ('archive_view', (), { + 'year': self.created.year, + 'month': self.created.month, + 'day': self.created.day}) + get_absolute_url = permalink(get_absolute_url) + +Notice that we specify an empty sequence for the second argument in this case, +because we only want to pass keyword arguments, not named arguments. + In this way, you're tying the model's absolute URL to the view that is used to display it, without repeating the URL information anywhere. You can still use the ``get_absolute_url`` method in templates, as before. diff --git a/docs/modpython.txt b/docs/modpython.txt index 2c999753c7..31ec1efe49 100644 --- a/docs/modpython.txt +++ b/docs/modpython.txt @@ -13,14 +13,15 @@ other server arrangements. Django requires Apache 2.x and mod_python 3.x, and you should use Apache's `prefork MPM`_, as opposed to the `worker MPM`_. -You may also be interested in `How to use Django with FastCGI`_. +You may also be interested in `How to use Django with FastCGI, SCGI or AJP`_ +(which also covers SCGI and AJP). .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _mod_perl: http://perl.apache.org/ .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html -.. _How to use Django with FastCGI: ../fastcgi/ +.. _How to use Django with FastCGI, SCGI or AJP: ../fastcgi/ Basic configuration =================== @@ -37,7 +38,8 @@ Then edit your ``httpd.conf`` file and add the following:: PythonDebug On -...and replace ``mysite.settings`` with the Python path to your settings file. +...and replace ``mysite.settings`` with the Python import path to your Django +project's settings file. This tells Apache: "Use mod_python for any URL at or under '/mysite/', using the Django mod_python handler." It passes the value of ``DJANGO_SETTINGS_MODULE`` @@ -53,6 +55,19 @@ on it, you'll need to tell mod_python:: PythonPath "['/path/to/project'] + sys.path" +.. caution:: + + Is you are using Windows, remember that the path will contain backslashes. + This string is passed through Python's string parser twice, so you need to + escape each backslash **twice**:: + + PythonPath "['c:\\\\path\\\\to\\\\project'] + sys.path" + + or use raw strings:: + + PythonPath "[r'c:\\path\\to\\project'] + sys.path" + + You can also add directives such as ``PythonAutoReload Off`` for performance. See the `mod_python documentation`_ for a full list of options. diff --git a/docs/release_notes_0.96.txt b/docs/release_notes_0.96.txt index ca5f5e045c..f62780c6b2 100644 --- a/docs/release_notes_0.96.txt +++ b/docs/release_notes_0.96.txt @@ -62,7 +62,7 @@ Database constraint names changed The format of the constraint names Django generates for foreign key references have changed slightly. These names are generally only used when it is not possible to put the reference directly on the affected -column, so they is not always visible. +column, so they are not always visible. The effect of this change is that running ``manage.py reset`` and similar commands against an existing database may generate SQL with @@ -261,4 +261,4 @@ all their hard work: that went into 0.96 -- but everyone who's contributed to Django is listed in AUTHORS_. -.. _AUTHORS: http://code.djangoproject.com/browser/django/trunk/AUTHORS \ No newline at end of file +.. _AUTHORS: http://code.djangoproject.com/browser/django/trunk/AUTHORS diff --git a/docs/request_response.txt b/docs/request_response.txt index 2b79903d13..40f06c859f 100644 --- a/docs/request_response.txt +++ b/docs/request_response.txt @@ -416,6 +416,10 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in The constructor doesn't take any arguments. Use this to designate that a page hasn't been modified since the user's last request. +``HttpResponseBadRequest`` + **New in Django development version.** + Acts just like ``HttpResponse`` but uses a 400 status code. + ``HttpResponseNotFound`` Acts just like ``HttpResponse`` but uses a 404 status code. diff --git a/docs/sessions.txt b/docs/sessions.txt index 660718b4e2..55fbc2c3da 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -158,7 +158,7 @@ is defined in ``django/contrib/sessions/models.py``. Because it's a normal model, you can access sessions using the normal Django database API:: >>> from django.contrib.sessions.models import Session - >>> s = Session.objects.get_object(pk='2b1189a188b44ad18c35e113ac6ceead') + >>> s = Session.objects.get(pk='2b1189a188b44ad18c35e113ac6ceead') >>> s.expire_date datetime.datetime(2005, 8, 20, 13, 35, 12) diff --git a/docs/templates.txt b/docs/templates.txt index db748ae432..d93ee49ac1 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -737,6 +737,7 @@ The following snippet of template code would accomplish this dubious task::
  • {{ item }}
    • {% endfor %} + {% endfor %} @@ -756,7 +757,7 @@ i.e.:: spaceless ~~~~~~~~~ -Normalizes whitespace between HTML tags to a single space. This includes tab +Removes whitespace between HTML tags. This includes tab characters and newlines. Example usage:: @@ -769,9 +770,9 @@ Example usage:: This example would return this HTML:: -

    Foo

    +

    Foo

    -Only space between *tags* is normalized -- not space between tags and text. In +Only space between *tags* is removed -- not space between tags and text. In this example, the space around ``Hello`` won't be stripped:: {% spaceless %} @@ -872,6 +873,23 @@ Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5 which is rounded up to 88). +with +~~~~ + +**New in Django development version** + +Caches a complex variable under a simpler name. This is useful when accessing +an "expensive" method (e.g., one that hits the database) multiple times. + +For example:: + + {% with business.employees.count as total %} + {{ total }} employee{{ total|pluralize }} + {% endwith %} + +The populated variable (in the example above, ``total``) is only available +between the ``{% with %}`` and ``{% endwith %}`` tags. + Built-in filter reference ------------------------- @@ -970,7 +988,7 @@ place -- but only if there's a decimal part to be displayed. For example: * ``36.15`` gets converted to ``36.2`` * ``36`` gets converted to ``36`` -If used with a numeric integer argument, ``floatformat`` rounds a number to that +If used with a numeric integer argument, ``floatformat`` rounds a number to that many decimal places. For example: * ``36.1234`` with floatformat:3 gets converted to ``36.123`` @@ -983,7 +1001,7 @@ For example: * ``36.1234`` with floatformat:-3 gets converted to ``36.123`` * ``36`` with floatformat:-4 gets converted to ``36`` -Using ``floatformat`` with no argument is equivalent to using ``floatformat`` with +Using ``floatformat`` with no argument is equivalent to using ``floatformat`` with an argument of ``-1``. get_digit diff --git a/docs/testing.txt b/docs/testing.txt index 31cea791d3..5b27ae6484 100644 --- a/docs/testing.txt +++ b/docs/testing.txt @@ -276,7 +276,7 @@ for testing purposes: ``status_code`` The HTTP status of the response. See RFC2616_ for a full list of HTTP status codes. - ``content`` The body of the response. The is the final page + ``content`` The body of the response. This is the final page content as rendered by the view, or any error message (such as the URL for a 302 redirect). @@ -468,7 +468,8 @@ failed:: FAILED (failures=1) -The return code for the script will indicate the number of tests that failed. +The return code for the script is the total number of failed and erroneous +tests. If all the tests pass, the return code is 0. Regardless of whether the tests pass or fail, the test database is destroyed when all the tests have been executed. diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt index 56c5fa769e..0e857d09ca 100644 --- a/docs/tutorial01.txt +++ b/docs/tutorial01.txt @@ -133,8 +133,8 @@ Now, edit ``settings.py``. It's a normal Python module with module-level variables representing Django settings. Change these settings to match your database's connection parameters: - * ``DATABASE_ENGINE`` -- Either 'postgresql', 'mysql' or 'sqlite3'. - More coming soon. + * ``DATABASE_ENGINE`` -- Either 'postgresql_psycopg2', 'mysql' or 'sqlite3'. + Other backends are `also available`_. * ``DATABASE_NAME`` -- The name of your database, or the full (absolute) path to the database file if you're using SQLite. * ``DATABASE_USER`` -- Your database username (not used for SQLite). @@ -143,6 +143,8 @@ database's connection parameters: empty string if your database server is on the same physical machine (not used for SQLite). +.. _also available: ../settings/ + .. admonition:: Note If you're using PostgreSQL or MySQL, make sure you've created a database by @@ -319,7 +321,8 @@ Now Django knows ``mysite`` includes the ``polls`` app. Let's run another comman python manage.py sql polls -You should see the following (the CREATE TABLE SQL statements for the polls app):: +You should see something similar to the following (the CREATE TABLE SQL statements +for the polls app):: BEGIN; CREATE TABLE "polls_poll" ( @@ -337,6 +340,8 @@ You should see the following (the CREATE TABLE SQL statements for the polls app) Note the following: + * The exact output will vary depending on the database you are using. + * Table names are automatically generated by combining the name of the app (``polls``) and the lowercase name of the model -- ``poll`` and ``choice``. (You can override this behavior.) @@ -365,8 +370,9 @@ If you're interested, also run the following commands: * ``python manage.py validate polls`` -- Checks for any errors in the construction of your models. - * ``python manage.py sqlinitialdata polls`` -- Outputs any initial data - required for Django's admin framework and your models. + * ``python manage.py sqlcustom polls`` -- Outputs any custom SQL statements + (such as table modifications or constraints) that are defined for the + application. * ``python manage.py sqlclear polls`` -- Outputs the necessary ``DROP TABLE`` statements for this app, according to which tables already exist diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt index 85c87de680..e6e1cb6cbf 100644 --- a/docs/url_dispatch.txt +++ b/docs/url_dispatch.txt @@ -185,10 +185,25 @@ The first argument to ``patterns()`` is a string ``prefix``. See The remaining arguments should be tuples in this format:: - (regular expression, Python callback function [, optional dictionary]) + (regular expression, Python callback function [, optional dictionary [, optional name]]) -...where ``optional dictionary`` is optional. (See -_`Passing extra options to view functions` below.) +...where ``optional dictionary`` and ``optional name`` are optional. (See +`Passing extra options to view functions`_ below.) + +url +--- +**New in development version** + +The ``url()`` function can be used instead of a tuple as an argument to +``patterns()``. This is convenient if you wish to specify a name without the +optional extra arguments dictionary. For example:: + + urlpatterns = patterns('', + url(r'/index/$', index_view, name="main-view"), + ... + ) + +See `Naming URL patterns`_ for why the ``name`` parameter is useful. handler404 ---------- @@ -479,3 +494,44 @@ The style you use is up to you. Note that if you use this technique -- passing objects rather than strings -- the view prefix (as explained in "The view prefix" above) will have no effect. + +Naming URL patterns +=================== + +**New in development version** + +It is fairly common to use the same view function in multiple URL patterns in +your URLConf. This leads to problems when you come to do reverse URL matching, +because the ``permalink()`` decorator and ``{% url %}`` template tag use the +name of the view function to find a match. + +To solve this problem, you can give a name to each of your URL patterns in +order to distinguish them from other patterns using the same views and +parameters. You can then use this name wherever you would otherwise use the +name of the view function. For example, if you URLConf contains:: + + urlpatterns = patterns('', + url(r'/archive/(\d{4})/$', archive, name="full-archive"), + url(r'/archive-summary/(\d{4})/$', archive, {'summary': True}, "arch-summary"), + ) + +...you could refer to either the summary archive view in a template as:: + + {% url arch-summary 1945 %} + +Even though both URL patterns refer to the ``archive`` view here, using the +``name`` parameter to ``url()`` allows you to tell them apart in templates. + +The string used for the URL name can contain any characters you like. You are +not restricted to valid Python names. + +.. note:: + + Make sure that when you name your URLs, you use names that are unlikely to + clash with any other application's choice of names. If you call your URL + pattern *comment* and another application does the same thing, there is no + guarantee which URL will be inserted into your template when you use this + name. Putting a prefix on your URL names, perhaps derived from + the application name, will decrease the chances of collision. Something + like *myapp-comment* is recommended over simply *comment*. + diff --git a/docs/webdesign.txt b/docs/webdesign.txt new file mode 100644 index 0000000000..8e6eae89dd --- /dev/null +++ b/docs/webdesign.txt @@ -0,0 +1,53 @@ +======================== +django.contrib.webdesign +======================== + +The ``django.contrib.webdesign`` package, part of the `"django.contrib" add-ons`_, +provides various Django helpers that are particularly useful to Web *designers* +(as opposed to developers). + +At present, the package contains only a single template tag. If you have ideas +for Web-designer-friendly functionality in Django, please `suggest them`_. + +.. _"django.contrib" add-ons: ../add_ons/ +.. _suggest them: ../contributing/ + +Template tags +============= + +To use these template tags, add ``'django.contrib.webdesign'`` to your +``INSTALLED_APPS`` setting. Once you've done that, use +``{% load webdesign %}`` in a template to give your template access to the tags. + + +lorem +===== + +Displays random "lorem ipsum" Latin text. This is useful for providing sample +data in templates. + +Usage:: + + {% lorem [count] [method] [random] %} + +The ``{% lorem %}`` tag can be used with zero, one, two or three arguments. +The arguments are: + + =========== ============================================================= + Argument Description + =========== ============================================================= + ``count`` A number (or variable) containing the number of paragraphs or + words to generate (default is 1). + ``method`` Either ``w`` for words, ``p`` for HTML paragraphs or ``b`` + for plain-text paragraph blocks (default is ``b``). + ``random`` The word ``random``, which if given, does not use the common + paragraph ("Lorem ipsum dolor sit amet...") when generating + text. + =========== ============================================================= + +Examples: + + * ``{% lorem %}`` will output the common "lorem ipsum" paragraph. + * ``{% lorem 3 p %}`` will output the common "lorem ipsum" paragraph + and two random paragraphs each wrapped in HTML ``

    `` tags. + * ``{% lorem 2 w random %}`` will output two random Latin words. -- cgit v1.3