diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/contrib/admin/_images/article_actions.png | bin | 35643 -> 13367 bytes | |||
| -rw-r--r-- | docs/ref/contrib/admin/index.txt | 114 | ||||
| -rw-r--r-- | docs/ref/contrib/contenttypes.txt | 4 | ||||
| -rw-r--r-- | docs/ref/databases.txt | 2 | ||||
| -rw-r--r-- | docs/ref/forms/fields.txt | 41 | ||||
| -rw-r--r-- | docs/ref/middleware.txt | 13 | ||||
| -rw-r--r-- | docs/ref/models/instances.txt | 42 | ||||
| -rw-r--r-- | docs/ref/models/querysets.txt | 2 | ||||
| -rw-r--r-- | docs/ref/templates/api.txt | 17 | ||||
| -rw-r--r-- | docs/ref/templates/builtins.txt | 37 |
10 files changed, 183 insertions, 89 deletions
diff --git a/docs/ref/contrib/admin/_images/article_actions.png b/docs/ref/contrib/admin/_images/article_actions.png Binary files differindex 254a8ad557..df4ab8f1ec 100644 --- a/docs/ref/contrib/admin/_images/article_actions.png +++ b/docs/ref/contrib/admin/_images/article_actions.png diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 64d9c52492..584672e4f0 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -704,6 +704,8 @@ objects. Templates can override or extend base admin templates as described in If you don't specify this attribute, a default template shipped with Django that provides the standard appearance is used. +.. _model-admin-methods: + ``ModelAdmin`` methods ---------------------- @@ -760,12 +762,19 @@ documented in :ref:`topics-http-urls`:: anything, so you'll usually want to prepend your custom URLs to the built-in ones. -Note, however, that the ``self.my_view`` function registered above will *not* -have any permission check done; it'll be accessible to the general public. Since -this is usually not what you want, Django provides a convience wrapper to check -permissions. This wrapper is :meth:`AdminSite.admin_view` (i.e. -``self.admin_site.admin_view`` inside a ``ModelAdmin`` instance); use it like -so:: +However, the ``self.my_view`` function registered above suffers from two +problems: + + * It will *not* perform and permission checks, so it will be accessible to + the general public. + * It will *not* provide any header details to prevent caching. This means if + the page retrieves data from the database, and caching middleware is + active, the page could show outdated information. + +Since this is usually not what you want, Django provides a convenience wrapper +to check permissions and mark the view as non-cacheable. This wrapper is +:meth:`AdminSite.admin_view` (i.e. ``self.admin_site.admin_view`` inside a +``ModelAdmin`` instance); use it like so:: class MyModelAdmin(admin.ModelAdmin): def get_urls(self): @@ -779,7 +788,14 @@ Notice the wrapped view in the fifth line above:: (r'^my_view/$', self.admin_site.admin_view(self.my_view)) -This wrapping will protect ``self.my_view`` from unauthorized access. +This wrapping will protect ``self.my_view`` from unauthorized access and will +apply the ``django.views.decorators.cache.never_cache`` decorator to make sure +it is not cached if the cache middleware is active. + +If the page is cacheable, but you still want the permission check to be performed, +you can pass a ``cacheable=True`` argument to :meth:`AdminSite.admin_view`:: + + (r'^my_view/$', self.admin_site.admin_view(self.my_view, cacheable=True)) .. method:: ModelAdmin.formfield_for_foreignkey(self, db_field, request, **kwargs) @@ -792,7 +808,7 @@ return a subset of objects for this foreign key field based on the user:: class MyModelAdmin(admin.ModelAdmin): def formfield_for_foreignkey(self, db_field, request, **kwargs): if db_field.name == "car": - kwargs["queryset"] = Car.object.filter(owner=request.user) + kwargs["queryset"] = Car.objects.filter(owner=request.user) return db_field.formfield(**kwargs) return super(MyModelAdmin, self).formfield_for_foreignkey(db_field, request, **kwargs) @@ -847,7 +863,7 @@ provided some extra mapping data that would not otherwise be available:: 'osm_data': self.get_osm_info(), } return super(MyModelAdmin, self).change_view(request, object_id, - extra_context=my_context)) + extra_context=my_context) ``ModelAdmin`` media definitions -------------------------------- @@ -1226,7 +1242,7 @@ or :attr:`AdminSite.login_template` properties. ``AdminSite`` objects ===================== -.. class:: AdminSite +.. class:: AdminSite(name=None) A Django administrative site is represented by an instance of ``django.contrib.admin.sites.AdminSite``; by default, an instance of @@ -1240,6 +1256,14 @@ or add anything you like. Then, simply create an instance of your Python class), and register your models and ``ModelAdmin`` subclasses with it instead of using the default. +.. versionadded:: 1.1 + +When constructing an instance of an ``AdminSite``, you are able to provide +a unique instance name using the ``name`` argument to the constructor. This +instance name is used to identify the instance, especially when +:ref:`reversing admin URLs <admin-reverse-urls>`. If no instance name is +provided, a default instance name of ``admin`` will be used. + ``AdminSite`` attributes ------------------------ @@ -1337,10 +1361,10 @@ a pattern for your new view. .. note:: Any view you render that uses the admin templates, or extends the base - admin template, should include in it's context a variable named - ``admin_site`` that contains the name of the :class:`AdminSite` instance. For - :class:`AdminSite` instances, this means ``self.name``; for :class:`ModelAdmin` - instances, this means ``self.admin_site.name``. + admin template, should provide the ``current_app`` argument to + ``RequestContext`` or ``Context`` when rendering the template. It should + be set to either ``self.name`` if your view is on an ``AdminSite`` or + ``self.admin_site.name`` if your view is on a ``ModelAdmin``. .. _admin-reverse-urls: @@ -1354,37 +1378,31 @@ accessible using Django's :ref:`URL reversing system <naming-url-patterns>`. The :class:`AdminSite` provides the following named URL patterns: - ====================== =============================== ============= - Page URL name Parameters - ====================== =============================== ============= - Index ``admin_index`` - Logout ``admin_logout`` - Password change ``admin_password_change`` - Password change done ``admin_password_change_done`` - i18n javascript ``admin_jsi18n`` - Application index page ``admin_app_list`` ``app_label`` - ====================== =============================== ============= - -These names will be prefixed with the name of the :class:`AdminSite` instance, -plus an underscore. For example, if your :class:`AdminSite` was named -``custom``, then the Logout view would be served using a URL with the name -``custom_admin_logout``. The default :class:`AdminSite` doesn't use a prefix -in it's URL names. + ====================== ======================== ============= + Page URL name Parameters + ====================== ======================== ============= + Index ``index`` + Logout ``logout`` + Password change ``password_change`` + Password change done ``password_change_done`` + i18n javascript ``jsi18n`` + Application index page ``app_list`` ``app_label`` + ====================== ======================== ============= Each :class:`ModelAdmin` instance provides an additional set of named URLs: - ====================== ===================================================== ============= - Page URL name Parameters - ====================== ===================================================== ============= - Changelist ``admin_{{ app_label }}_{{ model_name }}_changelist`` - Add ``admin_{{ app_label }}_{{ model_name }}_add`` - History ``admin_{{ app_label }}_{{ model_name }}_history`` ``object_id`` - Delete ``admin_{{ app_label }}_{{ model_name }}_delete`` ``object_id`` - Change ``admin_{{ app_label }}_{{ model_name }}_change`` ``object_id`` - ====================== ===================================================== ============= + ====================== =============================================== ============= + Page URL name Parameters + ====================== =============================================== ============= + Changelist ``{{ app_label }}_{{ model_name }}_changelist`` + Add ``{{ app_label }}_{{ model_name }}_add`` + History ``{{ app_label }}_{{ model_name }}_history`` ``object_id`` + Delete ``{{ app_label }}_{{ model_name }}_delete`` ``object_id`` + Change ``{{ app_label }}_{{ model_name }}_change`` ``object_id`` + ====================== =============================================== ============= -Again, these names will be prefixed by the name of the :class:`AdminSite` in -which they are deployed. +These named URLs are registered with the application namespace ``admin``, and +with an instance namespace corresponding to the name of the Site instance. So - if you wanted to get a reference to the Change view for a particular ``Choice`` object (from the polls application) in the default admin, you would @@ -1392,8 +1410,16 @@ call:: >>> from django.core import urlresolvers >>> c = Choice.objects.get(...) - >>> change_url = urlresolvers.reverse('admin_polls_choice_change', args=(c.id,)) + >>> change_url = urlresolvers.reverse('admin:polls_choice_change', args=(c.id,)) + +This will find the first registered instance of the admin application (whatever the instance +name), and resolve to the view for changing ``poll.Choice`` instances in that instance. + +If you want to find a URL in a specific admin instance, provide the name of that instance +as a ``current_app`` hint to the reverse call. For example, if you specifically wanted +the admin view from the admin instance named ``custom``, you would need to call:: -However, if the admin instance was named ``custom``, you would need to call:: + >>> change_url = urlresolvers.reverse('custom:polls_choice_change', args=(c.id,)) - >>> change_url = urlresolvers.reverse('custom_admin_polls_choice_change', args=(c.id,)) +For more details, see the documentation on :ref:`reversing namespaced URLs +<topics-http-reversing-url-namespaces>`. diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 94900b3892..8a926afc97 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -177,9 +177,9 @@ The ``ContentTypeManager`` .. method:: models.ContentTypeManager.clear_cache() Clears an internal cache used by - :class:`~django.contrib.contenttypes.models.ContentType>` to keep track + :class:`~django.contrib.contenttypes.models.ContentType` to keep track of which models for which it has created - :class:`django.contrib.contenttypes.models.ContentType>` instances. You + :class:`django.contrib.contenttypes.models.ContentType` instances. You probably won't ever need to call this method yourself; Django will call it automatically when it's needed. diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 9a35b6cb8f..007a7079b7 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -220,7 +220,7 @@ bytestrings (which shouldn't be too difficult) is the recommended solution. Should you decide to use ``utf8_bin`` collation for some of your tables with MySQLdb 1.2.1p2, you should still use ``utf8_collation_ci_swedish`` (the default) collation for the :class:`django.contrib.sessions.models.Session` -table (usually called ``django_session`` and the table +table (usually called ``django_session``) and the :class:`django.contrib.admin.models.LogEntry` table (usually called ``django_admin_log``). Those are the two standard tables that use :class:`~django.db.model.TextField` internally. diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index e532971179..4bb6a7c444 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -275,7 +275,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: ``CheckboxInput`` * Empty value: ``False`` * Normalizes to: A Python ``True`` or ``False`` value. - * Validates that the check box is checked (i.e. the value is ``True``) if + * Validates that the value is ``True`` (e.g. the check box is checked) if the field has ``required=True``. * Error message keys: ``required`` @@ -287,9 +287,10 @@ For each field, we describe the default widget used if you don't specify .. note:: Since all ``Field`` subclasses have ``required=True`` by default, the - validation condition here is important. If you want to include a checkbox - in your form that can be either checked or unchecked, you must remember to - pass in ``required=False`` when creating the ``BooleanField``. + validation condition here is important. If you want to include a boolean + in your form that can be either ``True`` or ``False`` (e.g. a checked or + unchecked checkbox), you must remember to pass in ``required=False`` when + creating the ``BooleanField``. ``CharField`` ~~~~~~~~~~~~~ @@ -328,7 +329,7 @@ Takes one extra required argument: An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this field. - + ``TypedChoiceField`` ~~~~~~~~~~~~~~~~~~~~ @@ -437,7 +438,7 @@ If no ``input_formats`` argument is provided, the default input formats are:: ``min_value``, ``max_digits``, ``max_decimal_places``, ``max_whole_digits`` -Takes four optional arguments: +Takes four optional arguments: .. attribute:: DecimalField.max_value .. attribute:: DecimalField.min_value @@ -449,7 +450,7 @@ Takes four optional arguments: The maximum number of digits (those before the decimal point plus those after the decimal point, with leading zeros stripped) permitted in the value. - + .. attribute:: DecimalField.decimal_places The maximum number of decimal places permitted. @@ -522,18 +523,18 @@ extra arguments; only ``path`` is required: A regular expression pattern; only files with names matching this expression will be allowed as choices. -``FloatField`` -~~~~~~~~~~~~~~ +``FloatField`` +~~~~~~~~~~~~~~ + + * Default widget: ``TextInput`` + * Empty value: ``None`` + * Normalizes to: A Python float. + * Validates that the given value is an float. Leading and trailing + whitespace is allowed, as in Python's ``float()`` function. + * Error message keys: ``required``, ``invalid``, ``max_value``, + ``min_value`` - * Default widget: ``TextInput`` - * Empty value: ``None`` - * Normalizes to: A Python float. - * Validates that the given value is an float. Leading and trailing - whitespace is allowed, as in Python's ``float()`` function. - * Error message keys: ``required``, ``invalid``, ``max_value``, - ``min_value`` - -Takes two optional arguments for validation, ``max_value`` and ``min_value``. +Takes two optional arguments for validation, ``max_value`` and ``min_value``. These control the range of values permitted in the field. ``ImageField`` @@ -779,10 +780,10 @@ example:: (which is ``"---------"`` by default) with the ``empty_label`` attribute, or you can disable the empty label entirely by setting ``empty_label`` to ``None``:: - + # A custom empty label field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)") - + # No empty label field2 = forms.ModelChoiceField(queryset=..., empty_label=None) diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 5125f6e064..ff51df9e8f 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -122,17 +122,10 @@ Reverse proxy middleware .. class:: django.middleware.http.SetRemoteAddrFromForwardedFor -Sets ``request.META['REMOTE_ADDR']`` based on -``request.META['HTTP_X_FORWARDED_FOR']``, if the latter is set. This is useful -if you're sitting behind a reverse proxy that causes each request's -``REMOTE_ADDR`` to be set to ``127.0.0.1``. +.. versionchanged: 1.1 -**Important note:** This does NOT validate ``HTTP_X_FORWARDED_FOR``. If you're -not behind a reverse proxy that sets ``HTTP_X_FORWARDED_FOR`` automatically, do -not use this middleware. Anybody can spoof the value of -``HTTP_X_FORWARDED_FOR``, and because this sets ``REMOTE_ADDR`` based on -``HTTP_X_FORWARDED_FOR``, that means anybody can "fake" their IP address. Only -use this when you can absolutely trust the value of ``HTTP_X_FORWARDED_FOR``. +This middleware was removed in Django 1.1. See :ref:`the release notes +<removed-setremoteaddrfromforwardedfor-middleware>` for details. Locale middleware ----------------- diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index c6509ece3d..7a0606dafe 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -188,6 +188,46 @@ almost always do the right thing and trying to override that will lead to errors that are difficult to track down. This feature is for advanced use only. +Updating attributes based on existing fields +-------------------------------------------- + +Sometimes you'll need to perform a simple arithmetic task on a field, such +as incrementing or decrementing the current value. The obvious way to +achieve this is to do something like:: + + >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') + >>> product.number_sold += 1 + >>> product.save() + +If the old ``number_sold`` value retrieved from the database was 10, then +the value of 11 will be written back to the database. + +This can be optimized slightly by expressing the update relative to the +original field value, rather than as an explicit assignment of a new value. +Django provides :ref:`F() expressions <query-expressions>` as a way of +performing this kind of relative update. Using ``F()`` expressions, the +previous example would be expressed as:: + + >>> from django.db.models import F + >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') + >>> product.number_sold = F('number_sold') + 1 + >>> product.save() + +This approach doesn't use the initial value from the database. Instead, it +makes the database do the update based on whatever value is current at the +time that the save() is executed. + +Once the object has been saved, you must reload the object in order to access +the actual value that was applied to the updated field:: + + >>> product = Products.objects.get(pk=product.pk) + >>> print product.number_sold + 42 + +For more details, see the documentation on :ref:`F() expressions +<query-expressions>` and their :ref:`use in update queries +<topics-db-queries-update>`. + Deleting objects ================ @@ -196,7 +236,7 @@ Deleting objects Issues a SQL ``DELETE`` for the object. This only deletes the object in the database; the Python instance will still be around, and will still have data in its fields. - + For more details, including how to delete objects in bulk, see :ref:`topics-db-queries-delete`. diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 348486b341..f78ebc506a 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -668,7 +668,7 @@ of the arguments is required, but you should use at least one of them. The resulting SQL of the above example would be:: - SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) + SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count FROM blog_blog; Note that the parenthesis required by most database engines around diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 05097b7e59..e3260a96f8 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -86,9 +86,16 @@ Rendering a context Once you have a compiled ``Template`` object, you can render a context -- or multiple contexts -- with it. The ``Context`` class lives at -``django.template.Context``, and the constructor takes one (optional) -argument: a dictionary mapping variable names to variable values. Call the -``Template`` object's ``render()`` method with the context to "fill" the +``django.template.Context``, and the constructor takes two (optional) +arguments: + + * A dictionary mapping variable names to variable values. + + * The name of the current application. This application name is used + to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`. + If you're not using namespaced URLs, you can ignore this argument. + +Call the ``Template`` object's ``render()`` method with the context to "fill" the template:: >>> from django.template import Context, Template @@ -549,13 +556,13 @@ Here are the template loaders that come with Django: Note that the loader performs an optimization when it is first imported: It caches a list of which :setting:`INSTALLED_APPS` packages have a ``templates`` subdirectory. - + This loader is enabled by default. ``django.template.loaders.eggs.load_template_source`` Just like ``app_directories`` above, but it loads templates from Python eggs rather than from the filesystem. - + This loader is disabled by default. Django uses the template loaders in order according to the diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index ba45a6f1c4..169688dd17 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -101,6 +101,14 @@ You can use any number of values in a ``{% cycle %}`` tag, separated by spaces. Values enclosed in single (``'``) or double quotes (``"``) are treated as string literals, while values without quotes are treated as template variables. +Note that the variables included in the cycle will not be escaped. This is +because template tags do not escape their content. If you want to escape the +variables in the cycle, you must do so explicitly:: + + {% filter force_escape %} + {% cycle var1 var2 var3 %} + {% endfilter %} + For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior old syntax from previous Django versions. You shouldn't use this in any new projects, but for the sake of the people who are still using it, here's what it @@ -160,8 +168,9 @@ Sample usage:: firstof ~~~~~~~ -Outputs the first variable passed that is not False. Outputs nothing if all the -passed variables are False. +Outputs the first variable passed that is not False, without escaping. + +Outputs nothing if all the passed variables are False. Sample usage:: @@ -170,11 +179,11 @@ Sample usage:: This is equivalent to:: {% if var1 %} - {{ var1 }} + {{ var1|safe }} {% else %}{% if var2 %} - {{ var2 }} + {{ var2|safe }} {% else %}{% if var3 %} - {{ var3 }} + {{ var3|safe }} {% endif %}{% endif %}{% endif %} You can also use a literal string as a fallback value in case all @@ -182,6 +191,14 @@ passed variables are False:: {% firstof var1 var2 var3 "fallback value" %} +Note that the variables included in the firstof tag will not be escaped. This +is because template tags do not escape their content. If you want to escape +the variables in the firstof tag, you must do so explicitly:: + + {% filter force_escape %} + {% firstof var1 var2 var3 "fallback value" %} + {% endfilter %} + .. templatetag:: for for @@ -778,6 +795,16 @@ missing. In practice you'll use this to link to views that are optional:: <a href="{{ the_url }}">Link to optional stuff</a> {% endif %} +.. versionadded:: 1.1 + +If you'd like to retrieve a namespaced URL, specify the fully qualified name:: + + {% url myapp:view-name %} + +This will follow the normal :ref:`namespaced URL resolution strategy +<topics-http-reversing-url-namespaces>`, including using any hints provided +by the context as to the current application. + .. templatetag:: widthratio widthratio |
