Django

Code

Changeset 136

Show
Ignore:
Timestamp:
07/16/05 23:20:57 (3 years ago)
Author:
adrian
Message:

Copy-edited model-API docs

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/model-api.txt

    r67 r136  
    33=============== 
    44 
    5 Django's models are the bread and butter of the framework.  There's a huge  
    6 array of options available to you when defining your data models; this  
    7 document explains all of them. 
     5Django's models are the bread and butter of the framework.  There's a huge 
     6array of options available to you when defining your data models. This 
     7document explains them. 
    88 
    99Options for models 
    1010================== 
    1111 
    12 A list of all possible options for a model object follows. Although there's a 
    13 wide array of possible options, only ``fields`` is required. 
     12A list of all possible options for a model object follows. Although there's a 
     13wide array of options, only ``fields`` is required. 
    1414 
    1515``admin`` 
    1616    A ``meta.Admin`` object; see `Admin options`_.  If this field isn't given, 
    1717    the object will not have an admin interface. 
    18      
     18 
    1919``db_table`` 
    2020    The name of the database table to use for the module:: 
    21      
     21 
    2222        db_table = "pizza_orders" 
    23          
    24     If not given, this will use ``app_label + '_' + module_name``. 
    25      
     23 
     24    If this isn't given, Django will use ``app_label + '_' + module_name``. 
     25 
    2626``exceptions`` 
    2727    Names of extra exception subclasses to include in the generated module. 
    2828    These exceptions are available from instance methods and from module-level 
    2929    methods:: 
    30          
     30 
    3131        exceptions = ("DisgustingToppingsException", "BurntCrust") 
    32      
     32 
    3333``fields`` 
    34     A list of field objects; see `Field objects`_. For example:: 
    35      
     34    A list of field objects. See `Field objects`_. For example:: 
     35 
    3636        fields = ( 
    3737            meta.CharField('customer_name', 'customer name', maxlength=15), 
    …… 
    4040            ... 
    4141        ) 
    42          
     42 
    4343``get_latest_by`` 
    44     The name of a date or datetime field; if given, the module will have a 
    45     ``get_latest()`` function which fetches the "latest" object in terms of 
    46     that field:: 
    47      
     44    The name of a ``DateField`` or ``DateTimeField``; if given, the module will 
     45    have a ``get_latest()`` function that fetches the "latest" object according 
     46    to that field:: 
     47 
    4848        get_latest_by = "order_date" 
    49      
     49 
    5050``module_constants`` 
    51     A dict of name/values to use as extra module-level constants:: 
    52      
     51    A dictionary of names/values to use as extra module-level constants:: 
     52 
    5353        module_constants = { 
    5454            'MEAT_TYPE_PEPPERONI' : 1, 
    5555            'MEAT_TYPE_SAUSAGE' : 2, 
    5656        } 
    57      
     57 
    5858``module_name`` 
    5959    The name of the module:: 
    60      
     60 
    6161        module_name = "pizza_orders" 
    62          
    63     If not given this will use a lowercased version of the class name. 
    64      
     62 
     63    If this isn't given, Django will use a lowercased version of the class 
     64    name, plus "s". 
     65 
    6566``order_with_respect_to`` 
    6667    Marks this object as "orderable" with respect to the given field.  This is 
    …… 
    6869    respect to a parent object.  For example, if a ``PizzaToppping`` relates to 
    6970    a ``Pizza`` object, you might use:: 
    70      
     71 
    7172        order_with_respect_to = 'pizza_id' 
    72      
     73 
    7374    to allow the toppings to be ordered with respect to the associated pizza. 
    74      
     75 
    7576``ordering`` 
    76     The default ordering for tho object:: 
    77      
     77    The default ordering for the object, for use by ``get_list`` and the admin:: 
     78 
    7879        ordering = (('order_date', 'DESC'),) 
    79          
    80     This is a tuple of 2-tuples; each 2-tuple is ``(field_name, ordering_type)`` 
    81     where ordering_type is either ``"ASC"`` or ``"DESC"``.  You may also use the 
    82     magic ``(None, "RANDOM")`` ordering tuple for random ordering. 
    83      
     80 
     81    This is a tuple of 2-tuples. Each 2-tuple is ``(field_name, ordering_type)`` 
     82    where ordering_type is either ``"ASC"`` or ``"DESC"``.  You can also use the 
     83    ``(None, "RANDOM")`` for random ordering. 
     84 
    8485``permissions`` 
    8586    Extra permissions to enter into the permissions table when creating this 
    86     object. A add, delete, and change permission is automatically created for 
    87     each object; this option specifies extra permissions:: 
    88      
    89         permissions = (("may_delivier_pizzas", "Can deliver pizzas"),) 
    90          
    91     This is a list of 2-tuples of  
     87    object. A add, delete, and change permission is automatically created for 
     88    each object. This option specifies extra permissions:: 
     89 
     90        permissions = (("can_delivier_pizzas", "Can deliver pizzas"),) 
     91 
     92    This is a list of 2-tuples of 
    9293    ``(permission_code, human_readable_permission_name)``. 
    93      
     94 
    9495``unique_together`` 
    9596    Sets of field names that, taken together, must be unique:: 
    96      
     97 
    9798        unique_together = (("driver_id", "restaurant_id"),) 
    98          
     99 
    99100    This is a list of lists of fields that must be unique when considered 
    100     together. 
    101      
     101    together. It's used in the Django admin. 
     102 
    102103``verbose_name`` 
    103104    A human-readable name for the object, singular:: 
    104      
     105 
    105106        verbose_name = "pizza" 
    106      
    107     If not given, this will use a munged version of the class name: 
     107 
     108    If this isn't given, Django will use a munged version of the class name: 
    108109    ``CamelCase`` becomes ``camel case``. 
    109      
     110 
    110111``verbose_name_plural`` 
    111112    The plural name for the object:: 
    112      
     113 
    113114        verbose_name_plural = "stories" 
    114      
    115     If not given, ``verbose_name + "s"`` will automatically be used. 
    116      
     115 
     116    If this isn't given, Django will use ``verbose_name + "s"``. 
     117 
    117118Field objects 
    118119============= 
    119120 
    120121The list of fields is the most important part of a data model.  Each item in 
    121 the ``fields`` list is an instance of a ``meta.Field`` subclass, and maps to 
     122the ``fields`` list is an instance of a ``meta.Field`` subclass and maps to 
    122123a database field. 
    123124 
    …… 
    131132--------------------- 
    132133 
    133 Each type of field takes a different set of options, but there are some 
    134 options that are common to all field types. These options are: 
     134Each type of field takes a different set of options, but some options are 
     135common to all field types. These options are: 
    135136 
    136137    ======================  =================================================== 
    137138    Option                  Description 
    138139    ======================  =================================================== 
    139     ``blank``               If ``True``, the field is allowed to be blank.   
     140    ``blank``               If ``True``, the field is allowed to be blank. 
    140141                            Note that this is different from ``null`` in that 
    141142                            string fields will store the empty string instead of 
    142                             ``NULL`` internally; this means that to create a 
     143                            ``NULL`` internally. This means that to create a 
    143144                            field that stores nulls you must pass ``blank=True`` 
    144                             and ``null=True`` . 
    145      
    146     ``choices``             A list of 2-tuples to use as choices for this  
    147                             field.If this is given, instead of the standard 
    148                             field a option menu will be used, limiting choices 
    149                             to the choices given.  A choices list looks like:: 
    150                          
     145                            and ``null=True``. 
     146 
     147    ``choices``             A list of 2-tuples to use as choices for this 
     148                            field. If this is given, Django's admin will use a 
     149                            select box instead of the standard text field and 
     150                            will limit choices to the choices given.  A choices 
     151                            list looks like:: 
     152 
    151153                                YEAR_IN_SCHOOL_CHOICES = ( 
    152154                                    ('FR', 'Freshman'), 
    …… 
    156158                                    ('GR', 'Graduate'), 
    157159                                ) 
    158                              
     160 
    159161                            The first element in each tuple is the actual value 
    160                             to be stored; the second element is the human 
    161                             readable name for the option. 
    162                              
     162                            to be stored. The second element is the 
     163                            human-readable name for the option. 
     164 
    163165    ``core``                For objects that are edited inline to a related 
    164166                            object.  If all "core" fields in an inline-edited 
    165167                            object are cleared, the object will be considered to 
    166168                            be deleted. 
    167                              
     169 
    168170                            It is an error to have an inline-editable 
    169171                            relation without at least one core field. 
    170      
     172 
    171173    ``db_index``            If ``True``, the SQL generator will create a database 
    172174                            index on this field. 
    173      
     175 
    174176    ``default``             The default value for the field. 
    175      
    176     ``editable``            ``True`` by default, if set to ``False`` the field 
    177                             will not be editable in the admin. 
    178      
    179     ``help_text``           Extra "help" text to be displayed with the field. 
    180      
    181     ``null``                If ``True`` empty values in the field will be  
    182                             stored as ``NULL`` in the database.   
    183          
    184     ``primary_key``         If ``True`` this field is the primary key for the 
    185                             table.  You only need to use this if you don't want 
     177 
     178    ``editable``            ``True`` by default. If this is set to ``False``, 
     179                            the field will not be editable in the admin. 
     180 
     181    ``help_text``           Extra "help" text to be displayed under the field 
     182                            on the object's admin form. 
     183 
     184    ``null``                If ``True``, empty values in the field will be 
     185                            stored as ``NULL`` in the database. 
     186 
     187    ``primary_key``         If ``True``, this field is the primary key for the 
     188                            table. You only need to use this if you don't want 
    186189                            the standard "id" field created and used as the 
    187190                            primary key. 
    188                              
     191 
    189192                            Implies ``blank=False``, ``null=False``, and 
    190                             ``unique=True``.  Only one primary key is allowed 
    191                             on each object. 
    192      
    193     ``radio_admin``         If ``choices`` is given, or if the field is a  
    194                             ManyToOne relation, use a radio button interface 
    195                             for the choices instead of the standard options 
    196                             menu interface. 
    197      
    198     ``unique``              If ``True`` this field must be unique throughout 
    199                             the table. 
    200      
    201     ``unique_for_date``     Set this to the name of a ``DateField`` or  
     193                            ``unique=True``. Only one primary key is allowed 
     194                            on an object. 
     195 
     196    ``radio_admin``         If ``choices`` is given, or if the field is a 
     197                            ManyToOne relation, use a radio-button interface 
     198                            for the choices instead of the standard select-box 
     199                            interface. 
     200 
     201    ``unique``              If ``True``, this field must be unique throughout 
     202                            the table. This is enforced at the database level 
     203                            and at the Django admin-form level. 
     204 
     205    ``unique_for_date``     Set this to the name of a ``DateField`` or 
    202206                            ``DateTimeField`` to require that this field 
    203                             be unique for the value of the date field. That 
    204                             is, if you have a field, ``title`` that has  
     207                            be unique for the value of the date field. For 
     208                            example, if you have a field ``title`` that has 
    205209                            ``unique_for_date="pub_date"``, then it is an 
    206210                            error to have two rows with the same ``title`` 
    207211                            and the same ``pub_date``. 
    208      
     212 
    209213    ``unique_for_month``    Like ``unique_for_date``, but requires the field 
    210214                            to be unique with respect to the month. 
    211      
    212     ``unique_for_year``     Like ``unique_for_date`` and ``unique_for_month`` 
    213                             but, well, you get the idea. 
    214      
     215 
     216    ``unique_for_year``     Like ``unique_for_date`` and ``unique_for_month``. 
     217 
    215218    ``validator_list``      A list of extra validators to apply to the field. 
    216                             See the `Form fields guide`_ for information about 
    217                             validators. 
    218219    ======================  =================================================== 
    219  
    220 .. _`Form fields guide`: http://www.djangoproject.com/FIXME/ 
    221220 
    222221Field Types 
    223222----------- 
    224      
     223 
    225224``AutoField`` 
    226     An ``IntegerField`` that automatically increments. You usually won't need to 
    227     use this directly; a primary key field will automatically be added to your  
    228     model if you don't specify otherwise. That automatically added field is:: 
    229      
     225    An ``IntegerField`` that automatically increments. You usually won't need to 
     226    use this directly; a primary key field will automatically be added to your 
     227    model if you don't specify otherwise. That automatically-added field is:: 
     228 
    230229        meta.AutoField('id', 'ID', primary_key=True) 
    231      
     230 
    232231``BooleanField`` 
    233232    A true/false field. 
    234      
     233 
    235234``CharField`` 
    236     A text field. These are displayed in the admin as single-line text inputs, so  
    237     for large amounts of text use a ``TextField``. 
    238      
    239     ``CharField``s have an extra required argument: ``maxlength``; the maximum  
    240     length (in characters) of the field. 
    241      
     235    A text field. These are displayed in the admin as single-line text inputs, so 
     236    for large amounts of text, use a ``TextField``. 
     237 
     238    ``CharField``s have an extra required argument: ``maxlength``, the maximum 
     239    length (in characters) of the field. The maxlength is enforced at the database 
     240    level and in Django's admin validation. 
     241 
    242242``CommaSeparatedIntegerField`` 
    243243    A field of integers separated by commas. 
    244      
     244 
    245245``DateField`` 
    246     A, um, date field. Has a few extra optional options: 
    247      
     246    A date field. Has a few extra optional options: 
     247 
    248248        ======================  =================================================== 
    249249        Option                  Description 
    250250        ======================  =================================================== 
    251251        ``auto_now``            Automatically set the field to now every time the 
    252                                 object is saved. Useful for "last-modified" 
     252                                object is saved. Useful for "last-modified" 
    253253                                timestamps. 
    254                                  
     254 
    255255        ``auto_now_add``        Automatically set the field to now when the object 
    256                                 is first created.  Useful for creation timestamps. 
     256                                is first created.  Useful for creation of 
     257                                timestamps. 
    257258        ======================  =================================================== 
    258      
     259 
    259260``DateTimeField`` 
    260261    A date and time field.  Takes the same extra options as ``DateField``. 
    261      
    262      
     262 
    263263``EmailField`` 
    264     A ``CharField`` that checks that the value is a valid email address.  Because 
    265     validating email addresses can be tricky, this is a pretty loose test. 
    266      
     264    A ``CharField`` that checks that the value is a valid e-mail address. 
     265    Because validating e-mail addresses can be tricky, this is a pretty loose 
     266    test. 
     267 
    267268``FileField`` 
    268     A file-upload field.  Takes on additional option, ``upload_to`` which is 
    269     a path to upload the file to.  This path may contain `strftime formatting`_ 
    270     which will be replaced by the date/time of the file upload (so that uploaded 
    271     files don't fill up the given directory). 
    272      
     269    A file-upload field.  Takes an additional option, ``upload_to``, which is 
     270    a local filesystem path to upload the file to. This path may contain 
     271    `strftime formatting`_, which will be replaced by the date/time of the file 
     272    upload (so that uploaded files don't fill up the given directory). 
     273 
    273274    .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941 
    274      
     275 
    275276``FloatField`` 
    276     A floating-point number. Has two additional required options: 
    277      
     277    A floating-point number. Has two additional required options: 
     278 
    278279        ======================  =================================================== 
    279280        Option                  Description 
    280281        ======================  =================================================== 
    281282        ``max_digits``          The maximum number of digits allowed in the number. 
    282          
     283 
    283284        ``decimal_places``      The number of decimal places to store with the 
    284285                                number 
    285286        ======================  =================================================== 
    286      
     287 
    287288    For example, to store numbers up to 999 with a resolution of 2 decimal places, 
    288289    you'd use:: 
    289      
     290 
    290291        meta.FloatField(..., max_digits=5, decimal_places=2) 
    291      
     292 
    292293    And to store numbers up to one million with a resolution of 10 decimal places:: 
    293      
     294 
    294295        meta.FloatField(..., max_digits=19, decimal_places=10) 
    295      
     296 
    296297``ForeignKey`` 
    297     A many-to-one relationship to the primary key in another object. So, to give a 
    298     ``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are  
     298    A many-to-one relationship to the primary key in another object. So, to give a 
     299    ``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are 
    299300    many toppings on a pizza):: 
    300      
     301 
    301302        meta.ForeignKey(Pizza) 
    302                  
     303 
    303304    ``ForeignKey`` fields take a large number of extra options for defining how 
    304305    the relationship should work: 
    305      
     306 
    306307    =======================  ============================================================ 
    307308    Option                   Description 
    308309    =======================  ============================================================ 
    309     ``edit_inline``          If ``True``, this related object is edited  
    310                              "inline" on the related object's page. This means 
    311                              that the object will not have its own admin  
    312                              interface.   
    313                               
    314     ``edit_inline_type``     This is either ``meta.TABULAR`` or  
    315                              ``meta.STACKED`` and controls weather the inline 
     310    ``edit_inline``          If ``True``, this related object is edited 
     311                             "inline" on the related object's page. This means 
     312                             that the object will not have its own admin 
     313                             interface. 
     314 
     315    ``edit_inline_type``     This is either ``meta.TABULAR`` or 
     316                             ``meta.STACKED`` and controls whether the inline 
    316317                             editable objects are displayed as a table or as 
    317                              a "stack" of fieldsets.  Defaults to  
     318                             a "stack" of fieldsets.  Defaults to 
    318319                             ``meta.STACKED``. 
    319                               
     320 
    320321    ``limit_choices_to``     A dictionary of lookup arguments and values (see 
    321                              the `Database API reference`_) to limit choices 
    322                              of this object to.  Use this along with  
    323                              ``meta.LazyDate`` to limit choices of objects 
    324                              by date, for example:: 
    325                               
     322                             the `Database API reference`_) that limit the 
     323                             available admin choices for this object. Use this 
     324                             with ``meta.LazyDate`` to limit choices of objects 
     325                             by date. For example:: 
     326 
    326327                                limit_choices_to = {'pub_date__lte' : meta.LazyDate()} 
    327                                  
     328 
    328329                             only allows the choice of related objects with a 
    329330                             ``pub_date`` before the current date/time to be 
    330331                             chosen. 
    331                               
     332 
    332333                             Not compatible with ``edit_inline``. 
    333      
     334 
    334335    ``max_num_in_admin``     For inline-edited objects, this is the maximum 
    335336                             number of related objects to display in the admin. 
    336                              Thus, if a pizza could only have up to 10  
     337                             Thus, if a pizza could only have up to 10 
    337338                             toppings, ``max_num_in_admin=10`` would ensure 
    338339                             that a user never enters more than 10 toppings. 
    339                               
     340 
    340341                             Note that this doesn't ensure more than 10 related 
    341                              toppings ever get created. 
    342      
     342                             toppings ever get created. It just controls the 
     343                             interface. 
     344 
    343345    ``min_num_in_admin``     The minimum number of related objects displayed in 
    344                              the admin. Normally, at the creation stage 
     346                             the admin. Normally, at the creation stage, 
    345347                             ``num_in_admin`` inline objects are shown, and at 
    346                              the edit stage ``num_extra_on_change`` objects are 
    347                              shown in addition to all pre-existing related 
    348                              objects.  However, no fewer than 
     348                             the edit stage ``num_extra_on_change`` blank 
     349                             objects are shown in addition to all pre-existing 
     350                             related objects.  However, no fewer than 
    349351                             ``min_num_in_admin`` related objects will ever be 
    350352                             displayed. 
    351      
    352     ``num_extra_on_change``  The number of extra blank related object fields to 
     353 
     354    ``num_extra_on_change``  The number of extra blank related-object fields to 
    353355                             show at the change stage. 
    354      
     356 
    355357    ``num_in_admin``         The default number of inline objects to display 
    356358                             on the object page at the add stage. 
    357      
     359 
    358360    ``raw_id_admin``         Only display a field for the integer to be entered 
    359                              instead of a drop-down menu. This is useful when 
     361                             instead of a drop-down menu. This is useful when 
    360362                             related to an object type that will have too many 
    361                              rows to make a menu practical. 
    362                               
     363                             rows to make a select box practical. 
     364 
    363365                             Not used with ``edit_inline``. 
    364                               
    365     ``rel_name``             The name of the relation. In the above example, 
    366                              this would default to 'pizza' (so that the  
     366 
     367    ``rel_name``             The name of the relation. In the above example, 
     368                             this would default to 'pizza' (so that the 
    367369                             ``Toppings`` object would have a ``get_pizza()`` 
    368                              function; if you set ``rel_name`` to "pie", then 
     370                             function. If you set ``rel_name`` to "pie", then 
    369371                             the function would be called ``get_pie()`` and the 
    370372                             field name would be ``pie_id``. 
    371      
     373 
    372374    ``related_name``         The name to use for the relation from the related 
    373375                             object back to this one.  For example, when if 
    374376                             ``Topping`` has this field:: 
    375                               
     377 
    376378                                    meta.ForeignKey(Pizza) 
    377                                      
     379 
    378380                             the ``related_name`` will be "topping" (taken from 
    379381                             the class name which will in turn give ``Pizza`` 
    380                              methods like ``get_topping_list()`` and  
    381                              ``get_topping_count()``.   
    382                               
     382                             methods like ``get_topping_list()`` and 
     383                             ``get_topping_count()``. 
     384 
    383385                             If you instead were to use:: 
    384                               
     386 
    385387                                    meta.ForeignKey(Pizza, related_name="munchie") 
    386                                      
     388 
    387389                             then the methods would be called 
    388390                             ``get_munchie_list()``, ``get_munchie_count()``, 
    389391                             etc. 
    390                               
     392 
    391393                             This is only really useful when you have a single 
    392394                             object that relates to the same object more than 
    393395                             once.  For example, if a ``Story`` object has both 
    394                              ``primary_category`` and ``secondary_category``   
     396                             ``primary_category`` and ``secondary_category`` 
    395397                             fields, to make sure that the category objects 
    396398                             have the correct methods, you'd use fields like:: 
    397                               
     399 
    398400                                    ... 
    399401                                    meta.ForeignKey(Category, name="primary_category_id", 
    400402                                                    rel_name="primary_category", 
    401403                                                    related_name="primary_story"), 
    402                                                      
     404 
    403405                                    meta.ForeignKey(Category, name="secondary_category_id", 
    404406                                                    rel_name="secondary_category", 
    405407                                                    related_name="secondary_story"), 
    406408                                    ... 
    407                                  
    408                              which would give the category objects methods  
    409                              named ``get_primary_story_list()`` and  
     409 
     410                             which would give the category objects methods 
     411                             named ``get_primary_story_list()`` and 
    410412                             ``get_secondary_story_list()``. 
    411                               
     413 
    412414    ``to_field``             The field on the related object that the relation 
    413                              is to. This is almost always ``id``, but if the 
    414                              PK on the other object is named something  
     415                             is to. This is almost always ``id``, but if the 
     416                             primary key on the other object is named something 
    415417                             different, this is how to indicate that. 
    416418    =======================  ============================================================ 
    417419 
    418 .. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/     
    419          
     420.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/ 
     421 
    420422``ImageField`` 
    421     Like a ``FieldField``, but validates that the uploaded object is a valid  
    422     image. Has two extra optional arguments, ``height_field`` and ``width_field`` 
     423    Like a ``FieldField``, but validates that the uploaded object is a valid 
     424    image. Has two extra optional arguments, ``height_field`` and ``width_field`` 
    423425    which, if set, will be auto-populated with the height and width of the image. 
    424      
     426 
     427    Requires the `Python Imaging Library`_. 
     428 
     429    .. _Python Imaging Library: http://www.pythonware.com/products/pil/ 
     430 
    425431``IntegerField`` 
    426     An integer, surprisingly. 
    427      
     432    An integer. 
     433 
    428434``IPAddressField`` 
    429435    An IP address, in string format (i.e. "24.124.1.30"). 
    430      
     436 
    431437``ManyToManyField`` 
    432438    A many-to-many relation to another object.  For example (taken from the 
    433439    ``core.flatfiles`` object:: 
    434      
     440 
    435441        class FlatFile(meta.Model): 
    436442            fields = ( 
    …… 
    438444                meta.ManyToManyField(Site), 
    439445            ) 
    440      
     446 
    441447    Many-to-many relations are a bit different from other fields.  First, they 
    442     aren't actually a field per se since they use a intermediary join table. 
    443     Second, they don't take any of the same options as the rest of the fields, 
    444     the only options taken are: 
    445      
     448    aren't actually a field per se, because they use a intermediary join table. 
     449    Second, they don't take any of the same options as the rest of the fields. 
     450    The only options taken are: 
     451 
    446452    =======================  ============================================================ 
    447453    Option                   Description 
    448454    =======================  ============================================================ 
    449     ``related_name``         See the description of ``related_name`` in  
     455    ``related_name``         See the description of ``related_name`` in 
    450456                             ``ManyToOneField``, above. 
    451                               
    452     ``filter_interface``     Use a nifty unobtrusive Javascript "filter" interface  
    453                              instead of the usability-challenged ``<select multiple>``. 
    454                              The value should be ``meta.HORIZONTAL`` or ``meta.VERTICAL`` 
    455                              (i.e. should the interface be stacked horizontally or 
     457 
     458    ``filter_interface``     Use a nifty unobtrusive Javascript "filter" interface 
     459                             instead of the usability-challenged ``<select multiple>`` 
     460                             in the admin form for this object. The value should be 
     461                             ``meta.HORIZONTAL`` or ``meta.VERTICAL`` (i.e. 
     462                             should the interface be stacked horizontally or 
    456463                             vertically). 
    457                               
     464 
    458465    ``limit_choices_to``     See the description under ``ManyToOneField``, above. 
    459466    =======================  ============================================================ 
    …… 
    461468``NullBooleanField`` 
    462469    Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this 
    463     instead of a ``BooleanField`` with ``null=True`` . 
    464      
     470    instead of a ``BooleanField`` with ``null=True``. 
     471 
    465472``OneToOneField`` 
    466473    Signifies a one-to-one relationship.  This is most useful on the primary key 
    467     of an object when that object "extends" another object in some way.   
    468      
     474    of an object when that object "extends" another object in some way. 
     475 
    469476    For example, if you are building a database of "places", you would build pretty 
    470477    standard stuff like address, phone number, etc. in the database.  If you then 
    …… 
    475482    the primary key ``id`` field (since one-to-one relations share the same 
    476483    primary key), and has a few in the admin interface: 
    477      
     484 
    478485        * No selection interface is displayed on ``Restaurant`` pages; there will 
    479486          be one (and only one) ``Restaurant`` for each place. 
    480            
     487 
    481488        * On the ``Restaurant`` change list, every single ``Place`` -- weather it 
    482           has an associated ``Restaurant`` or not -- will be displayed. Adding 
     489          has an associated ``Restaurant`` or not -- will be displayed. Adding 
    483490          a ``Restaurant`` to a ``Place`` just means filling out the required 
    484491          ``Restaurant`` fields. 
    …… 
    486493``PhoneNumberField`` 
    487494    Validates that the value is a valid phone number. 
    488      
     495 
    489496``PositiveIntegerField`` 
    490497    Like an ``IntegerField``, but must be positive. 
    491      
     498 
    492499``PositiveSmallIntegerField`` 
    493     Like a ``PositiveIntegerField``, but only allows values below 32767. 
    494      
     500    Like a ``PositiveIntegerField``, but only allows values under a certain 
     501    (database-dependent) point. 
     502 
    495503``SlugField`` 
    496     A "slug" suitable for parts of a URL; only allows alpha-numeric characters and 
    497     underscores.   
    498      
     504    A "slug," suitable for parts of a URL. Only allows alphanumeric characters 
     505    and underscores. 
     506 
    499507    Implies ``maxlength=50`` and ``db_index=True``. 
    500      
    501     Accepts an extra option, ``prepopulate_from`` which is a list of fields from 
    502     which to auto-populate the slug. 
    503      
     508 
     509    Accepts an extra option, ``prepopulate_from``, which is a list of fields 
     510    from which to auto-populate the slug, via JavaScript, in the object's admin 
     511    form. 
     512 
    504513``SmallIntegerField`` 
    505     Like an ``IntegerField``, but must be between -32768 and 32767. 
    506      
     514    Like an ``IntegerField``, but only allows values under a certain 
     515    (database-dependent) point. 
     516 
    507517``TextField`` 
    508518    A large text field (``<textarea>`` in HTML). 
    509      
     519 
    510520``TimeField`` 
    511     A time. Accepts the same auto-population options as ``DateField`` and 
     521    A time. Accepts the same auto-population options as ``DateField`` and 
    512522    ``DateTimeField``. 
    513      
     523 
    514524``URLField`` 
    515     A field for a URL.  If the ``verify_exists`` option is ``True``, the URL given 
    516     will be checked for existence (i.e. actually loads and doesn't give a 404  
    517     response). 
    518      
     525    A field for a URL.  If the ``verify_exists`` option is ``True`` (default), 
     526    the URL given will be checked for existence (i.e., the URL actually loads 
     527    and doesn't give a 404 response). 
     528 
    519529``USStateField`` 
    520     A US state. 
    521      
     530    A two-letter U.S. state abbreviation. 
     531 
    522532``XMLField`` 
    523     A field containing XML.  Takes one required argument, ``schema_path`` which 
    524     is the path to a RelaxNG_ scheme against which to validate the field. 
    525      
     533    A field containing XML. Takes one required argument, ``schema_path``, which 
     534    is the filesystem path to a RelaxNG_ schema against which to validate the 
     535    field. 
     536 
    526537    .. _RelaxNG: http://www.relaxng.org/ 
    527538 
    …… 
    530541 
    531542The ``admin`` field in the model tells Django how to construct the admin 
    532 interface for the object.  The field is an instance of the ``meta.Admin``  
     543interface for the object.  The field is an instance of the ``meta.Admin`` 
    533544object, which has the following options (of which only ``fields`` is required): 
    534545 
    535 ``date_hierarchy``     
     546``date_hierarchy`` 
    536547    To allow filtering of objects in the admin by date, set ``date_hierarchy`` 
    537548    to the name of the field to filter by:: 
    538      
     549 
    539550        date_hierarchy = 'order_date' 
    540      
     551 
    541552``fields`` 
    542553    A list of fieldsets to display on the admin page.  Each fieldset is a 2-tuple: 
    543554    ``(name, field_options)``.  The ``name`` is a string to name the field set, 
    544     and ``field_options`` is a dictionary of information about the fields to be  
    545     displayed in that fieldset. This dictionary has the following keys: 
    546      
     555    and ``field_options`` is a dictionary of information about the fields to be 
     556    displayed in that fieldset. This dictionary has the following keys: 
     557 
    547558