Django

Code

Changeset 41

Show
Ignore:
Timestamp:
07/14/05 19:42:28 (3 years ago)
Author:
jacob
Message:

Made a bunch of doc improvements

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r39 r41  
    33====================== 
    44 
    5 XXX INTRO HERE XXX 
     5Once you've created your `data models`_, you'll need to lookup data from the 
     6database.  This document explains the database abstraction API derived from the 
     7models, and how to create, retrieve, and update objects. 
     8 
     9.. _`data models`: http://www.djangoproject.com/documentation/model_api/ 
    610 
    711Throughout this reference, we'll refer to the following Poll application:: 
    …… 
    288292    SELECT * FROM polls_polls WHERE question LIKE 'Who%' AND id IN (3, 4, 5, 20); 
    289293 
     294Changing objects 
     295================ 
     296 
     297Once you've retrieved an object from the database using any of the above  
     298options, changing it is extremely easy.  Make changes directly to the 
     299objects fields, then call the object's ``save()`` method:: 
     300 
     301    >>> p = polls.get_object(id__exact=15) 
     302    >>> p.slug = "new_slug" 
     303    >>> p.pub_date = datetime.datetime.now() 
     304    >>> p.save() 
     305 
    290306Creating new objects 
    291307==================== 

  • django/trunk/docs/faq.txt

    r5 r41  
    33========== 
    44 
    5 The admin site is ugly!  How can I change it? 
    6 --------------------------------------------- 
     5General questions 
     6================= 
    77 
    8 We think it's very purty, but if you don't agree you can modify the admin site's 
    9 presentation by editing the CSS stylesheet and/or associated image files.  The  
    10 site is built using semantic HTML, so any changes you'd like to make should be 
    11 possible by editing the CSS stylesheet.  We've got a `guide to the CSS used  
    12 in the admin`_ to get you started. 
     8Why does this project exist? 
     9---------------------------- 
    1310 
    14 .. _`guide to the CSS used in the admin`: http://www.djangoproject.com/FIXME/ 
     11Django grew from a very practical need: in our fast-paced newsroom, we often 
     12have only a matter of hours to take a complicated web application from 
     13concept to public launch.  Django was designed to not only allow us to 
     14build web applications quickly, but to allow us to build them right. 
     15 
     16Django would not be possible without a whole host of open-source projects -- 
     17Apache, Python, and PostgresSQL to name a few -- and we're thrilled to be 
     18able to give something back to the open source community. 
    1519 
    1620How do you pronounce "Django"? 
    …… 
    2832one slashdotting.  Yes; it's quite stable. 
    2933 
     34Does Django scale? 
     35------------------ 
     36 
     37Yes.  Compared to development time, hardware is cheap, and so Django is 
     38designed to take advantage of as much hardware as you can throw at it. 
     39Django ships with clean separation of the database layer from the  
     40application layer and a simple yet powerful `cache framework`_. 
     41 
     42.. _`cache framework`: http://www.djangoproject.com/documentation/cache/ 
     43 
    3044Who's behind this? 
    3145------------------ 
    3246 
    3347`Adrian Holovaty`_ 
    34     XXX 
    35      
     48    Adrian is a gypsy-jazz virtuoso, an amateur Beatles historian and a proud 
     49    Chicagoan. He's also a pretty decent programmer, with a knack for whipping 
     50    data into shape and putting it to work for the good of his fellow man. 
     51    Adrian is the lead developer at World Online and the man behind the code at 
     52    chicagocrime.org. 
     53 
    3654`Simon Willison`_ 
    3755    XXX 
    3856 
    3957`Jacob Kaplan-Moss`_ 
    40     XXX 
     58    Jacob is a whipper-snapper from California who spends equal time coding and 
     59    cooking. He does Web development for World Online and actively hacks on 
     60    various cool side projects. He's contributed to the Python-ObjC bindings and 
     61    was the first guy to figure out how to write Tivo apps in Python. Lately 
     62    he's been messing with Python on the PSP. 
    4163 
    42 `Wilson Miner`_. 
    43     XXX 
    44      
     64`Wilson Miner`_ 
     65    Wilson's design-fu makes us all look like rock stars. When not sneaking 
     66    into apartment complex swimming pools  he is the Commercial Development 
     67    Director for World Online, which means he makes the money that pays all our 
     68    paychecks.   
     69         
    4570.. _`Adrian Holovaty`: http://www.holovaty.com/ 
    4671.. _`Simon Willison`: http://simon.incutio.com/ 
    …… 
    4873.. _`Wilson Miner`: http://www.wilsonminer.com/live/ 
    4974 
     75Using Django 
     76============ 
     77 
     78How do I get started? 
     79--------------------- 
     80 
     81... 
     82 
     83The admin interface 
     84=================== 
     85 
     86The admin site is ugly!  How can I change it? 
     87--------------------------------------------- 
     88 
     89We think it's very purty, but if you don't agree you can modify the admin site's 
     90presentation by editing the CSS stylesheet and/or associated image files.  The  
     91site is built using semantic HTML, so any changes you'd like to make should be 
     92possible by editing the CSS stylesheet.  We've got a `guide to the CSS used  
     93in the admin`_ to get you started. 
     94 
     95.. _`guide to the CSS used in the admin`: http://www.djangoproject.com/documentation/admin_css/ 
     96 

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

    r2 r41  
    33=============== 
    44 
    5 XXX INTRO XXX 
     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 all of them. 
    68 
    79Options for models 
    810================== 
    911 
    10 A list of all possible options for a model object follows.  Although there's a wide 
    11 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 possible options, only ``fields`` is required. 
    1214 
    1315``admin`` 
    14 --------- 
    15  
    16 A ``meta.Admin`` object; see `Admin options`_.  If this field isn't given, 
    17 the object will not have an admin interface. 
    18  
     16    A ``meta.Admin`` object; see `Admin options`_.  If this field isn't given, 
     17    the object will not have an admin interface. 
     18     
    1919``db_table`` 
    20 ------------ 
    21  
    22 The name of the database table to use for the module:: 
    23  
    24     db_table = "pizza_orders" 
    25      
    26 If not given, this will use ``app_label + '_' + module_name``. 
    27  
     20    The name of the database table to use for the module:: 
     21     
     22        db_table = "pizza_orders" 
     23         
     24    If not given, this will use ``app_label + '_' + module_name``. 
     25     
    2826``exceptions`` 
    29 -------------- 
    30  
    31 Names of extra exception subclasses to include in the generated module. 
    32 These exceptions are available from instance methods and from module-level 
    33 methods:: 
    34      
    35     exceptions = ("DisgustingToppingsException", "BurntCrust") 
    36  
     27    Names of extra exception subclasses to include in the generated module. 
     28    These exceptions are available from instance methods and from module-level 
     29    methods:: 
     30         
     31        exceptions = ("DisgustingToppingsException", "BurntCrust") 
     32     
    3733``fields`` 
    38 ---------- 
    39  
    40 A list of field objects; see `Field objects`_.  For example:: 
    41  
    42     fields = ( 
    43         meta.CharField('customer_name', 'customer name', maxlength=15), 
    44         meta.BooleanField('use_extra_cheese', 'use extra cheese'), 
    45         meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES), 
    46         ... 
    47     ) 
    48      
     34    A list of field objects; see `Field objects`_.  For example:: 
     35     
     36        fields = ( 
     37            meta.CharField('customer_name', 'customer name', maxlength=15), 
     38            meta.BooleanField('use_extra_cheese', 'use extra cheese'), 
     39            meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES), 
     40            ... 
     41        ) 
     42         
    4943``get_latest_by`` 
    50 ----------------- 
    51  
    52 The name of a date or datetime field; if given, the module will have a 
    53 ``get_latest()`` function which fetches the "latest" object in terms of 
    54 that field:: 
    55  
    56     get_latest_by = "order_date" 
    57  
     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     
     48        get_latest_by = "order_date" 
     49     
    5850``module_constants`` 
    59 -------------------- 
    60  
    61 A dict of name/values to use as extra module-level constants:: 
    62  
    63     module_constants = { 
    64         'MEAT_TYPE_PEPPERONI' : 1, 
    65         'MEAT_TYPE_SAUSAGE' : 2, 
    66     } 
    67  
     51    A dict of name/values to use as extra module-level constants:: 
     52     
     53        module_constants = { 
     54            'MEAT_TYPE_PEPPERONI' : 1, 
     55            'MEAT_TYPE_SAUSAGE' : 2, 
     56        } 
     57     
    6858``module_name`` 
    69 --------------- 
    70  
    71 The name of the module:: 
    72  
    73     module_name = "pizza_orders" 
    74      
    75 If not given this will use a lowercased version of the class name. 
    76  
     59    The name of the module:: 
     60     
     61        module_name = "pizza_orders" 
     62         
     63    If not given this will use a lowercased version of the class name. 
     64     
    7765``order_with_respect_to`` 
    78 ------------------------- 
    79  
    80 Marks this object as "orderable" with respect to the given field.  This is 
    81 almost always used with related objects to allow them to be ordered with 
    82 respect to a parent object.  For example, if a ``PizzaToppping`` relates to 
    83 a ``Pizza`` object, you might use:: 
    84  
    85     order_with_respect_to = 'pizza_id' 
    86  
    87 to allow the toppings to be ordered with respect to the associated pizza. 
    88  
     66    Marks this object as "orderable" with respect to the given field.  This is 
     67    almost always used with related objects to allow them to be ordered with 
     68    respect to a parent object.  For example, if a ``PizzaToppping`` relates to 
     69    a ``Pizza`` object, you might use:: 
     70     
     71        order_with_respect_to = 'pizza_id' 
     72     
     73    to allow the toppings to be ordered with respect to the associated pizza. 
     74     
    8975``ordering`` 
    90 ------------ 
    91  
    92 The default ordering for tho object:: 
    93  
    94     ordering = (('order_date', 'DESC'),) 
    95      
    96 This is a tuple of 2-tuples; each 2-tuple is ``(field_name, ordering_type)`` 
    97 where ordering_type is either ``"ASC"`` or ``"DESC"``.  You may also use the 
    98 magic ``(None, "RANDOM")`` ordering tuple for random ordering. 
    99  
     76    The default ordering for tho object:: 
     77     
     78        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     
    10084``permissions`` 
    101 --------------- 
    102  
    103 Extra permissions to enter into the permissions table when creating this 
    104 object.  A add, delete, and change permission is automatically created for 
    105 each object; this option specifies extra permissions:: 
    106  
    107     permissions = (("may_delivier_pizzas", "Can deliver pizzas"),) 
    108      
    109 This is a list of 2-tuples of  
    110 ``(permission_code, human_readable_permission_name)``. 
    111  
     85    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  
     92    ``(permission_code, human_readable_permission_name)``. 
     93     
    11294``unique_together`` 
    113 ------------------- 
    114  
    115 Sets of field names that, taken together, must be unique:: 
    116  
    117     unique_together = (("driver_id", "restaurant_id"),) 
    118      
    119 This is a list of lists of fields that must be unique when considered 
    120 together. 
    121  
     95    Sets of field names that, taken together, must be unique:: 
     96     
     97        unique_together = (("driver_id", "restaurant_id"),) 
     98         
     99    This is a list of lists of fields that must be unique when considered 
     100    together. 
     101     
    122102``verbose_name`` 
    123 ---------------- 
    124  
    125 A human-readable name for the object, singular:: 
    126  
    127     verbose_name = "pizza" 
    128  
    129 If not given, this will use a munged version of the class name: 
    130 ``CamelCase`` becomes ``camel case``. 
    131  
     103    A human-readable name for the object, singular:: 
     104     
     105        verbose_name = "pizza" 
     106     
     107    If not given, this will use a munged version of the class name: 
     108    ``CamelCase`` becomes ``camel case``. 
     109     
    132110``verbose_name_plural`` 
    133 ----------------------- 
    134  
    135 The plural name for the object:: 
    136  
    137     verbose_name_plural = "stories" 
    138  
    139 If not given, ``verbose_name + "s"`` will automatically be used. 
     111    The plural name for the object:: 
     112     
     113        verbose_name_plural = "stories" 
     114     
     115    If not given, ``verbose_name + "s"`` will automatically be used. 
    140116     
    141117Field objects 
    …… 
    250226Field Types 
    251227----------- 
    252  
     228     
    253229``AutoField`` 
    254 ````````````` 
    255  
    256 An ``IntegerField`` that automatically increments.  You usually won't need to 
    257 use this directly; a primary key field will automatically be added to your  
    258 model if you don't specify otherwise.  That automatically added field is:: 
    259  
    260     meta.AutoField('id', 'ID', primary_key=True) 
    261  
     230    An ``IntegerField`` that automatically increments.  You usually won't need to 
     231    use this directly; a primary key field will automatically be added to your  
     232    model if you don't specify otherwise.  That automatically added field is:: 
     233     
     234        meta.AutoField('id', 'ID', primary_key=True) 
     235     
    262236``BooleanField`` 
    263 ```````````````` 
    264  
    265 A true/false field. 
    266  
     237    A true/false field. 
     238     
    267239``CharField`` 
    268 ````````````` 
    269  
    270 A text field. These are displayed in the admin as single-line text inputs, so  
    271 for large amounts of text use a ``TextField``. 
    272  
    273 ``CharField``s have an extra required argument: ``maxlength``; the maximum  
    274 length (in characters) of the field. 
    275  
     240    A text field. These are displayed in the admin as single-line text inputs, so  
     241    for large amounts of text use a ``TextField``. 
     242     
     243    ``CharField``s have an extra required argument: ``maxlength``; the maximum  
     244    length (in characters) of the field. 
     245     
    276246``CommaSeparatedIntegerField`` 
    277 `````````````````````````````` 
    278  
    279 A field of integers separated by commas. 
    280  
     247    A field of integers separated by commas. 
     248     
    281249``DateField`` 
    282 ````````````` 
    283  
    284 A, um, date field.  Has a few extra optional options: 
    285  
    286     ======================  =================================================== 
    287     Option                  Description 
    288     ======================  =================================================== 
    289     ``auto_now``            Automatically set the field to now every time the 
    290                             object is saved.  Useful for "last-modified" 
    291                             timestamps. 
    292                              
    293     ``auto_now_add``        Automatically set the field to now when the object 
    294                             is first created.  Useful for creation timestamps. 
    295     ======================  =================================================== 
    296  
     250    A, um, date field.  Has a few extra optional options: 
     251     
     252        ======================  =================================================== 
     253        Option                  Description 
     254        ======================  =================================================== 
     255        ``auto_now``            Automatically set the field to now every time the 
     256                                object is saved.  Useful for "last-modified" 
     257                                timestamps. 
     258                                 
     259        ``auto_now_add``        Automatically set the field to now when the object 
     260                                is first created.  Useful for creation timestamps. 
     261        ======================  =================================================== 
     262     
    297263``DateTimeField`` 
    298 ````````````````` 
    299  
    300 A date and time field.  Takes the same extra options as ``DateField``. 
    301  
    302  
     264    A date and time field.  Takes the same extra options as ``DateField``. 
     265     
     266     
    303267``EmailField`` 
    304 `````````````` 
    305  
    306 A ``CharField`` that checks that the value is a valid email address.  Because 
    307 validating email addresses can be tricky, this is a pretty loose test. 
    308  
     268    A ``CharField`` that checks that the value is a valid email address.  Because 
     269    validating email addresses can be tricky, this is a pretty loose test. 
     270     
    309271``FileField`` 
    310 ````````````` 
    311  
    312 A file-upload field.  Takes on additional option, ``upload_to`` which is 
    313 a path to upload the file to.  This path may contain `strftime formatting`_ 
    314 which will be replaced by the date/time of the file upload (so that uploaded 
    315 files don't fill up the given directory). 
    316  
    317 .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941 
    318  
     272    A file-upload field.  Takes on additional option, ``upload_to`` which is 
     273    a path to upload the file to.  This path may contain `strftime formatting`_ 
     274    which will be replaced by the date/time of the file upload (so that uploaded 
     275    files don't fill up the given directory). 
     276     
     277    .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941 
     278     
    319279``FloatField`` 
    320 `````````````` 
    321  
    322 A floating-point number.  Has two additional required options: 
    323  
    324     ======================  =================================================== 
    325     Option                  Description 
    326     ======================  =================================================== 
    327     ``max_digits``          The maximum number of digits allowed in the number. 
    328      
    329     ``decimal_places``      The number of decimal places to store with the 
    330                             number 
    331     ======================  =================================================== 
    332  
    333 For example, to store numbers up to 999 with a resolution of 2 decimal places, 
    334 you'd use:: 
    335  
    336     meta.FloatField(..., max_digits=5, decimal_places=2) 
    337  
    338 And to store numbers up to one million with a resolution of 10 decimal places:: 
    339  
    340     meta.FloatField(..., max_digits=19, decimal_places=10) 
    341  
     280    A floating-point number.  Has two additional required options: 
     281     
     282        ======================  =================================================== 
     283        Option                  Description 
     284        ======================  =================================================== 
     285        ``max_digits``          The maximum number of digits allowed in the number. 
     286         
     287        ``decimal_places``      The number of decimal places to store with the 
     288                                number 
     289        ======================  =================================================== 
     290     
     291    For example, to store numbers up to 999 with a resolution of 2 decimal places, 
     292    you'd use:: 
     293     
     294        meta.FloatField(..., max_digits=5, decimal_places=2) 
     295     
     296    And to store numbers up to one million with a resolution of 10 decimal places:: 
     297     
     298        meta.FloatField(..., max_digits=19, decimal_places=10) 
     299     
    342300``ForeignKey`` 
    343 `````````````` 
    344  
    345 A many-to-one relationship to the primary key in another object.  So, to give a 
    346 ``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are  
    347 many toppings on a pizza):: 
    348  
    349     meta.ForeignKey(Pizza) 
    350      
    351 This is equivalent to (but much clearer than):: 
    352  
    353     meta.IntegerField('pizza_id', 'pizza', rel=meta.ManyToOne(Pizza, 'pizza', 'id')) 
    354      
    355 ``ForeignKey`` fields take all the arguments of ``ManyToOne`` relations (see 
    356 Relationships_, below for what those arguments are), plus the following extra 
    357 options: 
    358  
    359     ======================  =================================================== 
    360     Option                  Description 
    361     ======================  =================================================== 
    362     ``to_field``            The field on the related object that the relation 
    363                             is to.  This is almost always ``id``, but if the 
    364                             PK on the other object is named something  
    365                             different, this is how to indicate that. 
    366                              
    367     ``rel_name``            The name of the relation.  In the above exmaple, 
    368                             this would default to 'pizza' (so that the  
    369                             ``Toppings`` object would have a ``get_pizza()`` 
    370                             function; if you set ``rel_name`` to "pie", then 
    371                             the function would be called ``get_pie()`` and the 
    372                             field name would be ``pie_id``. 
    373     ======================  =================================================== 
    374  
    375      
    376 ``ImageField`` 
    377 `````````````` 
    378  
    379 Like a ``FieldField``, but validates that the uploaded object is a valid  
    380 image.  Has two extra optional arguments, ``height_field`` and ``width_field`` 
    381 which, if set, will be auto-populated with the height and width of the image. 
    382  
    383 ``IntegerField`` 
    384 ```````````````` 
    385  
    386 An integer, surprisingly. 
    387  
    388 ``IPAddressField`` 
    389 `````````````````` 
    390  
    391 An IP address, in string format (i.e. "24.124.1.30"). 
    392  
    393 ``ManyToManyField`` 
    394 ``````````````````` 
    395  
    396 XXX document once Adrian reworks this XXX 
    397  
    398 ``NullBooleanField`` 
    399 ```````````````````` 
    400  
    401 Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this 
    402 instead of a ``BooleanField`` with ``null=True`` . 
    403  
    404 ``PhoneNumberField`` 
    405 ```````````````````` 
    406  
    407 Validates that the value is a valid phone number. 
    408  
    409 ``PositiveIntegerField`` 
    410 ```````````````````````` 
    411  
    412 Like an ``IntegerField``, but must be positive. 
    413  
    414 ``PositiveSmallIntegerField`` 
    415 ````````````````````````````` 
    416  
    417 Like a ``PositiveIntegerField``, but only allows values below 32767. 
    418  
    419  
    420 ``SlugField`` 
    421 ````````````` 
    422  
    423 A "slug" suitable for parts of a URL; only allows alpha-numeric characters and 
    424 underscores.   
    425  
    426 Implies ``maxlength=50`` and ``db_index=True``. 
    427  
    428 Accepts an extra option, ``prepopulate_from`` which is a list of fields from 
    429 which to auto-populate the slug. 
    430  
    431 ``SmallIntegerField`` 
    432 ````````````````````` 
    433  
    434 Like an ``IntegerField``, but must be between -32768 and 32767. 
    435  
    436 ``TextField`` 
    437 ````````````` 
    438  
    439 A large text field (``<textarea>`` in HTML). 
    440  
    441 ``TimeField`` 
    442 ````````````` 
    443  
    444 A time.  Accepts the same auto-population options as ``DateField`` and 
    445 ``DateTimeField``. 
    446  
    447 ``URLField`` 
    448 ```````````` 
    449  
    450 A field for a URL.  If the ``verify_exists`` option is ``True``, the URL given 
    451 will be checked for existence (i.e. actually loads and doesn't give a 404  
    452 response). 
    453  
    454 ``USStateField`` 
    455 ```````````````` 
    456  
    457 A US state. 
    458  
    459 ``XMLField`` 
    460 ```````````` 
    461  
    462 A field containing XML.  Takes one required argument, ``schema_path`` which 
    463 is the path to a RelaxNG_ scheme against which to validate the field. 
    464  
    465 .. _RelaxNG: http://www.relaxng.org/ 
    466  
    467 Relationships 
    468 ============= 
    469  
    470 The ``rel`` option for a field marks that field as being a relationship to 
    471 another object.  For the most common cases, using ``ForeignKey`` or 
    472 ``ManyToManyField`` is best; these "shortcuts" encapsulate best practices 
    473 in database design (i.e. using integer foreign keys into another table's 
    474 primary key).  If you do need to explicitly create a relation, these relation 
    475 objects should be used as the value of the ``rel`` attribute.  Also, all 
    476 the options for ``ManyToOne`` are allowed as options for ``ForeignKey``,  
    477 and the same goes for ``ManyToMany`` and ``ManyToManyField``. 
    478  
    479 ``ManyToOne`` 
    480 ------------- 
    481  
    482 Signifies a many-to-one relation: if a ``Pizza`` can have many ``Topping``s, 
    483 then the ``Topping`` object should have a ``ManyToOne`` relation to ``Pizza``. 
    484  
    485 The three positional arguments to ``ManyToMany`` are: 
    486  
    487     * The class to relate to (i.e. ``Pizza`` or ``core.Site``). 
    488      
    489     * The name of the relation (i.e. ``pizza``, or ``site``); this is used in 
    490       the generated functions for managing that relationship (i.e.  
    491       ``get_pizza`` and ``get_site``). 
    492        
    493     * The name of the field the relationship "points" to.  In most cases this 
    494       will be "id", but if the other object's PK isn't named "id", this 
    495       must match the PK field name. 
    496        
    497 The keyword arguments accepted by ``ManyToOne`` are: 
    498  
    499     =======================  ================================================== 
     301    A many-to-one relationship to the primary key in another object.  So, to give a 
     302    ``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are  
     303    many toppings on a pizza):: 
     304     
     305        meta.ForeignKey(Pizza) 
     306                 
     307    ``ForeignKey`` fields take a large number of options for defining how the  
     308    relationship should work: 
     309     
     310    ======================   =================================================== 
    500311    Option                   Description 
    501     =======================  ================================================== 
     312    ======================   =================================================== 
    502313    ``edit_inline``          If ``True``, this related object is edited  
    503314                             "inline" on the related object's page.  This means 
    …… 
    512323                              
    513324    ``limit_choices_to``     A dictionary of lookup arguments and values (see 
    514                              the `Dictionary API reference`_) to limit choices 
     325                             the `Database API reference`_) to limit choices 
    515326                             of this object to.  Use this along with  
    516327                             ``meta.LazyDate`` to limit choices of objects 
    …… 
    524335                              
    525336                             Not compatible with ``edit_inline``. 
    526      
    527     ``lookup_overrides``     XXX FIXME XXX 
    528337     
    529338    ``max_num_in_admin``     For inline-edited objects, this is the maximum 
    …… 
    557366                              
    558367                             Not used with ``edit_inline``. 
     368                              
     369    ``rel_name``             The name of the relation.  In the above exmaple, 
     370                             this would default to 'pizza' (so that the  
     371                             ``Toppings`` object would have a ``get_pizza()`` 
     372                             function; if you set ``rel_name`` to "pie", then 
     373                             the function would be called ``get_pie()`` and the 
     374                             field name would be ``pie_id``. 
    559375     
    560376    ``related_name``         The name to use for the relation from the related 
    …… 
    597413                             named ``get_primary_story_list()`` and  
    598414                             ``get_secondary_story_list()``. 
     415                              
     416    ``to_field``             The field on the related object that the relation 
     417                             is to.  This is almost always ``id``, but if the 
     418                             PK on the other object is named something  
     419                             different, this is how to indicate that. 
    599420    =======================  ================================================== 
    600421 
    601 .. _`Dictionary API reference`: http://www.djangoproject.com/FIXME/ 
    602  
    603 ``ManyToMany`` 
    604 -------------- 
    605  
    606 XXX will this still exist given the changes to ManyToManyField? XXX 
    607  
    608 ``OneToOne`` 
    609 ------------ 
    610  
    611 Signifies a one-to-one relationship.  This is most useful on the primary key 
    612 of an object when that object "extends" another object in some way.   
    613  
    614 For example, if you are building a database of "places", you would build pretty 
    615 standard stuff like address, phone number, etc. in the database.  If you then 
    616 wanted to build a database of restaurants on top of the places, instead of 
    617 repeating yourself and replicating those fields in the restaurants object, you 
    618 could make ``Restaurant`` have a ``OneToOne`` relation to ``Place`` (since 
    619 a restaurant "is-a" place). 
    620  
    621 This has a few repercussions in the admin interface: 
    622  
    623     * No selection interface is displayed on ``Restaurant`` pages; there will 
    624       be one (and only one) ``Restaurant`` for each place. 
    625        
    626     * On the ``Restaurant`` change list, every single ``Place`` -- weather it 
    627       has an associated ``Restaurant`` or not -- will be displayed.  Adding 
    628       a ``Restaurant`` to a ``Place`` just means filling out the required 
    629       ``Restaurant`` fields. 
     422.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/     
     423         
     424``ImageField`` 
     425    Like a ``FieldField``, but validates that the uploaded object is a valid  
     426    image.  Has two extra optional arguments, ``height_field`` and ``width_field`` 
     427    which, if set, will be auto-populated with the height and width of the image. 
     428     
     429``IntegerField`` 
     430    An integer, surprisingly. 
     431     
     432``IPAddressField`` 
     433    An IP address, in string format (i.e. "24.124.1.30"). 
     434     
     435``ManyToManyField`` 
     436    XXX document once Adrian reworks this XXX 
     437     
     438``NullBooleanField`` 
     439    Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this 
     440    instead of a ``BooleanField`` with ``null=True`` . 
     441     
     442``PhoneNumberField`` 
     443    Validates that the value is a valid phone number. 
     444     
     445``PositiveIntegerField`` 
     446    Like an ``IntegerField``, but must be positive. 
     447     
     448``PositiveSmallIntegerField`` 
     449    Like a ``PositiveIntegerField``, but only allows values below 32767. 
     450     
     451``SlugField`` 
     452    A "slug" suitable for parts of a URL; only allows alpha-numeric characters and 
     453    underscores.   
     454     
     455    Implies ``maxlength=50`` and ``db_index=True``. 
     456     
     457    Accepts an extra option, ``prepopulate_from`` which is a list of fields from 
     458    which to auto-populate the slug. 
     459     
     460``SmallIntegerField`` 
     461    Like an ``IntegerField``, but must be between -32768 and 32767. 
     462     
     463``TextField`` 
     464    A large text field (``<textarea>`` in HTML). 
     465     
     466``TimeField`` 
     467    A time.  Accepts the same auto-population options as ``DateField`` and 
     468    ``DateTimeField``. 
     469     
     470``URLField`` 
     471    A field for a URL.  If the ``verify_exists`` option is ``True``, the URL given 
     472    will be checked for existence (i.e. actually loads and doesn't give a 404  
     473    response). 
     474     
     475``USStateField`` 
     476    A US state. 
     477     
     478``XMLField`` 
     479    A field containing XML.  Takes one required argument, ``schema_path`` which 
     480    is the path to a RelaxNG_ scheme against which to validate the field. 
     481     
     482    .. _RelaxNG: http://www.relaxng.org/ 
    630483 
    631484Admin options 
    …… 
    636489object, which has the following options (of which only ``fields`` is required): 
    637490 
    638 ``date_hierarchy`` 
    639 ------------------ 
    640  
    641 To allow filtering of objects in the admin by date, set ``date_hierarchy`` 
    642 to the name of the field to filter by:: 
    643  
    644     date_hierarchy = 'order_date' 
    645  
     491``date_hierarchy``     
     492    To allow filtering of objects in the admin by date, set ``date_hierarchy`` 
     493    to the name of the field to filter by:: 
     494     
     495        date_hierarchy = 'order_date' 
     496     
    646497``fields`` 
    647 ---------- 
    648  
    649 A list of fieldsets to display on the admin page.  Each fieldset is a 2-tuple: 
    650 ``(name, field_options)``.  The ``name`` is a string to name the field set, 
    651 and ``field_options`` is a dictionary of information about the fields to be  
    652 displayed in that fieldset.  This dictionary has the following keys: 
    653  
    654     ``fields`` 
    655         A tuple of field names to display in this fieldset.  To display 
    656         multiple fields on the same line, wrap those fields in their 
    657         own tuple. 
    658          
    659         This key is required in the dict. 
    660          
    661     ``classes`` 
    662         Extra CSS classes to apply to the fieldset.  This is a simple 
    663         string; you can apply multiple classes by separating them with 
    664         spaces. 
    665          
    666         Two useful classes defined by the default stylesheet are ``collapse`` 
    667         and ``wide``.  Fieldsets with the ``collapse`` style will be  
    668         initially collapsed in the admin and replaced with a small "click 
    669         to expand" link.  Fieldsets with the ``wide`` style will be given 
    670         extra horizontal space. 
     498    A list of fieldsets to display on the admin page.  Each fieldset is a 2-tuple: 
     499    ``(name, field_options)``.  The ``name`` is a string to name the field set, 
     500    and ``field_options`` is a dictionary of information about the fields to be  
     501    displayed in that fieldset.  This dictionary has the following keys: 
     502     
     503        ``fields`` 
     504            A tuple of field names to display in this fieldset.  To display 
     505            multiple fields on the same line, wrap those fields in their 
     506            own tuple. 
    671507             
    672 For example (taken from the ``core.flatfiles`` model):: 
    673  
    674     fields = ( 
    675         (None, { 
    676             'fields': ('url', 'title', 'content', 'sites') 
    677         }), 
    678         ('Advanced options', { 
    679             'classes': 'collapse',  
    680             'fields' : ('enable_comments', 'registration_required', 'template_name') 
    681         }), 
    682     ), 
    683      
    684 results in an admin that looks like: 
    685  
    686     .. image:: images/flatfiles_admin.png 
    687          
     508            This key is required in the dict. 
     509             
     510        ``classes`` 
     511            Extra CSS classes to apply to the fieldset.  This is a simple 
     512            string; you can apply multiple classes by separating them with 
     513            spaces. 
     514             
     515            Two useful classes defined by the default stylesheet are ``collapse`` 
     516            and ``wide``.  Fieldsets with the ``collapse`` style will be  
     517            initially collapsed in the admin and replaced with a small "click 
     518            to expand" link.  Fieldsets with the ``wide`` style will be given 
     519            extra horizontal space. 
     520                 
     521    For example (taken from the ``core.flatfiles`` model):: 
     522     
     523        fields = ( 
     524            (None, { 
     525                'fields': ('url', 'title', 'content', 'sites') 
     526            }), 
     527            ('Advanced options', { 
     528                'classes': 'collapse',  
     529                'fields' : ('enable_comments', 'registration_required', 'template_name') 
     530            }), 
     531        ), 
     532         
     533    results in an admin that looks like: 
     534     
     535        .. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png 
     536             
    688537``js`` 
    689 ------ 
    690  
    691 Extra JavaScript files to link into the admin screen.  This can be used to 
    692 tweak a given type of admin page in JS or to provide "quick links" to fill 
    693 in default values for certain fields. 
    694  
     538    Extra JavaScript files to link into the admin screen.  This can be used to 
     539    tweak a given type of admin page in JS or to provide "quick links" to fill 
     540    in default values for certain fields. 
     541     
    695542``list_display`` 
    696 ---------------- 
    697  
    698 List of fields to display on the list page in the admin. 
    699  
    700 There are a few special cases that do other things besides displaying the 
    701 contents of the given fields: 
    702  
    703     * If the field given has a relationship, that relationship is  
    704       followed and the ``repr()`` of the related object is displayed. 
    705        
    706     * If the field is a ``BooleanField``, a "on" or "off" icon will 
    707       be displayed instead of ``True`` or ``False``. 
    708        
    709     * If the field name given does not exist, a function of the model 
    710       will be searched for and called if present.  This function 
    711       should have a ``short_description`` attribute that will be 
    712       used as the header for the field. 
    713        
    714 See the exmaple below. 
    715  
     543    List of fields to display on the list page in the admin. 
     544     
     545    There are a few special cases that do other things besides displaying the 
     546    contents of the given fields: 
     547     
     548        * If the field given has a relationship, that relationship is  
     549          followed and the ``repr()`` of the related object is displayed. 
     550           
     551        * If the field is a ``BooleanField``, a "on" or "off" icon will 
     552          be displayed instead of ``True`` or ``False``. 
     553           
     554        * If the field name given does not exist, a function of the model 
     555          will be searched for and called if present.  This function 
     556          should have a ``short_description`` attribute that will be 
     557          used as the header for the field. 
     558           
     559    See the exmaple below. 
     560     
    716561``list_filter`` 
    717 --------------- 
    718  
    719 List of fields to filter by.  Each field should either be a ``BooleanField`` 
    720 or else a field with a ``ManyToOne`` relation. 
    721  
    722 An example of how ``list_display`` and ``list_filter`` work (taken from 
    723 the ``auth.user`` model):: 
    724  
    725     list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff'), 
    726     list_filter = ('is_staff', 'is_superuser'), 
    727      
    728 results in a admin that looks like: 
    729  
    730     .. image:: images/users_changelist.png 
    731      
    732 (This example also has ``search_fields`` defined; see below). 
    733  
     562    List of fields to filter by.  Each field should either be a ``BooleanField`` 
     563    or else a field with a ``ManyToOne`` relation. 
     564     
     565    An example of how ``list_display`` and ``list_filter`` work (taken from 
     566    the ``auth.user`` model):: 
     567     
     568        list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff'), 
     569        list_filter = ('is_staff', 'is_superuser'), 
     570         
     571    results in a admin that looks like: 
     572     
     573        .. image:: http://media.djangoproject.com/img/doc/users_changelist.png 
     574         
     575    (This example also has ``search_fields`` defined; see below). 
     576     
    734577``ordering`` 
    735 ------------ 
    736  
    737 An ordering tuple (see the `Options for models`_, above) that gives a  
    738 different ordering for the admin change list.  If not given, the  
    739 model's default ordering will be used. 
    740  
     578    An ordering tuple (see the `Options for models`_, above) that gives a  
     579    different ordering for the admin change list.  If not given, the  
     580    model's default ordering will be used. 
     581     
    741582``save_as`` 
    742 ----------- 
    743  
    744 Enables a "save as" feature on object pages.  Normally, objects have 
    745 three save options: "Save", "Save and continue editing", and "Save 
    746 and add another".   If ``save_as`` is ``True``, "Save and add another" 
    747 will be replaced by a "Save as" button. 
    748  
     583    Enables a "save as" feature on object pages.  Normally, objects have 
     584    three save options: "Save", "Save and continue editing", and "Save 
     585    and add another".   If ``save_as`` is ``True``, "Save and add another" 
     586    will be replaced by a "Save as" button. 
     587     
    749588``save_on_top`` 
    750 --------------- 
    751  
    752 If this option is ``True``, object pages will have the save buttons 
    753 across the top as well as at the bottom of the page. 
    754  
     589    If this option is ``True``, object pages will have the save buttons 
     590    across the top as well as at the bottom of the page. 
     591     
    755592``search_fields`` 
    756 ----------------- 
    757  
    758 A list of fields to provide a text search for.  These fields should, 
    759 obviously, be some kind of text field. 
    760  
     593    A list of fields to provide a text search for.  These fields should, 
     594    obviously, be some kind of text field. 
     595     

  • django/trunk/docs/templates.txt

    r2 r41  
    205205Since Django can be used to develop any sort of site, the tags, filters, and 
    206206variables available will be different depending on the application.  To make it 
    207 simple to figure out what's available in a given site. 
     207simple to figure out what's available in a given site your admin interface 
     208has a complete reference of all the template goodies available to you. 
    208209 
    209210This documentation is integrated into the administration interface for your 
    …… 
    256257