Ticket #15003: admin-doc-updates.diff

File admin-doc-updates.diff, 17.9 KB (added by Adam Vandenberg, 14 years ago)

  • docs/ref/contrib/admin/index.txt 

    diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 326bca4..5126036 100644
    a b There are six steps in activating the Django admin site:  
    2626    1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
    2727       setting.
    2828
    29     2. Admin has two dependencies - ``django.contrib.auth`` and
    30        ``django.contrib.contenttypes``. If these applications are not
     29    2. Admin has two dependencies - :mod:`django.contrib.auth` and
     30       :mod:`django.contrib.contenttypes`. If these applications are not
    3131       in your :setting:`INSTALLED_APPS` list, add them.
    3232
    3333    3. Determine which of your application's models should be editable in the
    … … Other topics  
    8787
    8888            admin.site.register(Author)
    8989
    90 ``ModelAdmin`` Options
     90``ModelAdmin`` options
    9191----------------------
    9292
    9393The ``ModelAdmin`` is very flexible. It has several options for dealing with
    … … subclass::  
    9797    class AuthorAdmin(admin.ModelAdmin):
    9898        date_hierarchy = 'pub_date'
    9999
     100.. attribute:: ModelAdmin.actions
     101
     102    A list of actions to make available on the change list page. See
     103    :doc:`/ref/contrib/admin/actions` for details.
     104
     105.. attribute:: ModelAdmin.actions_on_top
     106.. attribute:: ModelAdmin.actions_on_bottom
     107
     108    Controls where on the page the actions bar appears. By default, the admin
     109    changelist displays actions at the top of the page (``actions_on_top = True;
     110    actions_on_bottom = False``).
     111
     112.. attribute:: ModelAdmin.actions_selection_counter
     113
     114    .. versionadded:: 1.2
     115
     116    Controls whether a selection counter is display next to the action dropdown.
     117    By default, the admin changelist will display it
     118    (``actions_selection_counter = True``).
     119
    100120.. attribute:: ModelAdmin.date_hierarchy
    101121
    102122    Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField``
    … … subclass::  
    109129
    110130    .. versionadded:: 1.3
    111131
    112         This will intelligently populate itself based on available data,
    113         e.g. if all the dates are in one month, it'll show the day-level
    114         drill-down only.
     132    This will intelligently populate itself based on available data,
     133    e.g. if all the dates are in one month, it'll show the day-level
     134    drill-down only.
    115135
    116 .. attribute:: ModelAdmin.form
     136.. attribute:: ModelAdmin.exclude
    117137
    118     By default a ``ModelForm`` is dynamically created for your model. It is
    119     used to create the form presented on both the add/change pages. You can
    120     easily provide your own ``ModelForm`` to override any default form behavior
    121     on the add/change pages.
     138    This attribute, if given, should be a list of field names to exclude from
     139    the form.
    122140
    123     For an example see the section `Adding custom validation to the admin`_.
     141    For example, let's consider the following model::
     142
     143        class Author(models.Model):
     144            name = models.CharField(max_length=100)
     145            title = models.CharField(max_length=3)
     146            birth_date = models.DateField(blank=True, null=True)
     147
     148    If you want a form for the ``Author`` model that includes only the ``name``
     149    and ``title`` fields, you would specify ``fields`` or ``exclude`` like
     150    this::
     151
     152        class AuthorAdmin(admin.ModelAdmin):
     153            fields = ('name', 'title')
     154
     155        class AuthorAdmin(admin.ModelAdmin):
     156            exclude = ('birth_date',)
     157
     158    Since the Author model only has three fields, ``name``, ``title``, and
     159    ``birth_date``, the forms resulting from the above declarations will
     160    contain exactly the same fields.
     161
     162.. attribute:: ModelAdmin.fields
     163
     164    Use this option as an alternative to ``fieldsets`` if the layout does not
     165    matter and if you want to only show a subset of the available fields in the
     166    form. For example, you could define a simpler version of the admin form for
     167    the ``django.contrib.flatpages.FlatPage`` model as follows::
     168
     169        class FlatPageAdmin(admin.ModelAdmin):
     170            fields = ('url', 'title', 'content')
     171
     172    In the above example, only the fields 'url', 'title' and 'content' will be
     173    displayed, sequentially, in the form.
     174
     175    .. versionadded:: 1.2
     176
     177    ``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields`
     178    to be displayed as read-only.
     179
     180    .. admonition:: Note
     181
     182        This ``fields`` option should not be confused with the ``fields``
     183        dictionary key that is within the ``fieldsets`` option, as described in
     184        the previous section.
    124185
    125186.. attribute:: ModelAdmin.fieldsets
    126187
    … … subclass::  
    207268            ``django.utils.html.escape()`` to escape any HTML special
    208269            characters.
    209270
    210 .. attribute:: ModelAdmin.fields
    211 
    212     Use this option as an alternative to ``fieldsets`` if the layout does not
    213     matter and if you want to only show a subset of the available fields in the
    214     form. For example, you could define a simpler version of the admin form for
    215     the ``django.contrib.flatpages.FlatPage`` model as follows::
     271.. attribute:: ModelAdmin.filter_horizontal
    216272
    217         class FlatPageAdmin(admin.ModelAdmin):
    218             fields = ('url', 'title', 'content')
     273    Use a nifty unobtrusive JavaScript "filter" interface instead of the
     274    usability-challenged ``<select multiple>`` in the admin form. The value is
     275    a list of fields that should be displayed as a horizontal filter interface.
     276    See ``filter_vertical`` to use a vertical interface.
    219277
    220     In the above example, only the fields 'url', 'title' and 'content' will be
    221     displayed, sequentially, in the form.
     278.. attribute:: ModelAdmin.filter_vertical
    222279
    223     .. versionadded:: 1.2
     280    Same as ``filter_horizontal``, but is a vertical display of the filter
     281    interface.
    224282
    225     ``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields`
    226     to be displayed as read-only.
     283.. attribute:: ModelAdmin.form
    227284
    228     .. admonition:: Note
     285    By default a ``ModelForm`` is dynamically created for your model. It is
     286    used to create the form presented on both the add/change pages. You can
     287    easily provide your own ``ModelForm`` to override any default form behavior
     288    on the add/change pages.
    229289
    230         This ``fields`` option should not be confused with the ``fields``
    231         dictionary key that is within the ``fieldsets`` option, as described in
    232         the previous section.
     290    For an example see the section `Adding custom validation to the admin`_.
    233291
    234 .. attribute:: ModelAdmin.exclude
     292.. attribute:: ModelAdmin.formfield_overrides
    235293
    236     This attribute, if given, should be a list of field names to exclude from
    237     the form.
     294    This provides a quick-and-dirty way to override some of the
     295    :class:`~django.forms.Field` options for use in the admin.
     296    ``formfield_overrides`` is a dictionary mapping a field class to a dict of
     297    arguments to pass to the field at construction time.
    238298
    239     For example, let's consider the following model::
     299    Since that's a bit abstract, let's look at a concrete example. The most
     300    common use of ``formfield_overrides`` is to add a custom widget for a
     301    certain type of field. So, imagine we've written a ``RichTextEditorWidget``
     302    that we'd like to use for large text fields instead of the default
     303    ``<textarea>``. Here's how we'd do that::
    240304
    241         class Author(models.Model):
    242             name = models.CharField(max_length=100)
    243             title = models.CharField(max_length=3)
    244             birth_date = models.DateField(blank=True, null=True)
     305        from django.db import models
     306        from django.contrib import admin
    245307
    246     If you want a form for the ``Author`` model that includes only the ``name``
    247     and ``title`` fields, you would specify ``fields`` or ``exclude`` like
    248     this::
     308        # Import our custom widget and our model from where they're defined
     309        from myapp.widgets import RichTextEditorWidget
     310        from myapp.models import MyModel
    249311
    250         class AuthorAdmin(admin.ModelAdmin):
    251             fields = ('name', 'title')
     312        class MyModelAdmin(admin.ModelAdmin):
     313            formfield_overrides = {
     314                models.TextField: {'widget': RichTextEditorWidget},
     315            }
    252316
    253         class AuthorAdmin(admin.ModelAdmin):
    254             exclude = ('birth_date',)
     317    Note that the key in the dictionary is the actual field class, *not* a
     318    string. The value is another dictionary; these arguments will be passed to
     319    :meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for
     320    details.
    255321
    256     Since the Author model only has three fields, ``name``, ``title``, and
    257     ``birth_date``, the forms resulting from the above declarations will
    258     contain exactly the same fields.
     322    .. warning::
    259323
    260 .. attribute:: ModelAdmin.filter_horizontal
     324        If you want to use a custom widget with a relation field (i.e.
     325        :class:`~django.db.models.ForeignKey` or
     326        :class:`~django.db.models.ManyToManyField`), make sure you haven't
     327        included that field's name in ``raw_id_fields`` or ``radio_fields``.
    261328
    262     Use a nifty unobtrusive JavaScript "filter" interface instead of the
    263     usability-challenged ``<select multiple>`` in the admin form. The value is
    264     a list of fields that should be displayed as a horizontal filter interface.
    265     See ``filter_vertical`` to use a vertical interface.
     329        ``formfield_overrides`` won't let you change the widget on relation
     330        fields that have ``raw_id_fields`` or ``radio_fields`` set. That's
     331        because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
     332        their own.
    266333
    267 .. attribute:: ModelAdmin.filter_vertical
     334.. attribute:: ModelAdmin.inlines
    268335
    269     Same as ``filter_horizontal``, but is a vertical display of the filter
    270     interface.
     336    See :class:`InlineModelAdmin` objects below.
    271337
    272338.. attribute:: ModelAdmin.list_display
    273339
    … … subclass::  
    496562    regardless of this setting if one of the ``list_display`` fields is a
    497563    ``ForeignKey``.
    498564
    499 .. attribute:: ModelAdmin.inlines
    500 
    501     See :class:`InlineModelAdmin` objects below.
    502 
    503565.. attribute:: ModelAdmin.ordering
    504566
    505567    Set ``ordering`` to specify how lists of objects should be ordered in the
    506568    Django admin views. This should be a list or tuple in the same format as a
    507     model's ``ordering`` parameter.
     569    model's :attr:`~django.db.models.Options.ordering` parameter.
    508570
    509571    If this isn't provided, the Django admin will use the model's default
    510572    ordering.
    … … subclass::  
    674736        Performs a full-text match. This is like the default search method but
    675737        uses an index. Currently this is only available for MySQL.
    676738
    677 .. attribute:: ModelAdmin.formfield_overrides
    678 
    679     This provides a quick-and-dirty way to override some of the
    680     :class:`~django.forms.Field` options for use in the admin.
    681     ``formfield_overrides`` is a dictionary mapping a field class to a dict of
    682     arguments to pass to the field at construction time.
    683 
    684     Since that's a bit abstract, let's look at a concrete example. The most
    685     common use of ``formfield_overrides`` is to add a custom widget for a
    686     certain type of field. So, imagine we've written a ``RichTextEditorWidget``
    687     that we'd like to use for large text fields instead of the default
    688     ``<textarea>``. Here's how we'd do that::
    689 
    690         from django.db import models
    691         from django.contrib import admin
    692 
    693         # Import our custom widget and our model from where they're defined
    694         from myapp.widgets import RichTextEditorWidget
    695         from myapp.models import MyModel
    696 
    697         class MyModelAdmin(admin.ModelAdmin):
    698             formfield_overrides = {
    699                 models.TextField: {'widget': RichTextEditorWidget},
    700             }
    701 
    702     Note that the key in the dictionary is the actual field class, *not* a
    703     string. The value is another dictionary; these arguments will be passed to
    704     :meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for
    705     details.
    706 
    707     .. warning::
    708 
    709         If you want to use a custom widget with a relation field (i.e.
    710         :class:`~django.db.models.ForeignKey` or
    711         :class:`~django.db.models.ManyToManyField`), make sure you haven't
    712         included that field's name in ``raw_id_fields`` or ``radio_fields``.
    713 
    714         ``formfield_overrides`` won't let you change the widget on relation
    715         fields that have ``raw_id_fields`` or ``radio_fields`` set. That's
    716         because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
    717         their own.
    718 
    719 .. attribute:: ModelAdmin.actions
    720 
    721     A list of actions to make available on the change list page. See
    722     :doc:`/ref/contrib/admin/actions` for details.
    723 
    724 .. attribute:: ModelAdmin.actions_on_top
    725 .. attribute:: ModelAdmin.actions_on_bottom
    726 
    727     Controls where on the page the actions bar appears. By default, the admin
    728     changelist displays actions at the top of the page (``actions_on_top = True;
    729     actions_on_bottom = False``).
    730 
    731 .. attribute:: ModelAdmin.actions_selection_counter
    732 
    733     .. versionadded:: 1.2
    734 
    735     Controls whether a selection counter is display next to the action dropdown.
    736     By default, the admin changelist will display it
    737     (``actions_selection_counter = True``).
    738 
    739739Custom template options
    740740~~~~~~~~~~~~~~~~~~~~~~~
    741741
    … … on your ``ModelAdmin``::  
    10431043            }
    10441044            js = ("my_code.js",)
    10451045
    1046 Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
    1047 apply as :doc:`regular media definitions on forms </topics/forms/media>`.
     1046Keep in mind that this will be prepended with :setting:`MEDIA_URL`. The same
     1047rules apply as :doc:`regular media definitions on forms </topics/forms/media>`.
    10481048
    10491049Django admin Javascript makes use of the `jQuery`_ library. To avoid
    10501050conflict with user scripts, Django's jQuery is namespaced as
    … … automatically::  
    12551255            FriendshipInline,
    12561256        ]
    12571257
    1258 Working with Many-to-Many Models
     1258Working with many-to-many models
    12591259--------------------------------
    12601260
    12611261.. versionadded:: 1.2
    12621262
    12631263By default, admin widgets for many-to-many relations will be displayed
    1264 on whichever model contains the actual reference to the ``ManyToManyField``.
    1265 Depending on your ``ModelAdmin`` definition, each many-to-many field in your
    1266 model will be represented by a standard HTML ``<select multiple>``, a
    1267 horizontal or vertical filter, or a ``raw_id_admin`` widget. However, it is
    1268 also possible to to replace these widgets with inlines.
     1264on whichever model contains the actual reference to the
     1265:class:`~django.db.models.ManyToManyField`. Depending on your ``ModelAdmin``
     1266definition, each many-to-many field in your model will be represented by a
     1267standard HTML ``<select multiple>``, a horizontal or vertical filter, or a
     1268``raw_id_admin`` widget. However, it is also possible to to replace these
     1269widgets with inlines.
    12691270
    12701271Suppose we have the following models::
    12711272
    … … In all other respects, the ``InlineModelAdmin`` is exactly the same as any  
    13111312other. You can customize the appearance using any of the normal
    13121313``ModelAdmin`` properties.
    13131314
    1314 Working with Many-to-Many Intermediary Models
    1315 ----------------------------------------------
     1315Working with many-to-many intermediary models
     1316---------------------------------------------
    13161317
    13171318When you specify an intermediary model using the ``through`` argument to a
    1318 ``ManyToManyField``, the admin will not display a widget by default. This is
    1319 because each instance of that intermediary model requires more information
    1320 than could be displayed in a single widget, and the layout required for
    1321 multiple widgets will vary depending on the intermediate model.
     1319:class:`~django.db.models.ManyToManyField`, the admin will not display a
     1320widget by default. This is because each instance of that intermediary model
     1321requires more information than could be displayed in a single widget, and the
     1322layout required for multiple widgets will vary depending on the intermediate
     1323model.
    13221324
    13231325However, we still want to be able to edit that information inline. Fortunately,
    13241326this is easy to do with inline admin models. Suppose we have the following
    … … other inline. In your ``admin.py`` for this example app::  
    14071409See the :doc:`contenttypes documentation </ref/contrib/contenttypes>` for more
    14081410specific information.
    14091411
    1410 Overriding Admin Templates
     1412Overriding admin templates
    14111413==========================
    14121414
    14131415It is relatively easy to override many of the templates which the admin module
    … … directory.  
    14221424
    14231425In order to override one or more of them, first create an ``admin`` directory
    14241426in your project's ``templates`` directory. This can be any of the directories
    1425 you specified in ``TEMPLATE_DIRS``.
     1427you specified in :setting:`TEMPLATE_DIRS`.
    14261428
    14271429Within this ``admin`` directory, create sub-directories named after your app.
    14281430Within these app subdirectories create sub-directories named after your models.
    … … Templates can override or extend base admin templates as described in  
    15481550
    15491551    Path to a custom template that will be used by the admin site login view.
    15501552
    1551 .. versionadded:: 1.3
    1552 
    15531553.. attribute:: AdminSite.login_form
    15541554
     1555    .. versionadded:: 1.3
     1556
    15551557    Subclass of :class:`~django.contrib.auth.forms.AuthenticationForm` that
    15561558    will be used by the admin site login view.
    15571559
    … … a pattern for your new view.  
    16521654.. note::
    16531655    Any view you render that uses the admin templates, or extends the base
    16541656    admin template, should provide the ``current_app`` argument to
    1655     ``RequestContext`` or ``Context`` when rendering the template.  It should
    1656     be set to either ``self.name`` if your view is on an ``AdminSite`` or
    1657     ``self.admin_site.name`` if your view is on a ``ModelAdmin``.
     1657    :class:`~django.template.RequestContext` or :class:`~django.template.Context`
     1658    when rendering the template.  It should be set to either ``self.name`` if
     1659    your view is on an ``AdminSite`` or ``self.admin_site.name`` if your view
     1660    is on a ``ModelAdmin``.
    16581661
    16591662.. _admin-reverse-urls:
    16601663
    1661 Reversing Admin URLs
     1664Reversing admin URLs
    16621665====================
    16631666
    16641667When an :class:`AdminSite` is deployed, the views provided by that site are
Back to Top