From a19ed8aea395e8e07164ff7d85bd7dff2f24edca Mon Sep 17 00:00:00 2001
From: Brian Rosner <brosner@gmail.com>
Date: Fri, 18 Jul 2008 23:54:34 +0000
Subject: Merged the newforms-admin branch into trunk.

This is a backward incompatible change. The admin contrib app has been
refactored. The newforms module has several improvements including FormSets
and Media definitions.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@7967 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/model-api.txt | 478 -----------------------------------------------------
 1 file changed, 478 deletions(-)

(limited to 'docs/model-api.txt')

diff --git a/docs/model-api.txt b/docs/model-api.txt
index 4e7b5c3096..4accad122a 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -12,8 +12,6 @@ The basics:
     * Each attribute of the model represents a database field.
     * Model metadata (non-field information) goes in an inner class named
       ``Meta``.
-    * Metadata used for Django's admin site goes into an inner class named
-      ``Admin``.
     * With all of this, Django gives you an automatically-generated
       database-access API, which is explained in the `Database API reference`_.
 
@@ -425,18 +423,6 @@ not specified, Django will use a default length of 50.
 
 Implies ``db_index=True``.
 
-Accepts an extra option, ``prepopulate_from``, which is a list of fields
-from which to auto-populate the slug, via JavaScript, in the object's admin
-form::
-
-    models.SlugField(prepopulate_from=("pre_name", "name"))
-
-``prepopulate_from`` doesn't accept DateTimeFields, ForeignKeys nor
-ManyToManyFields.
-
-The admin represents ``SlugField`` as an ``<input type="text">`` (a
-single-line input).
-
 ``SmallIntegerField``
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -665,16 +651,6 @@ unless you want to override the default primary-key behavior.
 ``primary_key=True`` implies ``null=False`` and ``unique=True``. Only
 one primary key is allowed on an object.
 
-``radio_admin``
-~~~~~~~~~~~~~~~
-
-By default, Django's admin uses a select-box interface (<select>) for
-fields that are ``ForeignKey`` or have ``choices`` set. If ``radio_admin``
-is set to ``True``, Django will use a radio-button interface instead.
-
-Don't use this for a field unless it's a ``ForeignKey`` or has ``choices``
-set.
-
 ``unique``
 ~~~~~~~~~~
 
@@ -822,14 +798,6 @@ relationship should work. All are optional:
     =======================  ============================================================
     Argument                 Description
     =======================  ============================================================
-    ``edit_inline``          If ``True``, this related object is edited
-                             "inline" on the related object's page. This means
-                             that the object will not have its own admin
-                             interface. Use either ``models.TABULAR`` or ``models.STACKED``,
-                             which, respectively, designate whether the inline-editable
-                             objects are displayed as a table or as a "stack" of
-                             fieldsets.
-
     ``limit_choices_to``     A dictionary of lookup arguments and values (see
                              the `Database API reference`_) that limit the
                              available admin choices for this object. Use this
@@ -848,39 +816,6 @@ relationship should work. All are optional:
 
                              Not compatible with ``edit_inline``.
 
-    ``max_num_in_admin``     For inline-edited objects, this is the maximum
-                             number of related objects to display in the admin.
-                             Thus, if a pizza could only have up to 10
-                             toppings, ``max_num_in_admin=10`` would ensure
-                             that a user never enters more than 10 toppings.
-
-                             Note that this doesn't ensure more than 10 related
-                             toppings ever get created. It simply controls the
-                             admin interface; it doesn't enforce things at the
-                             Python API level or database level.
-
-    ``min_num_in_admin``     The minimum number of related objects displayed in
-                             the admin. Normally, at the creation stage,
-                             ``num_in_admin`` inline objects are shown, and at
-                             the edit stage ``num_extra_on_change`` blank
-                             objects are shown in addition to all pre-existing
-                             related objects.  However, no fewer than
-                             ``min_num_in_admin`` related objects will ever be
-                             displayed.
-
-    ``num_extra_on_change``  The number of extra blank related-object fields to
-                             show at the change stage.
-
-    ``num_in_admin``         The default number of inline objects to display
-                             on the object page at the add stage.
-
-    ``raw_id_admin``         Only display a field for the integer to be entered
-                             instead of a drop-down menu. This is useful when
-                             related to an object type that will have too many
-                             rows to make a select box practical.
-
-                             Not used with ``edit_inline``.
-
     ``related_name``         The name to use for the relation from the related
                              object back to this one. See the
                              `related objects documentation`_ for a full
@@ -957,13 +892,6 @@ the relationship should work. All are optional:
     =======================  ============================================================
     ``related_name``         See the description under ``ForeignKey`` above.
 
-    ``filter_interface``     Use a nifty unobtrusive Javascript "filter" interface
-                             instead of the usability-challenged ``<select multiple>``
-                             in the admin form for this object. The value should be
-                             ``models.HORIZONTAL`` or ``models.VERTICAL`` (i.e.
-                             should the interface be stacked horizontally or
-                             vertically).
-
     ``limit_choices_to``     See the description under ``ForeignKey`` above.
 
     ``symmetrical``          Only used in the definition of ManyToManyFields on self.
@@ -1255,412 +1183,6 @@ attribute is the primary key field for the model. You can read and set this
 value, just as you would for any other attribute, and it will update the
 correct field in the model.
 
-Admin options
-=============
-
-If you want your model to be visible to Django's admin site, give your model an
-inner ``"class Admin"``, like so::
-
-    class Person(models.Model):
-        first_name = models.CharField(max_length=30)
-        last_name = models.CharField(max_length=30)
-
-        class Admin:
-            # Admin options go here
-            pass
-
-The ``Admin`` class tells Django how to display the model in the admin site.
-
-Here's a list of all possible ``Admin`` options. None of these options are
-required. To use an admin interface without specifying any options, use
-``pass``, like so::
-
-    class Admin:
-        pass
-
-Adding ``class Admin`` to a model is completely optional.
-
-``date_hierarchy``
-------------------
-
-Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in
-your model, and the change list page will include a date-based drilldown
-navigation by that field.
-
-Example::
-
-    date_hierarchy = 'pub_date'
-
-``fields``
-----------
-
-Set ``fields`` to control the layout of admin "add" and "change" pages.
-
-``fields`` is a list of two-tuples, in which each two-tuple represents a
-``<fieldset>`` on the admin form page. (A ``<fieldset>`` is a "section" of the
-form.)
-
-The two-tuples are in the format ``(name, field_options)``, where ``name`` is a
-string representing the title of the fieldset and ``field_options`` is a
-dictionary of information about the fieldset, including a list of fields to be
-displayed in it.
-
-A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::
-
-    class Admin:
-        fields = (
-            (None, {
-                'fields': ('url', 'title', 'content', 'sites')
-            }),
-            ('Advanced options', {
-                'classes': 'collapse',
-                'fields' : ('enable_comments', 'registration_required', 'template_name')
-            }),
-        )
-
-This results in an admin page that looks like:
-
-    .. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
-
-If ``fields`` isn't given, Django will default to displaying each field that
-isn't an ``AutoField`` and has ``editable=True``, in a single fieldset, in
-the same order as the fields are defined in the model.
-
-The ``field_options`` dictionary can have the following keys:
-
-``fields``
-~~~~~~~~~~
-
-A tuple of field names to display in this fieldset. This key is required.
-
-Example::
-
-    {
-    'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
-    }
-
-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'),
-    }
-
-``classes``
-~~~~~~~~~~~
-
-A string containing extra CSS classes to apply to the fieldset.
-
-Example::
-
-    {
-    'classes': 'wide',
-    }
-
-Apply multiple classes by separating them with spaces. Example::
-
-    {
-    '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.
-
-``description``
-~~~~~~~~~~~~~~~
-
-A string of optional extra text to be displayed at the top of each fieldset,
-under the heading of the fieldset. It's used verbatim, so you can use any HTML
-and you must escape any special HTML characters (such as ampersands) yourself.
-
-``js``
-------
-
-A list of strings representing URLs of JavaScript files to link into the admin
-screen via ``<script src="">`` tags. This can be used to tweak a given type of
-admin page in JavaScript or to provide "quick links" to fill in default values
-for certain fields.
-
-If you use relative URLs -- URLs that don't start with ``http://`` or ``/`` --
-then the admin site will automatically prefix these links with
-``settings.ADMIN_MEDIA_PREFIX``.
-
-``list_display``
-----------------
-
-Set ``list_display`` to control which fields are displayed on the change list
-page of the admin.
-
-Example::
-
-    list_display = ('first_name', 'last_name')
-
-If you don't set ``list_display``, the admin site will display a single column
-that displays the ``__str__()`` representation of each object.
-
-A few special cases to note about ``list_display``:
-
-    * 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``.)
-
-    * 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, Django will call it and
-      display the output. This method should have a ``short_description``
-      function attribute, for use as the header for the field.
-
-      Here's a full example model::
-
-          class Person(models.Model):
-              name = models.CharField(max_length=50)
-              birthday = models.DateField()
-
-              class Admin:
-                  list_display = ('name', 'decade_born_in')
-
-              def decade_born_in(self):
-                  return self.birthday.strftime('%Y')[:3] + "0's"
-              decade_born_in.short_description = 'Birth decade'
-
-    * If the string given is a method of the model, 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::
-
-          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 Admin:
-                  list_display = ('first_name', 'last_name', 'colored_name')
-
-              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
-
-    * If the string given is a method of the model 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::
-
-          class Person(models.Model):
-              first_name = models.CharField(max_length=50)
-              birthday = models.DateField()
-
-              class Admin:
-                  list_display = ('name', 'born_in_fifties')
-
-              def born_in_fifties(self):
-                  return self.birthday.strftime('%Y')[:3] == 5
-              born_in_fifties.boolean = True
-
-
-    * 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')
-
-    * 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(max_length=50)
-            color_code = models.CharField(max_length=6)
-
-            class Admin:
-                list_display = ('first_name', 'colored_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'
-
-      The above will tell Django to order by the ``first_name`` field when
-      trying to sort by ``colored_first_name`` in the admin.
-
-``list_display_links``
-----------------------
-
-Set ``list_display_links`` to control which fields in ``list_display`` should
-be linked to the "change" page for an object.
-
-By default, the change list page will link the first column -- the first field
-specified in ``list_display`` -- to the change page for each item. But
-``list_display_links`` lets you change which columns are linked. Set
-``list_display_links`` to a list or tuple of field names (in the same format as
-``list_display``) to link.
-
-``list_display_links`` can specify one or many field names. As long as the
-field names appear in ``list_display``, Django doesn't care how many (or how
-few) fields are linked. The only requirement is: If you want to use
-``list_display_links``, you must define ``list_display``.
-
-In this example, the ``first_name`` and ``last_name`` fields will be linked on
-the change list page::
-
-    class Admin:
-        list_display = ('first_name', 'last_name', 'birthday')
-        list_display_links = ('first_name', 'last_name')
-
-Finally, note that in order to use ``list_display_links``, you must define
-``list_display``, too.
-
-``list_filter``
----------------
-
-Set ``list_filter`` to activate filters in the right sidebar of the change list
-page of the admin. This should be a list of field names, and each specified
-field should be either a ``BooleanField``, ``CharField``, ``DateField``,
-``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
-
-This example, taken from the ``django.contrib.auth.models.User`` model, shows
-how both ``list_display`` and ``list_filter`` work::
-
-    class Admin:
-        list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
-        list_filter = ('is_staff', 'is_superuser')
-
-The above code results in an admin change list page that looks like this:
-
-    .. image:: http://media.djangoproject.com/img/doc/users_changelist.png
-
-(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``
------------------------
-
-Set ``list_select_related`` to tell Django to use ``select_related()`` in
-retrieving the list of objects on the admin change list page. This can save you
-a bunch of database queries.
-
-The value should be either ``True`` or ``False``. Default is ``False``.
-
-Note that Django will use ``select_related()``, regardless of this setting,
-if one of the ``list_display`` fields is a ``ForeignKey``.
-
-For more on ``select_related()``, see `the select_related() docs`_.
-
-.. _the select_related() docs: ../db-api/#select-related
-
-``ordering``
-------------
-
-Set ``ordering`` to specify how objects on the admin change list page should be
-ordered. This should be a list or tuple in the same format as a model's
-``ordering`` parameter.
-
-If this isn't provided, the Django admin will use the model's default ordering.
-
-``save_as``
------------
-
-Set ``save_as`` to enable a "save as" feature on admin change forms.
-
-Normally, objects have three save options: "Save", "Save and continue editing"
-and "Save and add another". If ``save_as`` is ``True``, "Save and add another"
-will be replaced by a "Save as" button.
-
-"Save as" means the object will be saved as a new object (with a new ID),
-rather than the old object.
-
-By default, ``save_as`` is set to ``False``.
-
-``save_on_top``
----------------
-
-Set ``save_on_top`` to add save buttons across the top of your admin change
-forms.
-
-Normally, the save buttons appear only at the bottom of the forms. If you set
-``save_on_top``, the buttons will appear both on the top and the bottom.
-
-By default, ``save_on_top`` is set to ``False``.
-
-``search_fields``
------------------
-
-Set ``search_fields`` to enable a search box on the admin change list page.
-This should be set to a list of field names that will be searched whenever
-somebody submits a search query in that text box.
-
-These fields should be some kind of text field, such as ``CharField`` or
-``TextField``. You can also perform a related lookup on a ``ForeignKey`` with
-the lookup API "follow" notation::
-
-    search_fields = ['foreign_key__related_fieldname']
-
-When somebody does a search in the admin search box, Django splits the search
-query into words and returns all objects that contain each of the words, case
-insensitive, where each word must be in at least one of ``search_fields``. For
-example, if ``search_fields`` is set to ``['first_name', 'last_name']`` and a
-user searches for ``john lennon``, Django will do the equivalent of this SQL
-``WHERE`` clause::
-
-    WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')
-    AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')
-
-For faster and/or more restrictive searches, prefix the field name
-with an operator:
-
-``^``
-    Matches the beginning of the field. For example, if ``search_fields`` is
-    set to ``['^first_name', '^last_name']`` and a user searches for
-    ``john lennon``, Django will do the equivalent of this SQL ``WHERE``
-    clause::
-
-        WHERE (first_name ILIKE 'john%' OR last_name ILIKE 'john%')
-        AND (first_name ILIKE 'lennon%' OR last_name ILIKE 'lennon%')
-
-    This query is more efficient than the normal ``'%john%'`` query, because
-    the database only needs to check the beginning of a column's data, rather
-    than seeking through the entire column's data. Plus, if the column has an
-    index on it, some databases may be able to use the index for this query,
-    even though it's a ``LIKE`` query.
-
-``=``
-    Matches exactly, case-insensitive. For example, if
-    ``search_fields`` is set to ``['=first_name', '=last_name']`` and
-    a user searches for ``john lennon``, Django will do the equivalent
-    of this SQL ``WHERE`` clause::
-
-        WHERE (first_name ILIKE 'john' OR last_name ILIKE 'john')
-        AND (first_name ILIKE 'lennon' OR last_name ILIKE 'lennon')
-
-    Note that the query input is split by spaces, so, following this example,
-    it's currently not possible to search for all records in which
-    ``first_name`` is exactly ``'john winston'`` (containing a space).
-
-``@``
-    Performs a full-text match. This is like the default search method but uses
-    an index. Currently this is only available for MySQL.
-
 Managers
 ========
 
-- 
cgit v1.3