mirror of https://github.com/django/django.git
Made a bunch of doc improvements
git-svn-id: http://code.djangoproject.com/svn/django/trunk@41 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jacob Kaplan-Moss
parent
5fc13947fc
commit
f19dbab514
|
|
@ -2,7 +2,11 @@
|
|||
Database API reference
|
||||
======================
|
||||
|
||||
XXX INTRO HERE XXX
|
||||
Once you've created your `data models`_, you'll need to lookup data from the
|
||||
database. This document explains the database abstraction API derived from the
|
||||
models, and how to create, retrieve, and update objects.
|
||||
|
||||
.. _`data models`: http://www.djangoproject.com/documentation/model_api/
|
||||
|
||||
Throughout this reference, we'll refer to the following Poll application::
|
||||
|
||||
|
|
@ -287,6 +291,18 @@ For example::
|
|||
|
||||
SELECT * FROM polls_polls WHERE question LIKE 'Who%' AND id IN (3, 4, 5, 20);
|
||||
|
||||
Changing objects
|
||||
================
|
||||
|
||||
Once you've retrieved an object from the database using any of the above
|
||||
options, changing it is extremely easy. Make changes directly to the
|
||||
objects fields, then call the object's ``save()`` method::
|
||||
|
||||
>>> p = polls.get_object(id__exact=15)
|
||||
>>> p.slug = "new_slug"
|
||||
>>> p.pub_date = datetime.datetime.now()
|
||||
>>> p.save()
|
||||
|
||||
Creating new objects
|
||||
====================
|
||||
|
||||
|
|
|
|||
71
docs/faq.txt
71
docs/faq.txt
|
|
@ -2,16 +2,20 @@
|
|||
Django FAQ
|
||||
==========
|
||||
|
||||
The admin site is ugly! How can I change it?
|
||||
---------------------------------------------
|
||||
General questions
|
||||
=================
|
||||
|
||||
We think it's very purty, but if you don't agree you can modify the admin site's
|
||||
presentation by editing the CSS stylesheet and/or associated image files. The
|
||||
site is built using semantic HTML, so any changes you'd like to make should be
|
||||
possible by editing the CSS stylesheet. We've got a `guide to the CSS used
|
||||
in the admin`_ to get you started.
|
||||
Why does this project exist?
|
||||
----------------------------
|
||||
|
||||
.. _`guide to the CSS used in the admin`: http://www.djangoproject.com/FIXME/
|
||||
Django grew from a very practical need: in our fast-paced newsroom, we often
|
||||
have only a matter of hours to take a complicated web application from
|
||||
concept to public launch. Django was designed to not only allow us to
|
||||
build web applications quickly, but to allow us to build them right.
|
||||
|
||||
Django would not be possible without a whole host of open-source projects --
|
||||
Apache, Python, and PostgresSQL to name a few -- and we're thrilled to be
|
||||
able to give something back to the open source community.
|
||||
|
||||
How do you pronounce "Django"?
|
||||
------------------------------
|
||||
|
|
@ -27,23 +31,66 @@ We've been using Django for almost two years. Sites built on Django have
|
|||
weathered traffic spikes of over one million hits an hour, and at least
|
||||
one slashdotting. Yes; it's quite stable.
|
||||
|
||||
Does Django scale?
|
||||
------------------
|
||||
|
||||
Yes. Compared to development time, hardware is cheap, and so Django is
|
||||
designed to take advantage of as much hardware as you can throw at it.
|
||||
Django ships with clean separation of the database layer from the
|
||||
application layer and a simple yet powerful `cache framework`_.
|
||||
|
||||
.. _`cache framework`: http://www.djangoproject.com/documentation/cache/
|
||||
|
||||
Who's behind this?
|
||||
------------------
|
||||
|
||||
`Adrian Holovaty`_
|
||||
XXX
|
||||
Adrian is a gypsy-jazz virtuoso, an amateur Beatles historian and a proud
|
||||
Chicagoan. He's also a pretty decent programmer, with a knack for whipping
|
||||
data into shape and putting it to work for the good of his fellow man.
|
||||
Adrian is the lead developer at World Online and the man behind the code at
|
||||
chicagocrime.org.
|
||||
|
||||
`Simon Willison`_
|
||||
XXX
|
||||
|
||||
`Jacob Kaplan-Moss`_
|
||||
XXX
|
||||
Jacob is a whipper-snapper from California who spends equal time coding and
|
||||
cooking. He does Web development for World Online and actively hacks on
|
||||
various cool side projects. He's contributed to the Python-ObjC bindings and
|
||||
was the first guy to figure out how to write Tivo apps in Python. Lately
|
||||
he's been messing with Python on the PSP.
|
||||
|
||||
`Wilson Miner`_.
|
||||
XXX
|
||||
`Wilson Miner`_
|
||||
Wilson's design-fu makes us all look like rock stars. When not sneaking
|
||||
into apartment complex swimming pools he is the Commercial Development
|
||||
Director for World Online, which means he makes the money that pays all our
|
||||
paychecks.
|
||||
|
||||
.. _`Adrian Holovaty`: http://www.holovaty.com/
|
||||
.. _`Simon Willison`: http://simon.incutio.com/
|
||||
.. _`Jacob Kaplan-Moss`: http://www.jacobian.org/
|
||||
.. _`Wilson Miner`: http://www.wilsonminer.com/live/
|
||||
|
||||
Using Django
|
||||
============
|
||||
|
||||
How do I get started?
|
||||
---------------------
|
||||
|
||||
...
|
||||
|
||||
The admin interface
|
||||
===================
|
||||
|
||||
The admin site is ugly! How can I change it?
|
||||
---------------------------------------------
|
||||
|
||||
We think it's very purty, but if you don't agree you can modify the admin site's
|
||||
presentation by editing the CSS stylesheet and/or associated image files. The
|
||||
site is built using semantic HTML, so any changes you'd like to make should be
|
||||
possible by editing the CSS stylesheet. We've got a `guide to the CSS used
|
||||
in the admin`_ to get you started.
|
||||
|
||||
.. _`guide to the CSS used in the admin`: http://www.djangoproject.com/documentation/admin_css/
|
||||
|
||||
|
|
|
|||
|
|
@ -2,23 +2,21 @@
|
|||
Model reference
|
||||
===============
|
||||
|
||||
XXX INTRO XXX
|
||||
Django's models are the bread and butter of the framework. There's a huge
|
||||
array of options available to you when defining your data models; this
|
||||
document explains all of them.
|
||||
|
||||
Options for models
|
||||
==================
|
||||
|
||||
A list of all possible options for a model object follows. Although there's a wide
|
||||
array of possible options, only ``fields`` is required.
|
||||
A list of all possible options for a model object follows. Although there's a
|
||||
wide array of possible options, only ``fields`` is required.
|
||||
|
||||
``admin``
|
||||
---------
|
||||
|
||||
A ``meta.Admin`` object; see `Admin options`_. If this field isn't given,
|
||||
the object will not have an admin interface.
|
||||
|
||||
``db_table``
|
||||
------------
|
||||
|
||||
The name of the database table to use for the module::
|
||||
|
||||
db_table = "pizza_orders"
|
||||
|
|
@ -26,8 +24,6 @@ The name of the database table to use for the module::
|
|||
If not given, this will use ``app_label + '_' + module_name``.
|
||||
|
||||
``exceptions``
|
||||
--------------
|
||||
|
||||
Names of extra exception subclasses to include in the generated module.
|
||||
These exceptions are available from instance methods and from module-level
|
||||
methods::
|
||||
|
|
@ -35,8 +31,6 @@ methods::
|
|||
exceptions = ("DisgustingToppingsException", "BurntCrust")
|
||||
|
||||
``fields``
|
||||
----------
|
||||
|
||||
A list of field objects; see `Field objects`_. For example::
|
||||
|
||||
fields = (
|
||||
|
|
@ -47,8 +41,6 @@ A list of field objects; see `Field objects`_. For example::
|
|||
)
|
||||
|
||||
``get_latest_by``
|
||||
-----------------
|
||||
|
||||
The name of a date or datetime field; if given, the module will have a
|
||||
``get_latest()`` function which fetches the "latest" object in terms of
|
||||
that field::
|
||||
|
|
@ -56,8 +48,6 @@ that field::
|
|||
get_latest_by = "order_date"
|
||||
|
||||
``module_constants``
|
||||
--------------------
|
||||
|
||||
A dict of name/values to use as extra module-level constants::
|
||||
|
||||
module_constants = {
|
||||
|
|
@ -66,8 +56,6 @@ A dict of name/values to use as extra module-level constants::
|
|||
}
|
||||
|
||||
``module_name``
|
||||
---------------
|
||||
|
||||
The name of the module::
|
||||
|
||||
module_name = "pizza_orders"
|
||||
|
|
@ -75,8 +63,6 @@ The name of the module::
|
|||
If not given this will use a lowercased version of the class name.
|
||||
|
||||
``order_with_respect_to``
|
||||
-------------------------
|
||||
|
||||
Marks this object as "orderable" with respect to the given field. This is
|
||||
almost always used with related objects to allow them to be ordered with
|
||||
respect to a parent object. For example, if a ``PizzaToppping`` relates to
|
||||
|
|
@ -87,8 +73,6 @@ a ``Pizza`` object, you might use::
|
|||
to allow the toppings to be ordered with respect to the associated pizza.
|
||||
|
||||
``ordering``
|
||||
------------
|
||||
|
||||
The default ordering for tho object::
|
||||
|
||||
ordering = (('order_date', 'DESC'),)
|
||||
|
|
@ -98,8 +82,6 @@ where ordering_type is either ``"ASC"`` or ``"DESC"``. You may also use the
|
|||
magic ``(None, "RANDOM")`` ordering tuple for random ordering.
|
||||
|
||||
``permissions``
|
||||
---------------
|
||||
|
||||
Extra permissions to enter into the permissions table when creating this
|
||||
object. A add, delete, and change permission is automatically created for
|
||||
each object; this option specifies extra permissions::
|
||||
|
|
@ -110,8 +92,6 @@ This is a list of 2-tuples of
|
|||
``(permission_code, human_readable_permission_name)``.
|
||||
|
||||
``unique_together``
|
||||
-------------------
|
||||
|
||||
Sets of field names that, taken together, must be unique::
|
||||
|
||||
unique_together = (("driver_id", "restaurant_id"),)
|
||||
|
|
@ -120,8 +100,6 @@ This is a list of lists of fields that must be unique when considered
|
|||
together.
|
||||
|
||||
``verbose_name``
|
||||
----------------
|
||||
|
||||
A human-readable name for the object, singular::
|
||||
|
||||
verbose_name = "pizza"
|
||||
|
|
@ -130,8 +108,6 @@ If not given, this will use a munged version of the class name:
|
|||
``CamelCase`` becomes ``camel case``.
|
||||
|
||||
``verbose_name_plural``
|
||||
-----------------------
|
||||
|
||||
The plural name for the object::
|
||||
|
||||
verbose_name_plural = "stories"
|
||||
|
|
@ -251,8 +227,6 @@ Field Types
|
|||
-----------
|
||||
|
||||
``AutoField``
|
||||
`````````````
|
||||
|
||||
An ``IntegerField`` that automatically increments. You usually won't need to
|
||||
use this directly; a primary key field will automatically be added to your
|
||||
model if you don't specify otherwise. That automatically added field is::
|
||||
|
|
@ -260,13 +234,9 @@ model if you don't specify otherwise. That automatically added field is::
|
|||
meta.AutoField('id', 'ID', primary_key=True)
|
||||
|
||||
``BooleanField``
|
||||
````````````````
|
||||
|
||||
A true/false field.
|
||||
|
||||
``CharField``
|
||||
`````````````
|
||||
|
||||
A text field. These are displayed in the admin as single-line text inputs, so
|
||||
for large amounts of text use a ``TextField``.
|
||||
|
||||
|
|
@ -274,13 +244,9 @@ for large amounts of text use a ``TextField``.
|
|||
length (in characters) of the field.
|
||||
|
||||
``CommaSeparatedIntegerField``
|
||||
``````````````````````````````
|
||||
|
||||
A field of integers separated by commas.
|
||||
|
||||
``DateField``
|
||||
`````````````
|
||||
|
||||
A, um, date field. Has a few extra optional options:
|
||||
|
||||
====================== ===================================================
|
||||
|
|
@ -295,20 +261,14 @@ A, um, date field. Has a few extra optional options:
|
|||
====================== ===================================================
|
||||
|
||||
``DateTimeField``
|
||||
`````````````````
|
||||
|
||||
A date and time field. Takes the same extra options as ``DateField``.
|
||||
|
||||
|
||||
``EmailField``
|
||||
``````````````
|
||||
|
||||
A ``CharField`` that checks that the value is a valid email address. Because
|
||||
validating email addresses can be tricky, this is a pretty loose test.
|
||||
|
||||
``FileField``
|
||||
`````````````
|
||||
|
||||
A file-upload field. Takes on additional option, ``upload_to`` which is
|
||||
a path to upload the file to. This path may contain `strftime formatting`_
|
||||
which will be replaced by the date/time of the file upload (so that uploaded
|
||||
|
|
@ -317,8 +277,6 @@ files don't fill up the given directory).
|
|||
.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
|
||||
|
||||
``FloatField``
|
||||
``````````````
|
||||
|
||||
A floating-point number. Has two additional required options:
|
||||
|
||||
====================== ===================================================
|
||||
|
|
@ -340,161 +298,14 @@ And to store numbers up to one million with a resolution of 10 decimal places::
|
|||
meta.FloatField(..., max_digits=19, decimal_places=10)
|
||||
|
||||
``ForeignKey``
|
||||
``````````````
|
||||
|
||||
A many-to-one relationship to the primary key in another object. So, to give a
|
||||
``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are
|
||||
many toppings on a pizza)::
|
||||
|
||||
meta.ForeignKey(Pizza)
|
||||
|
||||
This is equivalent to (but much clearer than)::
|
||||
|
||||
meta.IntegerField('pizza_id', 'pizza', rel=meta.ManyToOne(Pizza, 'pizza', 'id'))
|
||||
|
||||
``ForeignKey`` fields take all the arguments of ``ManyToOne`` relations (see
|
||||
Relationships_, below for what those arguments are), plus the following extra
|
||||
options:
|
||||
|
||||
====================== ===================================================
|
||||
Option Description
|
||||
====================== ===================================================
|
||||
``to_field`` The field on the related object that the relation
|
||||
is to. This is almost always ``id``, but if the
|
||||
PK on the other object is named something
|
||||
different, this is how to indicate that.
|
||||
|
||||
``rel_name`` The name of the relation. In the above exmaple,
|
||||
this would default to 'pizza' (so that the
|
||||
``Toppings`` object would have a ``get_pizza()``
|
||||
function; if you set ``rel_name`` to "pie", then
|
||||
the function would be called ``get_pie()`` and the
|
||||
field name would be ``pie_id``.
|
||||
====================== ===================================================
|
||||
|
||||
|
||||
``ImageField``
|
||||
``````````````
|
||||
|
||||
Like a ``FieldField``, but validates that the uploaded object is a valid
|
||||
image. Has two extra optional arguments, ``height_field`` and ``width_field``
|
||||
which, if set, will be auto-populated with the height and width of the image.
|
||||
|
||||
``IntegerField``
|
||||
````````````````
|
||||
|
||||
An integer, surprisingly.
|
||||
|
||||
``IPAddressField``
|
||||
``````````````````
|
||||
|
||||
An IP address, in string format (i.e. "24.124.1.30").
|
||||
|
||||
``ManyToManyField``
|
||||
```````````````````
|
||||
|
||||
XXX document once Adrian reworks this XXX
|
||||
|
||||
``NullBooleanField``
|
||||
````````````````````
|
||||
|
||||
Like a ``BooleanField``, but allows ``NULL`` as one of the options. Use this
|
||||
instead of a ``BooleanField`` with ``null=True`` .
|
||||
|
||||
``PhoneNumberField``
|
||||
````````````````````
|
||||
|
||||
Validates that the value is a valid phone number.
|
||||
|
||||
``PositiveIntegerField``
|
||||
````````````````````````
|
||||
|
||||
Like an ``IntegerField``, but must be positive.
|
||||
|
||||
``PositiveSmallIntegerField``
|
||||
`````````````````````````````
|
||||
|
||||
Like a ``PositiveIntegerField``, but only allows values below 32767.
|
||||
|
||||
|
||||
``SlugField``
|
||||
`````````````
|
||||
|
||||
A "slug" suitable for parts of a URL; only allows alpha-numeric characters and
|
||||
underscores.
|
||||
|
||||
Implies ``maxlength=50`` and ``db_index=True``.
|
||||
|
||||
Accepts an extra option, ``prepopulate_from`` which is a list of fields from
|
||||
which to auto-populate the slug.
|
||||
|
||||
``SmallIntegerField``
|
||||
`````````````````````
|
||||
|
||||
Like an ``IntegerField``, but must be between -32768 and 32767.
|
||||
|
||||
``TextField``
|
||||
`````````````
|
||||
|
||||
A large text field (``<textarea>`` in HTML).
|
||||
|
||||
``TimeField``
|
||||
`````````````
|
||||
|
||||
A time. Accepts the same auto-population options as ``DateField`` and
|
||||
``DateTimeField``.
|
||||
|
||||
``URLField``
|
||||
````````````
|
||||
|
||||
A field for a URL. If the ``verify_exists`` option is ``True``, the URL given
|
||||
will be checked for existence (i.e. actually loads and doesn't give a 404
|
||||
response).
|
||||
|
||||
``USStateField``
|
||||
````````````````
|
||||
|
||||
A US state.
|
||||
|
||||
``XMLField``
|
||||
````````````
|
||||
|
||||
A field containing XML. Takes one required argument, ``schema_path`` which
|
||||
is the path to a RelaxNG_ scheme against which to validate the field.
|
||||
|
||||
.. _RelaxNG: http://www.relaxng.org/
|
||||
|
||||
Relationships
|
||||
=============
|
||||
|
||||
The ``rel`` option for a field marks that field as being a relationship to
|
||||
another object. For the most common cases, using ``ForeignKey`` or
|
||||
``ManyToManyField`` is best; these "shortcuts" encapsulate best practices
|
||||
in database design (i.e. using integer foreign keys into another table's
|
||||
primary key). If you do need to explicitly create a relation, these relation
|
||||
objects should be used as the value of the ``rel`` attribute. Also, all
|
||||
the options for ``ManyToOne`` are allowed as options for ``ForeignKey``,
|
||||
and the same goes for ``ManyToMany`` and ``ManyToManyField``.
|
||||
|
||||
``ManyToOne``
|
||||
-------------
|
||||
|
||||
Signifies a many-to-one relation: if a ``Pizza`` can have many ``Topping``s,
|
||||
then the ``Topping`` object should have a ``ManyToOne`` relation to ``Pizza``.
|
||||
|
||||
The three positional arguments to ``ManyToMany`` are:
|
||||
|
||||
* The class to relate to (i.e. ``Pizza`` or ``core.Site``).
|
||||
|
||||
* The name of the relation (i.e. ``pizza``, or ``site``); this is used in
|
||||
the generated functions for managing that relationship (i.e.
|
||||
``get_pizza`` and ``get_site``).
|
||||
|
||||
* The name of the field the relationship "points" to. In most cases this
|
||||
will be "id", but if the other object's PK isn't named "id", this
|
||||
must match the PK field name.
|
||||
|
||||
The keyword arguments accepted by ``ManyToOne`` are:
|
||||
``ForeignKey`` fields take a large number of options for defining how the
|
||||
relationship should work:
|
||||
|
||||
====================== ===================================================
|
||||
Option Description
|
||||
|
|
@ -511,7 +322,7 @@ The keyword arguments accepted by ``ManyToOne`` are:
|
|||
``meta.STACKED``.
|
||||
|
||||
``limit_choices_to`` A dictionary of lookup arguments and values (see
|
||||
the `Dictionary API reference`_) to limit choices
|
||||
the `Database API reference`_) to limit choices
|
||||
of this object to. Use this along with
|
||||
``meta.LazyDate`` to limit choices of objects
|
||||
by date, for example::
|
||||
|
|
@ -524,8 +335,6 @@ The keyword arguments accepted by ``ManyToOne`` are:
|
|||
|
||||
Not compatible with ``edit_inline``.
|
||||
|
||||
``lookup_overrides`` XXX FIXME XXX
|
||||
|
||||
``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
|
||||
|
|
@ -557,6 +366,13 @@ The keyword arguments accepted by ``ManyToOne`` are:
|
|||
|
||||
Not used with ``edit_inline``.
|
||||
|
||||
``rel_name`` The name of the relation. In the above exmaple,
|
||||
this would default to 'pizza' (so that the
|
||||
``Toppings`` object would have a ``get_pizza()``
|
||||
function; if you set ``rel_name`` to "pie", then
|
||||
the function would be called ``get_pie()`` and the
|
||||
field name would be ``pie_id``.
|
||||
|
||||
``related_name`` The name to use for the relation from the related
|
||||
object back to this one. For example, when if
|
||||
``Topping`` has this field::
|
||||
|
|
@ -596,37 +412,74 @@ The keyword arguments accepted by ``ManyToOne`` are:
|
|||
which would give the category objects methods
|
||||
named ``get_primary_story_list()`` and
|
||||
``get_secondary_story_list()``.
|
||||
|
||||
``to_field`` The field on the related object that the relation
|
||||
is to. This is almost always ``id``, but if the
|
||||
PK on the other object is named something
|
||||
different, this is how to indicate that.
|
||||
======================= ==================================================
|
||||
|
||||
.. _`Dictionary API reference`: http://www.djangoproject.com/FIXME/
|
||||
.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/
|
||||
|
||||
``ManyToMany``
|
||||
--------------
|
||||
``ImageField``
|
||||
Like a ``FieldField``, but validates that the uploaded object is a valid
|
||||
image. Has two extra optional arguments, ``height_field`` and ``width_field``
|
||||
which, if set, will be auto-populated with the height and width of the image.
|
||||
|
||||
XXX will this still exist given the changes to ManyToManyField? XXX
|
||||
``IntegerField``
|
||||
An integer, surprisingly.
|
||||
|
||||
``OneToOne``
|
||||
------------
|
||||
``IPAddressField``
|
||||
An IP address, in string format (i.e. "24.124.1.30").
|
||||
|
||||
Signifies a one-to-one relationship. This is most useful on the primary key
|
||||
of an object when that object "extends" another object in some way.
|
||||
``ManyToManyField``
|
||||
XXX document once Adrian reworks this XXX
|
||||
|
||||
For example, if you are building a database of "places", you would build pretty
|
||||
standard stuff like address, phone number, etc. in the database. If you then
|
||||
wanted to build a database of restaurants on top of the places, instead of
|
||||
repeating yourself and replicating those fields in the restaurants object, you
|
||||
could make ``Restaurant`` have a ``OneToOne`` relation to ``Place`` (since
|
||||
a restaurant "is-a" place).
|
||||
``NullBooleanField``
|
||||
Like a ``BooleanField``, but allows ``NULL`` as one of the options. Use this
|
||||
instead of a ``BooleanField`` with ``null=True`` .
|
||||
|
||||
This has a few repercussions in the admin interface:
|
||||
``PhoneNumberField``
|
||||
Validates that the value is a valid phone number.
|
||||
|
||||
* No selection interface is displayed on ``Restaurant`` pages; there will
|
||||
be one (and only one) ``Restaurant`` for each place.
|
||||
``PositiveIntegerField``
|
||||
Like an ``IntegerField``, but must be positive.
|
||||
|
||||
* On the ``Restaurant`` change list, every single ``Place`` -- weather it
|
||||
has an associated ``Restaurant`` or not -- will be displayed. Adding
|
||||
a ``Restaurant`` to a ``Place`` just means filling out the required
|
||||
``Restaurant`` fields.
|
||||
``PositiveSmallIntegerField``
|
||||
Like a ``PositiveIntegerField``, but only allows values below 32767.
|
||||
|
||||
``SlugField``
|
||||
A "slug" suitable for parts of a URL; only allows alpha-numeric characters and
|
||||
underscores.
|
||||
|
||||
Implies ``maxlength=50`` and ``db_index=True``.
|
||||
|
||||
Accepts an extra option, ``prepopulate_from`` which is a list of fields from
|
||||
which to auto-populate the slug.
|
||||
|
||||
``SmallIntegerField``
|
||||
Like an ``IntegerField``, but must be between -32768 and 32767.
|
||||
|
||||
``TextField``
|
||||
A large text field (``<textarea>`` in HTML).
|
||||
|
||||
``TimeField``
|
||||
A time. Accepts the same auto-population options as ``DateField`` and
|
||||
``DateTimeField``.
|
||||
|
||||
``URLField``
|
||||
A field for a URL. If the ``verify_exists`` option is ``True``, the URL given
|
||||
will be checked for existence (i.e. actually loads and doesn't give a 404
|
||||
response).
|
||||
|
||||
``USStateField``
|
||||
A US state.
|
||||
|
||||
``XMLField``
|
||||
A field containing XML. Takes one required argument, ``schema_path`` which
|
||||
is the path to a RelaxNG_ scheme against which to validate the field.
|
||||
|
||||
.. _RelaxNG: http://www.relaxng.org/
|
||||
|
||||
Admin options
|
||||
=============
|
||||
|
|
@ -636,16 +489,12 @@ interface for the object. The field is an instance of the ``meta.Admin``
|
|||
object, which has the following options (of which only ``fields`` is required):
|
||||
|
||||
``date_hierarchy``
|
||||
------------------
|
||||
|
||||
To allow filtering of objects in the admin by date, set ``date_hierarchy``
|
||||
to the name of the field to filter by::
|
||||
|
||||
date_hierarchy = 'order_date'
|
||||
|
||||
``fields``
|
||||
----------
|
||||
|
||||
A list of fieldsets to display on the admin page. Each fieldset is a 2-tuple:
|
||||
``(name, field_options)``. The ``name`` is a string to name the field set,
|
||||
and ``field_options`` is a dictionary of information about the fields to be
|
||||
|
|
@ -683,18 +532,14 @@ For example (taken from the ``core.flatfiles`` model)::
|
|||
|
||||
results in an admin that looks like:
|
||||
|
||||
.. image:: images/flatfiles_admin.png
|
||||
.. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
|
||||
|
||||
``js``
|
||||
------
|
||||
|
||||
Extra JavaScript files to link into the admin screen. This can be used to
|
||||
tweak a given type of admin page in JS or to provide "quick links" to fill
|
||||
in default values for certain fields.
|
||||
|
||||
``list_display``
|
||||
----------------
|
||||
|
||||
List of fields to display on the list page in the admin.
|
||||
|
||||
There are a few special cases that do other things besides displaying the
|
||||
|
|
@ -714,8 +559,6 @@ contents of the given fields:
|
|||
See the exmaple below.
|
||||
|
||||
``list_filter``
|
||||
---------------
|
||||
|
||||
List of fields to filter by. Each field should either be a ``BooleanField``
|
||||
or else a field with a ``ManyToOne`` relation.
|
||||
|
||||
|
|
@ -727,34 +570,26 @@ the ``auth.user`` model)::
|
|||
|
||||
results in a admin that looks like:
|
||||
|
||||
.. image:: images/users_changelist.png
|
||||
.. image:: http://media.djangoproject.com/img/doc/users_changelist.png
|
||||
|
||||
(This example also has ``search_fields`` defined; see below).
|
||||
|
||||
``ordering``
|
||||
------------
|
||||
|
||||
An ordering tuple (see the `Options for models`_, above) that gives a
|
||||
different ordering for the admin change list. If not given, the
|
||||
model's default ordering will be used.
|
||||
|
||||
``save_as``
|
||||
-----------
|
||||
|
||||
Enables a "save as" feature on object pages. 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_on_top``
|
||||
---------------
|
||||
|
||||
If this option is ``True``, object pages will have the save buttons
|
||||
across the top as well as at the bottom of the page.
|
||||
|
||||
``search_fields``
|
||||
-----------------
|
||||
|
||||
A list of fields to provide a text search for. These fields should,
|
||||
obviously, be some kind of text field.
|
||||
|
||||
|
|
|
|||
|
|
@ -204,7 +204,8 @@ Using the built-in reference
|
|||
|
||||
Since Django can be used to develop any sort of site, the tags, filters, and
|
||||
variables available will be different depending on the application. To make it
|
||||
simple to figure out what's available in a given site.
|
||||
simple to figure out what's available in a given site your admin interface
|
||||
has a complete reference of all the template goodies available to you.
|
||||
|
||||
This documentation is integrated into the administration interface for your
|
||||
sites and is divided into 4 sections: tags, filters, models, and views. The
|
||||
|
|
@ -255,20 +256,14 @@ tags/filters.
|
|||
Built-in tag reference
|
||||
----------------------
|
||||
|
||||
block
|
||||
`````
|
||||
|
||||
``block``
|
||||
Define a block that can be overridden by child templates. See `Template
|
||||
inheritance`_ for more information.
|
||||
|
||||
comment
|
||||
```````
|
||||
|
||||
``comment``
|
||||
Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
|
||||
|
||||
cycle
|
||||
`````
|
||||
|
||||
``cycle``
|
||||
Cycle among the given strings each time this tag is encountered.
|
||||
|
||||
Within a loop, cycles among the given strings each time through
|
||||
|
|
@ -290,15 +285,11 @@ then use that name each successive time through::
|
|||
You can use any number of values, separated by commas. Make sure not to put
|
||||
spaces between the values -- only commas.
|
||||
|
||||
debug
|
||||
`````
|
||||
|
||||
``debug``
|
||||
Output a whole load of debugging information, including the current context and
|
||||
imported modules.
|
||||
|
||||
extends
|
||||
```````
|
||||
|
||||
``extends``
|
||||
Signal that this template extends a parent template.
|
||||
|
||||
This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
|
||||
|
|
@ -308,9 +299,7 @@ template to extend.
|
|||
|
||||
See `Template inheritance`_ for more information.
|
||||
|
||||
filter
|
||||
``````
|
||||
|
||||
``filter``
|
||||
Filter the contents of the blog through variable filters.
|
||||
|
||||
Filters can also be piped through each other, and they can have arguments --
|
||||
|
|
@ -322,9 +311,7 @@ Sample usage::
|
|||
This text will be HTML-escaped, and will appear in all lowercase.
|
||||
{% endfilter %}
|
||||
|
||||
firstof
|
||||
```````
|
||||
|
||||
``firstof``
|
||||
Outputs the first variable passed that is not False. Outputs nothing if all the
|
||||
passed variables are False.
|
||||
|
||||
|
|
@ -344,9 +331,7 @@ This is equivalent to::
|
|||
|
||||
but obviously much cleaner!
|
||||
|
||||
for
|
||||
```
|
||||
|
||||
``for``
|
||||
Loop over each item in an array. For example, to display a list of athletes
|
||||
given ``athlete_list``::
|
||||
|
||||
|
|
@ -371,9 +356,7 @@ The for loop sets a number of variables available within the loop:
|
|||
current one
|
||||
========================== ================================================
|
||||
|
||||
if
|
||||
``
|
||||
|
||||
``if``
|
||||
The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
|
||||
exists, is not empty, and is not a false boolean value) the contents of the
|
||||
block are output::
|
||||
|
|
@ -417,9 +400,7 @@ tags instead::
|
|||
{% endif %}
|
||||
{% endif %}
|
||||
|
||||
ifchanged
|
||||
`````````
|
||||
|
||||
``ifchanged``
|
||||
Check if a value has changed from the last iteration of a loop.
|
||||
|
||||
The 'ifchanged' block tag is used within a loop. It checks its own rendered
|
||||
|
|
@ -433,9 +414,7 @@ has changed::
|
|||
<a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
|
||||
{% endfor %}
|
||||
|
||||
ifnotequal
|
||||
``````````
|
||||
|
||||
``ifnotequal``
|
||||
Output the contents of the block if the two arguments do not equal each other.
|
||||
|
||||
Example::
|
||||
|
|
@ -444,16 +423,12 @@ Example::
|
|||
...
|
||||
{% endifnotequal %}
|
||||
|
||||
load
|
||||
````
|
||||
|
||||
``load``
|
||||
Load a custom template tag set.
|
||||
|
||||
See `Custom tag and filter libraries`_ for more information.
|
||||
|
||||
now
|
||||
```
|
||||
|
||||
``now``
|
||||
Display the date, formatted according to the given string.
|
||||
|
||||
Uses the same format as PHP's ``date()`` function; see http://php.net/date
|
||||
|
|
@ -463,9 +438,7 @@ Sample usage::
|
|||
|
||||
It is {% now "jS F Y H:i" %}
|
||||
|
||||
regroup
|
||||
```````
|
||||
|
||||
``regroup``
|
||||
Regroup a list of alike objects by a common attribute.
|
||||
|
||||
This complex tag is best illustrated by use of an example: say that ``people``
|
||||
|
|
@ -508,9 +481,7 @@ i.e.::
|
|||
|
||||
{% regroup people|dictsort:"gender" by gender as grouped %}
|
||||
|
||||
ssi
|
||||
```
|
||||
|
||||
``ssi``
|
||||
Output the contents of a given file into the page.
|
||||
|
||||
Like a simple "include" tag, the ``ssi`` tag includes the contents
|
||||
|
|
@ -524,9 +495,7 @@ file are evaluated as template code, with the current context::
|
|||
|
||||
{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
|
||||
|
||||
templatetag
|
||||
```````````
|
||||
|
||||
``templatetag``
|
||||
Output one of the bits used to compose template tags.
|
||||
|
||||
Since the template system has no concept of "escaping", to display one of the
|
||||
|
|
@ -543,9 +512,7 @@ The argument tells which template bit to output:
|
|||
``closevariable`` ``}}``
|
||||
================== =======
|
||||
|
||||
widthratio
|
||||
``````````
|
||||
|
||||
``widthratio``
|
||||
For creating bar charts and such, this tag calculates the ratio of a given value
|
||||
to a maximum value, and then applies that ratio to a constant.
|
||||
|
||||
|
|
@ -560,156 +527,122 @@ which is rounded up to 88).
|
|||
Built-in filter reference
|
||||
-------------------------
|
||||
|
||||
add
|
||||
```
|
||||
``add``
|
||||
Adds the arg to the value
|
||||
|
||||
addslashes
|
||||
``````````
|
||||
``addslashes``
|
||||
Adds slashes - useful for passing strings to JavaScript, for example.
|
||||
|
||||
capfirst
|
||||
````````
|
||||
``capfirst``
|
||||
Capitalizes the first character of the value
|
||||
|
||||
center
|
||||
``````
|
||||
``center``
|
||||
Centers the value in a field of a given width
|
||||
|
||||
cut
|
||||
```
|
||||
``cut``
|
||||
Removes all values of arg from the given string
|
||||
|
||||
date
|
||||
````
|
||||
``date``
|
||||
Formats a date according to the given format (same as the now_ tag)
|
||||
|
||||
default
|
||||
```````
|
||||
``default``
|
||||
If value is unavailable, use given default
|
||||
|
||||
dictsort
|
||||
````````
|
||||
``dictsort``
|
||||
Takes a list of dicts, returns that list sorted by the property given in the
|
||||
argument.
|
||||
|
||||
dictsortreversed
|
||||
````````````````
|
||||
``dictsortreversed``
|
||||
Takes a list of dicts, returns that list sorted in reverse order by the property
|
||||
given in the argument.
|
||||
|
||||
divisibleby
|
||||
```````````
|
||||
``divisibleby``
|
||||
Returns true if the value is divisible by the argument
|
||||
|
||||
escape
|
||||
``````
|
||||
``escape``
|
||||
Escapes a string's HTML
|
||||
|
||||
filesizeformat
|
||||
``````````````
|
||||
``filesizeformat``
|
||||
Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
|
||||
bytes, etc).
|
||||
|
||||
first
|
||||
`````
|
||||
``first``
|
||||
Returns the first item in a list
|
||||
|
||||
fix_ampersands
|
||||
``````````````
|
||||
``fix_ampersands``
|
||||
Replaces ampersands with ``&`` entities
|
||||
|
||||
floatformat
|
||||
```````````
|
||||
``floatformat``
|
||||
Displays a floating point number as 34.2 (with one decimal places) - but
|
||||
only if there's a point to be displayed
|
||||
|
||||
get_digit
|
||||
`````````
|
||||
``get_digit``
|
||||
Given a whole number, returns the requested digit of it, where 1 is the
|
||||
right-most digit, 2 is the second-right-most digit, etc. Returns the
|
||||
original value for invalid input (if input or argument is not an integer,
|
||||
or if argument is less than 1). Otherwise, output is always an integer.
|
||||
|
||||
join
|
||||
````
|
||||
``join``
|
||||
Joins a list with a string, like Python's ``str.join(list)``
|
||||
|
||||
length
|
||||
``````
|
||||
``length``
|
||||
Returns the length of the value - useful for lists
|
||||
|
||||
length_is
|
||||
`````````
|
||||
``length_is``
|
||||
Returns a boolean of whether the value's length is the argument
|
||||
|
||||
linebreaks
|
||||
``````````
|
||||
``linebreaks``
|
||||
Converts newlines into <p> and <br />s
|
||||
|
||||
linebreaksbr
|
||||
````````````
|
||||
``linebreaksbr``
|
||||
Converts newlines into <br />s
|
||||
|
||||
linenumbers
|
||||
```````````
|
||||
``linenumbers``
|
||||
Displays text with line numbers
|
||||
|
||||
ljust
|
||||
`````
|
||||
``ljust``
|
||||
Left-aligns the value in a field of a given width
|
||||
|
||||
Argument: field size
|
||||
|
||||
lower
|
||||
`````
|
||||
``lower``
|
||||
Converts a string into all lowercase
|
||||
|
||||
make_list
|
||||
`````````
|
||||
``make_list``
|
||||
Returns the value turned into a list. For an integer, it's a list of
|
||||
digits. For a string, it's a list of characters.
|
||||
|
||||
phone2numeric
|
||||
`````````````
|
||||
``phone2numeric``
|
||||
Takes a phone number and converts it in to its numerical equivalent
|
||||
|
||||
pluralize
|
||||
`````````
|
||||
``pluralize``
|
||||
Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'
|
||||
|
||||
pprint
|
||||
``````
|
||||
``pprint``
|
||||
A wrapper around pprint.pprint -- for debugging, really
|
||||
|
||||
random
|
||||
``````
|
||||
``random``
|
||||
Returns a random item from the list
|
||||
|
||||
removetags
|
||||
```````````
|
||||
``removetags``
|
||||
Removes a space separated list of [X]HTML tags from the output
|
||||
|
||||
rjust
|
||||
`````
|
||||
``rjust``
|
||||
Right-aligns the value in a field of a given width
|
||||
|
||||
Argument: field size
|
||||
|
||||
slice
|
||||
`````
|
||||
``slice``
|
||||
Returns a slice of the list.
|
||||
|
||||
Uses the same syntax as Python's list slicing; see
|
||||
http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
|
||||
for an introduction.
|
||||
|
||||
slugify
|
||||
```````
|
||||
``slugify``
|
||||
Converts to lowercase, removes non-alpha chars and converts spaces to hyphens
|
||||
|
||||
stringformat
|
||||
````````````
|
||||
``stringformat``
|
||||
Formats the variable according to the argument, a string formatting specifier.
|
||||
This specifier uses Python string formating syntax, with the exception that
|
||||
the leading "%" is dropped.
|
||||
|
|
@ -717,30 +650,24 @@ the leading "%" is dropped.
|
|||
See http://docs.python.org/lib/typesseq-strings.html for documentation
|
||||
of Python string formatting
|
||||
|
||||
striptags
|
||||
`````````
|
||||
``striptags``
|
||||
Strips all [X]HTML tags
|
||||
|
||||
time
|
||||
````
|
||||
``time``
|
||||
Formats a time according to the given format (same as the now_ tag).
|
||||
|
||||
timesince
|
||||
`````````
|
||||
``timesince``
|
||||
Formats a date as the time since that date (i.e. "4 days, 6 hours")
|
||||
|
||||
title
|
||||
`````
|
||||
``title``
|
||||
Converts a string into titlecase
|
||||
|
||||
truncatewords
|
||||
`````````````
|
||||
``truncatewords``
|
||||
Truncates a string after a certain number of words
|
||||
|
||||
Argument: Number of words to truncate after
|
||||
|
||||
unordered_list
|
||||
``````````````
|
||||
``unordered_list``
|
||||
Recursively takes a self-nested list and returns an HTML unordered list --
|
||||
WITHOUT opening and closing <ul> tags.
|
||||
|
||||
|
|
@ -760,36 +687,29 @@ then ``{{ var|unordered_list }}`` would return::
|
|||
</ul>
|
||||
</li>
|
||||
|
||||
upper
|
||||
`````
|
||||
``upper``
|
||||
Converts a string into all uppercase
|
||||
|
||||
urlencode
|
||||
`````````
|
||||
``urlencode``
|
||||
Escapes a value for use in a URL
|
||||
|
||||
urlize
|
||||
``````
|
||||
``urlize``
|
||||
Converts URLs in plain text into clickable links
|
||||
|
||||
urlizetrunc
|
||||
```````````
|
||||
``urlizetrunc``
|
||||
Converts URLs into clickable links, truncating URLs to the given character limit
|
||||
|
||||
Argument: Length to truncate URLs to.
|
||||
|
||||
wordcount
|
||||
`````````
|
||||
``wordcount``
|
||||
Returns the number of words
|
||||
|
||||
wordwrap
|
||||
````````
|
||||
``wordwrap``
|
||||
Wraps words at specified line length
|
||||
|
||||
Argument: number of words to wrap the text at.
|
||||
|
||||
yesno
|
||||
`````
|
||||
``yesno``
|
||||
Given a string mapping values for true, false and (optionally) None,
|
||||
returns one of those strings according to the value:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue