diff options
| author | Luke Plant <L.Plant.98@cantab.net> | 2011-10-10 17:32:33 +0000 |
|---|---|---|
| committer | Luke Plant <L.Plant.98@cantab.net> | 2011-10-10 17:32:33 +0000 |
| commit | c61987d75ad9bc5233257f46a8246bb9d63bbbe1 (patch) | |
| tree | 8effcabf40a7e1718973456c693d2decc5a8e8d3 /docs/ref/contrib/admin | |
| parent | af244e47ccc88860fe928fec96c7873e3e4017fe (diff) | |
Removed use of non-standard indentation rules in docs, and the custom transform that supported them.
Doc writers should be aware that we are now back to normal ReST rules
regarding blockquotes.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16955 bcc190cf-cafb-0310-a4f2-bffc1f526a37
Diffstat (limited to 'docs/ref/contrib/admin')
| -rw-r--r-- | docs/ref/contrib/admin/index.txt | 534 |
1 files changed, 267 insertions, 267 deletions
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 875c234f03..9c5ba2ca67 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -16,31 +16,31 @@ Overview There are seven steps in activating the Django admin site: - 1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS` - setting. +1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS` + setting. - 2. The admin has four dependencies - :mod:`django.contrib.auth`, - :mod:`django.contrib.contenttypes`, - :mod:`django.contrib.messages` and - :mod:`django.contrib.sessions`. If these applications are not - in your :setting:`INSTALLED_APPS` list, add them. +2. The admin has four dependencies - :mod:`django.contrib.auth`, + :mod:`django.contrib.contenttypes`, + :mod:`django.contrib.messages` and + :mod:`django.contrib.sessions`. If these applications are not + in your :setting:`INSTALLED_APPS` list, add them. - 3. Add ``django.contrib.messages.context_processors.messages`` to - :setting:`TEMPLATE_CONTEXT_PROCESSORS` and - :class:`~django.contrib.messages.middleware.MessageMiddleware` to - :setting:`MIDDLEWARE_CLASSES`. +3. Add ``django.contrib.messages.context_processors.messages`` to + :setting:`TEMPLATE_CONTEXT_PROCESSORS` and + :class:`~django.contrib.messages.middleware.MessageMiddleware` to + :setting:`MIDDLEWARE_CLASSES`. - 4. Determine which of your application's models should be editable in the - admin interface. +4. Determine which of your application's models should be editable in the + admin interface. - 5. For each of those models, optionally create a ``ModelAdmin`` class that - encapsulates the customized admin functionality and options for that - particular model. +5. For each of those models, optionally create a ``ModelAdmin`` class that + encapsulates the customized admin functionality and options for that + particular model. - 6. Instantiate an ``AdminSite`` and tell it about each of your models and - ``ModelAdmin`` classes. +6. Instantiate an ``AdminSite`` and tell it about each of your models and + ``ModelAdmin`` classes. - 7. Hook the ``AdminSite`` instance into your URLconf. +7. Hook the ``AdminSite`` instance into your URLconf. Other topics ------------ @@ -239,54 +239,54 @@ subclass:: The ``field_options`` dictionary can have the following keys: - * ``fields`` - A tuple of field names to display in this fieldset. This key is - required. + * ``fields`` + A tuple of field names to display in this fieldset. This key is + required. - Example:: + Example:: - { - 'fields': ('first_name', 'last_name', 'address', 'city', 'state'), - } + { + 'fields': ('first_name', 'last_name', 'address', 'city', 'state'), + } - Just like with the :attr:`~ModelAdmin.fields` option, to display - multiple fields on the same line, wrap those fields in their own - tuple. In this example, the ``first_name`` and ``last_name`` fields - will display on the same line:: + Just like with the :attr:`~ModelAdmin.fields` option, to display + multiple fields on the same line, wrap those fields in their own + tuple. In this example, the ``first_name`` and ``last_name`` fields + will display on the same line:: - { - 'fields': (('first_name', 'last_name'), 'address', 'city', 'state'), - } + { + 'fields': (('first_name', 'last_name'), 'address', 'city', 'state'), + } - .. versionadded:: 1.2 + .. versionadded:: 1.2 - ``fields`` can contain values defined in - :attr:`~ModelAdmin.readonly_fields` to be displayed as read-only. + ``fields`` can contain values defined in + :attr:`~ModelAdmin.readonly_fields` to be displayed as read-only. - * ``classes`` - A list containing extra CSS classes to apply to the fieldset. + * ``classes`` + A list containing extra CSS classes to apply to the fieldset. - Example:: + Example:: - { - 'classes': ['wide', 'extrapretty'], - } + { + 'classes': ['wide', 'extrapretty'], + } - Two useful classes defined by the default admin site stylesheet are - ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style - will be initially collapsed in the admin and replaced with a small - "click to expand" link. Fieldsets with the ``wide`` style will be - given extra horizontal space. + Two useful classes defined by the default admin site stylesheet are + ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style + will be initially collapsed in the admin and replaced with a small + "click to expand" link. Fieldsets with the ``wide`` style will be + given extra horizontal space. - * ``description`` - A string of optional extra text to be displayed at the top of each - fieldset, under the heading of the fieldset. + * ``description`` + A string of optional extra text to be displayed at the top of each + fieldset, under the heading of the fieldset. - Note that this value is *not* HTML-escaped when it's displayed in - the admin interface. This lets you include HTML if you so desire. - Alternatively you can use plain text and - ``django.utils.html.escape()`` to escape any HTML special - characters. + Note that this value is *not* HTML-escaped when it's displayed in + the admin interface. This lets you include HTML if you so desire. + Alternatively you can use plain text and + ``django.utils.html.escape()`` to escape any HTML special + characters. .. attribute:: ModelAdmin.filter_horizontal @@ -400,129 +400,129 @@ subclass:: You have four possible values that can be used in ``list_display``: - * A field of the model. For example:: + * A field of the model. For example:: - class PersonAdmin(admin.ModelAdmin): - list_display = ('first_name', 'last_name') + class PersonAdmin(admin.ModelAdmin): + list_display = ('first_name', 'last_name') - * A callable that accepts one parameter for the model instance. For - example:: + * A callable that accepts one parameter for the model instance. For + example:: - def upper_case_name(obj): - return ("%s %s" % (obj.first_name, obj.last_name)).upper() - upper_case_name.short_description = 'Name' + def upper_case_name(obj): + return ("%s %s" % (obj.first_name, obj.last_name)).upper() + upper_case_name.short_description = 'Name' - class PersonAdmin(admin.ModelAdmin): - list_display = (upper_case_name,) + class PersonAdmin(admin.ModelAdmin): + list_display = (upper_case_name,) - * A string representing an attribute on the ``ModelAdmin``. This - behaves same as the callable. For example:: + * A string representing an attribute on the ``ModelAdmin``. This + behaves same as the callable. For example:: - class PersonAdmin(admin.ModelAdmin): - list_display = ('upper_case_name',) + class PersonAdmin(admin.ModelAdmin): + list_display = ('upper_case_name',) - def upper_case_name(self, obj): - return ("%s %s" % (obj.first_name, obj.last_name)).upper() - upper_case_name.short_description = 'Name' + def upper_case_name(self, obj): + return ("%s %s" % (obj.first_name, obj.last_name)).upper() + upper_case_name.short_description = 'Name' - * A string representing an attribute on the model. This behaves almost - the same as the callable, but ``self`` in this context is the model - instance. Here's a full model example:: + * A string representing an attribute on the model. This behaves almost + the same as the callable, but ``self`` in this context is the model + instance. Here's a full model example:: - class Person(models.Model): - name = models.CharField(max_length=50) - birthday = models.DateField() + class Person(models.Model): + name = models.CharField(max_length=50) + birthday = models.DateField() - def decade_born_in(self): - return self.birthday.strftime('%Y')[:3] + "0's" - decade_born_in.short_description = 'Birth decade' + def decade_born_in(self): + return self.birthday.strftime('%Y')[:3] + "0's" + decade_born_in.short_description = 'Birth decade' - class PersonAdmin(admin.ModelAdmin): - list_display = ('name', 'decade_born_in') + class PersonAdmin(admin.ModelAdmin): + list_display = ('name', 'decade_born_in') A few special cases to note about ``list_display``: - * If the field is a ``ForeignKey``, Django will display the - ``__unicode__()`` of the related object. + * If the field is a ``ForeignKey``, Django will display the + ``__unicode__()`` of the related object. - * ``ManyToManyField`` fields aren't supported, because that would - entail executing a separate SQL statement for each row in the table. - If you want to do this nonetheless, give your model a custom method, - and add that method's name to ``list_display``. (See below for more - on custom methods in ``list_display``.) + * ``ManyToManyField`` fields aren't supported, because that would + entail executing a separate SQL statement for each row in the table. + If you want to do this nonetheless, give your model a custom method, + and add that method's name to ``list_display``. (See below for more + on custom methods in ``list_display``.) - * If the field is a ``BooleanField`` or ``NullBooleanField``, Django - will display a pretty "on" or "off" icon instead of ``True`` or - ``False``. + * If the field is a ``BooleanField`` or ``NullBooleanField``, Django + will display a pretty "on" or "off" icon instead of ``True`` or + ``False``. - * If the string given is a method of the model, ``ModelAdmin`` or a - callable, Django will HTML-escape the output by default. If you'd - rather not escape the output of the method, give the method an - ``allow_tags`` attribute whose value is ``True``. + * If the string given is a method of the model, ``ModelAdmin`` or a + callable, Django will HTML-escape the output by default. If you'd + rather not escape the output of the method, give the method an + ``allow_tags`` attribute whose value is ``True``. - Here's a full example model:: + Here's a full example model:: - class Person(models.Model): - first_name = models.CharField(max_length=50) - last_name = models.CharField(max_length=50) - color_code = models.CharField(max_length=6) + class Person(models.Model): + first_name = models.CharField(max_length=50) + last_name = models.CharField(max_length=50) + color_code = models.CharField(max_length=6) - def colored_name(self): - return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name) - colored_name.allow_tags = True + def colored_name(self): + return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name) + colored_name.allow_tags = True - class PersonAdmin(admin.ModelAdmin): - list_display = ('first_name', 'last_name', 'colored_name') + class PersonAdmin(admin.ModelAdmin): + list_display = ('first_name', 'last_name', 'colored_name') - * If the string given is a method of the model, ``ModelAdmin`` or a - callable that returns True or False Django will display a pretty - "on" or "off" icon if you give the method a ``boolean`` attribute - whose value is ``True``. + * If the string given is a method of the model, ``ModelAdmin`` or a + callable that returns True or False Django will display a pretty + "on" or "off" icon if you give the method a ``boolean`` attribute + whose value is ``True``. - Here's a full example model:: + Here's a full example model:: - class Person(models.Model): - first_name = models.CharField(max_length=50) - birthday = models.DateField() + class Person(models.Model): + first_name = models.CharField(max_length=50) + birthday = models.DateField() - def born_in_fifties(self): - return self.birthday.strftime('%Y')[:3] == '195' - born_in_fifties.boolean = True + def born_in_fifties(self): + return self.birthday.strftime('%Y')[:3] == '195' + born_in_fifties.boolean = True - class PersonAdmin(admin.ModelAdmin): - list_display = ('name', 'born_in_fifties') + class PersonAdmin(admin.ModelAdmin): + list_display = ('name', 'born_in_fifties') - * The ``__str__()`` and ``__unicode__()`` methods are just as valid in - ``list_display`` as any other model method, so it's perfectly OK to - do this:: + * The ``__str__()`` and ``__unicode__()`` methods are just as valid in + ``list_display`` as any other model method, so it's perfectly OK to + do this:: - list_display = ('__unicode__', 'some_other_field') + list_display = ('__unicode__', 'some_other_field') - * 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). + * 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. + 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:: + For example:: - class Person(models.Model): - first_name = models.CharField(max_length=50) - color_code = models.CharField(max_length=6) + class Person(models.Model): + first_name = models.CharField(max_length=50) + color_code = models.CharField(max_length=6) - def colored_first_name(self): - return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name) - colored_first_name.allow_tags = True - colored_first_name.admin_order_field = 'first_name' + def colored_first_name(self): + return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name) + colored_first_name.allow_tags = True + colored_first_name.admin_order_field = 'first_name' - class PersonAdmin(admin.ModelAdmin): - list_display = ('first_name', 'colored_first_name') + class PersonAdmin(admin.ModelAdmin): + list_display = ('first_name', 'colored_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. + The above will tell Django to order by the ``first_name`` field when + trying to sort by ``colored_first_name`` in the admin. .. attribute:: ModelAdmin.list_display_links @@ -561,12 +561,12 @@ subclass:: ``list_editable`` interacts with a couple of other options in particular ways; you should note the following rules: - * Any field in ``list_editable`` must also be in ``list_display``. - You can't edit a field that's not displayed! + * Any field in ``list_editable`` must also be in ``list_display``. + You can't edit a field that's not displayed! - * The same field can't be listed in both ``list_editable`` and - ``list_display_links`` -- a field can't be both a form and - a link. + * The same field can't be listed in both ``list_editable`` and + ``list_display_links`` -- a field can't be both a form and + a link. You'll get a validation error if either of these rules are broken. @@ -582,119 +582,119 @@ subclass:: ``list_filter`` should be a list of elements, where each element should be of one of the following types: - * a field name, where the specified field should be either a - ``BooleanField``, ``CharField``, ``DateField``, ``DateTimeField``, - ``IntegerField``, ``ForeignKey`` or ``ManyToManyField``, for example:: + * a field name, where the specified field should be either a + ``BooleanField``, ``CharField``, ``DateField``, ``DateTimeField``, + ``IntegerField``, ``ForeignKey`` or ``ManyToManyField``, for example:: - class PersonAdmin(ModelAdmin): - list_filter = ('is_staff', 'company') + class PersonAdmin(ModelAdmin): + list_filter = ('is_staff', 'company') - .. versionadded:: 1.3 + .. versionadded:: 1.3 - Field names in ``list_filter`` can also span relations - using the ``__`` lookup, for example:: + Field names in ``list_filter`` can also span relations + using the ``__`` lookup, for example:: - class PersonAdmin(UserAdmin): - list_filter = ('company__name',) + class PersonAdmin(UserAdmin): + list_filter = ('company__name',) - * a class inheriting from :mod:`django.contrib.admin.SimpleListFilter`, - which you need to provide the ``title`` and ``parameter_name`` - attributes to and override the ``lookups`` and ``queryset`` methods, - e.g.:: + * a class inheriting from :mod:`django.contrib.admin.SimpleListFilter`, + which you need to provide the ``title`` and ``parameter_name`` + attributes to and override the ``lookups`` and ``queryset`` methods, + e.g.:: - from django.utils.translation import ugettext_lazy as _ - from django.contrib.admin import SimpleListFilter + from django.utils.translation import ugettext_lazy as _ + from django.contrib.admin import SimpleListFilter - class DecadeBornListFilter(SimpleListFilter): - # Human-readable title which will be displayed in the - # right admin sidebar just above the filter options. - title = _('decade born') + class DecadeBornListFilter(SimpleListFilter): + # Human-readable title which will be displayed in the + # right admin sidebar just above the filter options. + title = _('decade born') - # Parameter for the filter that will be used in the URL query. - parameter_name = 'decade' + # Parameter for the filter that will be used in the URL query. + parameter_name = 'decade' - def lookups(self, request, model_admin): - """ - Returns a list of tuples. The first element in each - tuple is the coded value for the option that will - appear in the URL query. The second element is the - human-readable name for the option that will appear - in the right sidebar. - """ - return ( - ('80s', _('in the eighties')), - ('90s', _('in the nineties')), - ) + def lookups(self, request, model_admin): + """ + Returns a list of tuples. The first element in each + tuple is the coded value for the option that will + appear in the URL query. The second element is the + human-readable name for the option that will appear + in the right sidebar. + """ + return ( + ('80s', _('in the eighties')), + ('90s', _('in the nineties')), + ) - def queryset(self, request, queryset): - """ - Returns the filtered queryset based on the value - provided in the query string and retrievable via - `self.value()`. - """ - # Compare the requested value (either '80s' or 'other') - # to decide how to filter the queryset. - if self.value() == '80s': - return queryset.filter(birthday__year__gte=1980, - birthday__year__lte=1989) - if self.value() == '90s': - return queryset.filter(birthday__year__gte=1990, - birthday__year__lte=1999) + def queryset(self, request, queryset): + """ + Returns the filtered queryset based on the value + provided in the query string and retrievable via + `self.value()`. + """ + # Compare the requested value (either '80s' or 'other') + # to decide how to filter the queryset. + if self.value() == '80s': + return queryset.filter(birthday__year__gte=1980, + birthday__year__lte=1989) + if self.value() == '90s': + return queryset.filter(birthday__year__gte=1990, + birthday__year__lte=1999) - class PersonAdmin(ModelAdmin): - list_filter = (DecadeBornListFilter,) + class PersonAdmin(ModelAdmin): + list_filter = (DecadeBornListFilter,) - .. note:: + .. note:: - As a convenience, the ``HttpRequest`` object is passed to the - ``lookups`` and ``queryset`` methods, for example:: + As a convenience, the ``HttpRequest`` object is passed to the + ``lookups`` and ``queryset`` methods, for example:: - class AuthDecadeBornListFilter(DecadeBornListFilter): + class AuthDecadeBornListFilter(DecadeBornListFilter): - def lookups(self, request, model_admin): - if request.user.is_superuser: - return super(AuthDecadeBornListFilter, - self).lookups(request, model_admin) + def lookups(self, request, model_admin): + if request.user.is_superuser: + return super(AuthDecadeBornListFilter, + self).lookups(request, model_admin) - def queryset(self, request, queryset): - if request.user.is_superuser: - return super(AuthDecadeBornListFilter, - self).queryset(request, queryset) + def queryset(self, request, queryset): + if request.user.is_superuser: + return super(AuthDecadeBornListFilter, + self).queryset(request, queryset) - Also as a convenience, the ``ModelAdmin`` object is passed to - the ``lookups`` method, for example if you want to base the - lookups on the available data:: + Also as a convenience, the ``ModelAdmin`` object is passed to + the ``lookups`` method, for example if you want to base the + lookups on the available data:: - class AdvancedDecadeBornListFilter(DecadeBornListFilter): + class AdvancedDecadeBornListFilter(DecadeBornListFilter): - def lookups(self, request, model_admin): - """ - Only show the lookups if there actually is - anyone born in the corresponding decades. - """ - qs = model_admin.queryset(request) - if qs.filter(birthday__year__gte=1980, - birthday__year__lte=1989).exists(): - yield ('80s', _('in the eighties')) - if qs.filter(birthday__year__gte=1990, - birthday__year__lte=1999).exists(): - yield ('90s', _('in the nineties')) + def lookups(self, request, model_admin): + """ + Only show the lookups if there actually is + anyone born in the corresponding decades. + """ + qs = model_admin.queryset(request) + if qs.filter(birthday__year__gte=1980, + birthday__year__lte=1989).exists(): + yield ('80s', _('in the eighties')) + if qs.filter(birthday__year__gte=1990, + birthday__year__lte=1999).exists(): + yield ('90s', _('in the nineties')) - * a tuple, where the first element is a field name and the second - element is a class inheriting from - :mod:`django.contrib.admin.FieldListFilter`, for example:: + * a tuple, where the first element is a field name and the second + element is a class inheriting from + :mod:`django.contrib.admin.FieldListFilter`, for example:: - from django.contrib.admin import BooleanFieldListFilter + from django.contrib.admin import BooleanFieldListFilter - class PersonAdmin(ModelAdmin): - list_filter = ( - ('is_staff', BooleanFieldListFilter), - ) + class PersonAdmin(ModelAdmin): + list_filter = ( + ('is_staff', BooleanFieldListFilter), + ) - .. note:: + .. note:: - The ``FieldListFilter`` API is currently considered internal - and prone to refactoring. + The ``FieldListFilter`` API is currently considered internal + and prone to refactoring. .. attribute:: ModelAdmin.list_max_show_all @@ -1076,11 +1076,11 @@ templates used by the :class:`ModelAdmin` views: However, the ``self.my_view`` function registered above suffers from two problems: - * It will *not* perform any 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. + * It will *not* perform any 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 @@ -1356,8 +1356,8 @@ information. Django provides two subclasses of ``InlineModelAdmin`` and they are: - * :class:`~django.contrib.admin.TabularInline` - * :class:`~django.contrib.admin.StackedInline` + * :class:`~django.contrib.admin.TabularInline` + * :class:`~django.contrib.admin.StackedInline` The difference between these two is merely the template used to render them. @@ -1735,11 +1735,11 @@ Templates which may be overridden per app or model Not every template in ``contrib/admin/templates/admin`` may be overridden per app or per model. The following can: - * ``app_index.html`` - * ``change_form.html`` - * ``change_list.html`` - * ``delete_confirmation.html`` - * ``object_history.html`` +* ``app_index.html`` +* ``change_form.html`` +* ``change_list.html`` +* ``delete_confirmation.html`` +* ``object_history.html`` For those templates that cannot be overridden in this way, you may still override them for your entire project. Just place the new version in your @@ -1920,28 +1920,28 @@ 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 ``index`` - Logout ``logout`` - Password change ``password_change`` - Password change done ``password_change_done`` - i18n javascript ``jsi18n`` - Application index page ``app_list`` ``app_label`` - ====================== ======================== ============= +====================== ======================== ============= +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 ``{{ 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`` - ====================== =============================================== ============= +====================== =============================================== ============= +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`` +====================== =============================================== ============= These named URLs are registered with the application namespace ``admin``, and with an instance namespace corresponding to the name of the Site instance. |
