diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/add_ons.txt | 65 | ||||
| -rw-r--r-- | docs/authentication.txt | 16 | ||||
| -rw-r--r-- | docs/db-api.txt | 29 | ||||
| -rw-r--r-- | docs/django-admin.txt | 6 | ||||
| -rw-r--r-- | docs/faq.txt | 2 | ||||
| -rw-r--r-- | docs/generic_views.txt | 25 | ||||
| -rw-r--r-- | docs/model-api.txt | 6 | ||||
| -rw-r--r-- | docs/settings.txt | 41 | ||||
| -rw-r--r-- | docs/templates.txt | 24 | ||||
| -rw-r--r-- | docs/templates_python.txt | 5 |
10 files changed, 204 insertions, 15 deletions
diff --git a/docs/add_ons.txt b/docs/add_ons.txt index f7b3056ef0..9f5dc640da 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -45,6 +45,71 @@ See the `csrf documentation`_. .. _csrf documentation: http://www.djangoproject.com/documentation/csrf/ +humanize +======== + +A set of Django template filters useful for adding a "human touch" to data. +To activate these filters, add ``'django.contrib.english'`` to your +``INSTALLED_APPS`` setting. Once you've done that, use ``{% load english %}`` +in a template, and you'll have access to these filters: + +apnumber +-------- + +For numbers 1-9, returns the number spelled out. Otherwise, returns the +number. This follows Associated Press style. + +Examples: + + * ``1`` becomes ``'one'``. + * ``2`` becomes ``'two'``. + * ``10`` becomes ``10``. + +You can pass in either an integer or a string representation of an integer. + +intcomma +-------- + +Converts an integer to a string containing commas every three digits. + +Examples: + + * ``4500`` becomes ``'4,500'``. + * ``45000`` becomes ``'45,000'``. + * ``450000`` becomes ``'450,000'``. + * ``4500000`` becomes ``'4,500,000'``. + +You can pass in either an integer or a string representation of an integer. + +intword +------- + +Converts a large integer to a friendly text representation. Works best for +numbers over 1 million. + +Examples: + + * ``1000000`` becomes ``'1.0 million'``. + * ``1200000`` becomes ``'1.2 million'``. + * ``1200000000`` becomes ``'1.2 billion'``. + +Values up to 1000000000000000 (one quadrillion) are supported. + +You can pass in either an integer or a string representation of an integer. + +ordinal +------- + +Converts an integer to its ordinal as a string. + +Examples: + + * ``1`` becomes ``'1st'``. + * ``2`` becomes ``'2nd'``. + * ``3`` becomes ``'3rd'``. + +You can pass in either an integer or a string representation of an integer. + flatpages ========= diff --git a/docs/authentication.txt b/docs/authentication.txt index 1be64c045a..c1a1f8494d 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -82,14 +82,14 @@ Methods ``user_permissions``. ``User`` objects can access their related objects in the same way as any other `Django model`_:: - ``myuser.objects.groups = [group_list]`` - ``myuser.objects.groups.add(group, group,...)`` - ``myuser.objects.groups.remove(group, group,...)`` - ``myuser.objects.groups.clear()`` - ``myuser.objects.permissions = [permission_list]`` - ``myuser.objects.permissions.add(permission, permission, ...)`` - ``myuser.objects.permissions.remove(permission, permission, ...]`` - ``myuser.objects.permissions.clear()`` + myuser.objects.groups = [group_list] + myuser.objects.groups.add(group, group,...) + myuser.objects.groups.remove(group, group,...) + myuser.objects.groups.clear() + myuser.objects.permissions = [permission_list] + myuser.objects.permissions.add(permission, permission, ...) + myuser.objects.permissions.remove(permission, permission, ...] + myuser.objects.permissions.clear() In addition to those automatic API methods, ``User`` objects have the following custom methods: diff --git a/docs/db-api.txt b/docs/db-api.txt index 4442a75125..3624620609 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -1035,6 +1035,15 @@ SQL equivalent:: SELECT ... WHERE pub_date IS NULL; +search +~~~~~~ + +A boolean full-text search, taking advantage of full-text indexing. This is +like ``contains`` but is significantly faster due to full-text indexing. + +Note this is only available in MySQL and requires direct manipulation of the +database to add the full-text index. + Default lookups are exact ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1578,3 +1587,23 @@ get_FOO_height() and get_FOO_width() For every ``ImageField``, the object will have ``get_FOO_height()`` and ``get_FOO_width()`` methods, where ``FOO`` is the name of the field. This returns the height (or width) of the image, as an integer, in pixels. + +Falling back to raw SQL +======================= + +If you find yourself needing to write an SQL query that is too complex for +Django's database-mapper to handle, you can fall back into raw-SQL statement +mode. + +The preferred way to do this is by giving your model custom methods or custom +manager methods that execute queries. Although there's nothing in Django that +*requires* database queries to live in the model layer, this approach keeps all +your data-access logic in one place, which is smart from an code-organization +standpoint. For instructions, see `Executing custom SQL`_. + +Finally, it's important to note that the Django database layer is merely an +interface to your database. You can access your database via other tools, +programming languages or database frameworks; there's nothing Django-specific +about your database. + +.. _Executing custom SQL: http://www.djangoproject.com/documentation/model_api/#executing-custom-sql diff --git a/docs/django-admin.txt b/docs/django-admin.txt index 90f5f5e4ed..3334ae4530 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -148,7 +148,11 @@ If you run this script as a user with normal privileges (recommended), you might not have access to start a port on a low port number. Low port numbers are reserved for the superuser (root). -DO NOT USE THIS SERVER IN A PRODUCTION SETTING. +DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through +security audits or performance tests. (And that's how it's gonna stay. We're in +the business of making Web frameworks, not Web servers, so improving this +server to be able to handle a production environment is outside the scope of +Django.) The development server automatically reloads Python code for each request, as needed. You don't need to restart the server for code changes to take effect. diff --git a/docs/faq.txt b/docs/faq.txt index d63c02550e..a2c069f0ca 100644 --- a/docs/faq.txt +++ b/docs/faq.txt @@ -112,7 +112,7 @@ Lawrence, Kansas, USA. .. _`Simon Willison`: http://simon.incutio.com/ .. _`simon.incutio.com`: http://simon.incutio.com/ .. _`Jacob Kaplan-Moss`: http://www.jacobian.org/ -.. _`Wilson Miner`: http://www.wilsonminer.com/live/ +.. _`Wilson Miner`: http://www.wilsonminer.com/ Which sites use Django? ----------------------- diff --git a/docs/generic_views.txt b/docs/generic_views.txt index 317828a2b2..d14fe12418 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -641,8 +641,10 @@ A page representing a list of objects. * ``paginate_by``: An integer specifying how many objects should be displayed per page. If this is given, the view will paginate objects with - ``paginate_by`` objects per page. The view will expect a ``page`` query - string (GET) parameter containing a zero-indexed page number. + ``paginate_by`` objects per page. The view will expect either a ``page`` + query string parameter (via ``GET``) containing a zero-indexed page + number, or a ``page`` variable specified in the URLconf. See + "Notes on pagination" below. * ``template_name``: The full name of a template to use in rendering the page. This lets you override the default template name (see below). @@ -711,6 +713,25 @@ If the results are paginated, the context will contain these extra variables: * ``hits``: The total number of objects across *all* pages, not just this page. +Notes on pagination +~~~~~~~~~~~~~~~~~~~ + +If ``paginate_by`` is specified, Django will paginate the results. You can +specify the page number in the URL in one of two ways: + + * Use the ``page`` parameter in the URLconf. For example, this is what + your URLconf might look like:: + + (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict)) + + * Pass the page number via the ``page`` query-string parameter. For + example, a URL would look like this: + + /objects/?page=3 + +In both cases, ``page`` is 1-based, not 0-based, so the first page would be +represented as page ``1``. + ``django.views.generic.list_detail.object_detail`` -------------------------------------------------- diff --git a/docs/model-api.txt b/docs/model-api.txt index 9cc5b8f203..c6707a691b 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -1239,6 +1239,12 @@ The above code results in an admin change list page that looks like this: (This example also has ``search_fields`` defined. See below.) +``list_per_page`` +----------------- + +Set ``list_per_page`` to control how many items appear on each paginated admin +change list page. By default, this is set to ``100``. + ``list_select_related`` ----------------------- diff --git a/docs/settings.txt b/docs/settings.txt index 26d5930f21..553736b280 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -291,7 +291,7 @@ The default formatting to use for date fields on Django admin change-list pages -- and, possibly, by other parts of the system. See `allowed date format strings`_. -See also DATETIME_FORMAT and TIME_FORMAT. +See also DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. .. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now @@ -304,7 +304,7 @@ The default formatting to use for datetime fields on Django admin change-list pages -- and, possibly, by other parts of the system. See `allowed date format strings`_. -See also DATE_FORMAT and TIME_FORMAT. +See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. .. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now @@ -532,6 +532,23 @@ Default:: A tuple of middleware classes to use. See the `middleware docs`_. +MONTH_DAY_FORMAT +---------------- + +Default: ``'F j'`` + +The default formatting to use for date fields on Django admin change-list +pages -- and, possibly, by other parts of the system -- in cases when only the +month and day are displayed. + +For example, when a Django admin change-list page is being filtered by a date +drilldown, the header for a given day displays the day and month. Different +locales have different formats. For example, U.S. English would say +"January 1," whereas Spanish might say "1 Enero." + +See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT, +TIME_FORMAT and YEAR_MONTH_FORMAT. + PREPEND_WWW ----------- @@ -696,7 +713,8 @@ The default formatting to use for time fields on Django admin change-list pages -- and, possibly, by other parts of the system. See `allowed date format strings`_. -See also DATE_FORMAT and DATETIME_FORMAT. +See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and +MONTH_DAY_FORMAT. .. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now @@ -720,6 +738,23 @@ A boolean that specifies whether to output the "Etag" header. This saves bandwidth but slows down performance. This is only used if ``CommonMiddleware`` is installed (see the `middleware docs`_). +YEAR_MONTH_FORMAT +----------------- + +Default: ``'F Y'`` + +The default formatting to use for date fields on Django admin change-list +pages -- and, possibly, by other parts of the system -- in cases when only the +year and month are displayed. + +For example, when a Django admin change-list page is being filtered by a date +drilldown, the header for a given month displays the month and the year. +Different locales have different formats. For example, U.S. English would say +"January 2006," whereas another locale might say "2006/January." + +See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT, +TIME_FORMAT and MONTH_DAY_FORMAT. + .. _cache docs: http://www.djangoproject.com/documentation/cache/ .. _middleware docs: http://www.djangoproject.com/documentation/middleware/ .. _session docs: http://www.djangoproject.com/documentation/sessions/ diff --git a/docs/templates.txt b/docs/templates.txt index 8d5a383b8c..c191b409f4 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -1091,3 +1091,27 @@ Value Argument Outputs ``None`` ``"yeah,no"`` ``"no"`` (converts None to False if no mapping for None is given) ========== ====================== ================================== + +Other tags and filter libraries +=============================== + +Django comes with a couple of other template-tag libraries that you have to +enable explicitly in your ``INSTALLED_APPS`` setting and enable in your +template with the ``{% load %}`` tag. + +django.contrib.humanize +----------------------- + +A set of Django template filters useful for adding a "human touch" to data. See +the `humanize documentation`_. + +.. _humanize documentation: http://www.djangoproject.com/documentation/add_ons/#humanize + +django.contrib.markup +--------------------- + +A collection of template filters that implement these common markup languages: + + * Textile + * Markdown + * ReST (ReStructured Text) diff --git a/docs/templates_python.txt b/docs/templates_python.txt index 6c33052792..dea5bcbee6 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -368,6 +368,11 @@ Generally, you'll store templates in files on your filesystem rather than using the low-level ``Template`` API yourself. Save templates in a directory specified as a **template directory**. +Django searches for template directories in a number of places, depending on +your template-loader settings (see "Loader types" below), but the most basic +way of specifying template directories is by using the ``TEMPLATE_DIRS`` +setting. + The TEMPLATE_DIRS setting ~~~~~~~~~~~~~~~~~~~~~~~~~ |