test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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 2005-07-15 00:42:28 +00:00
parent 5fc13947fc
commit f19dbab514
4 changed files with 859 additions and 1041 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/db-api.txt
View File

@ -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
View File

@ -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/

653
docs/model-api.txt
View File

@ -2,141 +2,117 @@
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.
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::
The name of the database table to use for the module::
db_table = "pizza_orders"
db_table = "pizza_orders"
If not given, this will use ``app_label + '_' + module_name``.
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::
Names of extra exception subclasses to include in the generated module.
These exceptions are available from instance methods and from module-level
methods::
exceptions = ("DisgustingToppingsException", "BurntCrust")
exceptions = ("DisgustingToppingsException", "BurntCrust")
``fields``
----------
A list of field objects; see `Field objects`_. For example::
A list of field objects; see `Field objects`_. For example::
fields = (
meta.CharField('customer_name', 'customer name', maxlength=15),
meta.BooleanField('use_extra_cheese', 'use extra cheese'),
meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES),
...
)
fields = (
meta.CharField('customer_name', 'customer name', maxlength=15),
meta.BooleanField('use_extra_cheese', 'use extra cheese'),
meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES),
...
)
``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::
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::
get_latest_by = "order_date"
get_latest_by = "order_date"
``module_constants``
--------------------
A dict of name/values to use as extra module-level constants::
A dict of name/values to use as extra module-level constants::
module_constants = {
'MEAT_TYPE_PEPPERONI' : 1,
'MEAT_TYPE_SAUSAGE' : 2,
}
module_constants = {
'MEAT_TYPE_PEPPERONI' : 1,
'MEAT_TYPE_SAUSAGE' : 2,
}
``module_name``
---------------
The name of the module::
The name of the module::
module_name = "pizza_orders"
module_name = "pizza_orders"
If not given this will use a lowercased version of the class name.
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
a ``Pizza`` object, you might use::
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
a ``Pizza`` object, you might use::
order_with_respect_to = 'pizza_id'
order_with_respect_to = 'pizza_id'
to allow the toppings to be ordered with respect to the associated pizza.
to allow the toppings to be ordered with respect to the associated pizza.
``ordering``
------------
The default ordering for tho object::
The default ordering for tho object::
ordering = (('order_date', 'DESC'),)
ordering = (('order_date', 'DESC'),)
This is a tuple of 2-tuples; each 2-tuple is ``(field_name, ordering_type)``
where ordering_type is either ``"ASC"`` or ``"DESC"``. You may also use the
magic ``(None, "RANDOM")`` ordering tuple for random ordering.
This is a tuple of 2-tuples; each 2-tuple is ``(field_name, ordering_type)``
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::
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::
permissions = (("may_delivier_pizzas", "Can deliver pizzas"),)
permissions = (("may_delivier_pizzas", "Can deliver pizzas"),)
This is a list of 2-tuples of
``(permission_code, human_readable_permission_name)``.
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::
Sets of field names that, taken together, must be unique::
unique_together = (("driver_id", "restaurant_id"),)
unique_together = (("driver_id", "restaurant_id"),)
This is a list of lists of fields that must be unique when considered
together.
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::
A human-readable name for the object, singular::
verbose_name = "pizza"
verbose_name = "pizza"
If not given, this will use a munged version of the class name:
``CamelCase`` becomes ``camel case``.
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::
The plural name for the object::
verbose_name_plural = "stories"
verbose_name_plural = "stories"
If not given, ``verbose_name + "s"`` will automatically be used.
If not given, ``verbose_name + "s"`` will automatically be used.
Field objects
=============
@ -251,254 +227,89 @@ 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::
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::
meta.AutoField('id', 'ID', primary_key=True)
meta.AutoField('id', 'ID', primary_key=True)
``BooleanField``
````````````````
A true/false field.
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``.
A text field. These are displayed in the admin as single-line text inputs, so
for large amounts of text use a ``TextField``.
``CharField``s have an extra required argument: ``maxlength``; the maximum
length (in characters) of the field.
``CharField``s have an extra required argument: ``maxlength``; the maximum
length (in characters) of the field.
``CommaSeparatedIntegerField``
``````````````````````````````
A field of integers separated by commas.
A field of integers separated by commas.
``DateField``
`````````````
A, um, date field. Has a few extra optional options:
A, um, date field. Has a few extra optional options:
====================== ===================================================
Option Description
====================== ===================================================
``auto_now`` Automatically set the field to now every time the
object is saved. Useful for "last-modified"
timestamps.
====================== ===================================================
Option Description
====================== ===================================================
``auto_now`` Automatically set the field to now every time the
object is saved. Useful for "last-modified"
timestamps.
``auto_now_add`` Automatically set the field to now when the object
is first created. Useful for creation timestamps.
====================== ===================================================
``auto_now_add`` Automatically set the field to now when the object
is first created. Useful for creation timestamps.
====================== ===================================================
``DateTimeField``
`````````````````
A date and time field. Takes the same extra options as ``DateField``.
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.
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
files don't fill up the given directory).
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
files don't fill up the given directory).
.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
``FloatField``
``````````````
A floating-point number. Has two additional required options:
A floating-point number. Has two additional required options:
====================== ===================================================
Option Description
====================== ===================================================
``max_digits`` The maximum number of digits allowed in the number.
====================== ===================================================
Option Description
====================== ===================================================
``max_digits`` The maximum number of digits allowed in the number.
``decimal_places`` The number of decimal places to store with the
number
====================== ===================================================
``decimal_places`` The number of decimal places to store with the
number
====================== ===================================================
For example, to store numbers up to 999 with a resolution of 2 decimal places,
you'd use::
For example, to store numbers up to 999 with a resolution of 2 decimal places,
you'd use::
meta.FloatField(..., max_digits=5, decimal_places=2)
meta.FloatField(..., max_digits=5, decimal_places=2)
And to store numbers up to one million with a resolution of 10 decimal places::
And to store numbers up to one million with a resolution of 10 decimal places::
meta.FloatField(..., max_digits=19, decimal_places=10)
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)::
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)
meta.ForeignKey(Pizza)
``ForeignKey`` fields take a large number of options for defining how the
relationship should work:
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:
======================= ==================================================
====================== ===================================================
Option Description
======================= ==================================================
====================== ===================================================
``edit_inline`` If ``True``, this related object is edited
"inline" on the related object's page. This means
that the object will not have its own admin
@ -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,125 +489,107 @@ 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::
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'
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
displayed in that fieldset. This dictionary has the following keys:
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
displayed in that fieldset. This dictionary has the following keys:
``fields``
A tuple of field names to display in this fieldset. To display
multiple fields on the same line, wrap those fields in their
own tuple.
``fields``
A tuple of field names to display in this fieldset. To display
multiple fields on the same line, wrap those fields in their
own tuple.
This key is required in the dict.
This key is required in the dict.
``classes``
Extra CSS classes to apply to the fieldset. This is a simple
string; you can apply multiple classes by separating them with
spaces.
``classes``
Extra CSS classes to apply to the fieldset. This is a simple
string; you can apply multiple classes by separating them with
spaces.
Two useful classes defined by the default stylesheet are ``collapse``
and ``wide``. Fieldsets with the ``collapse`` style will be
initially collapsed in the admin and replaced with a small "click
to expand" link. Fieldsets with the ``wide`` style will be given
extra horizontal space.
Two useful classes defined by the default stylesheet are ``collapse``
and ``wide``. Fieldsets with the ``collapse`` style will be
initially collapsed in the admin and replaced with a small "click
to expand" link. Fieldsets with the ``wide`` style will be given
extra horizontal space.
For example (taken from the ``core.flatfiles`` model)::
For example (taken from the ``core.flatfiles`` model)::
fields = (
(None, {
'fields': ('url', 'title', 'content', 'sites')
}),
('Advanced options', {
'classes': 'collapse',
'fields' : ('enable_comments', 'registration_required', 'template_name')
}),
),
fields = (
(None, {
'fields': ('url', 'title', 'content', 'sites')
}),
('Advanced options', {
'classes': 'collapse',
'fields' : ('enable_comments', 'registration_required', 'template_name')
}),
),
results in an admin that looks like:
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.
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.
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
contents of the given fields:
There are a few special cases that do other things besides displaying the
contents of the given fields:
* If the field given has a relationship, that relationship is
followed and the ``repr()`` of the related object is displayed.
* If the field given has a relationship, that relationship is
followed and the ``repr()`` of the related object is displayed.
* If the field is a ``BooleanField``, a "on" or "off" icon will
be displayed instead of ``True`` or ``False``.
* If the field is a ``BooleanField``, a "on" or "off" icon will
be displayed instead of ``True`` or ``False``.
* If the field name given does not exist, a function of the model
will be searched for and called if present. This function
should have a ``short_description`` attribute that will be
used as the header for the field.
* If the field name given does not exist, a function of the model
will be searched for and called if present. This function
should have a ``short_description`` attribute that will be
used as the header for the field.
See the exmaple below.
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.
List of fields to filter by. Each field should either be a ``BooleanField``
or else a field with a ``ManyToOne`` relation.
An example of how ``list_display`` and ``list_filter`` work (taken from
the ``auth.user`` model)::
An example of how ``list_display`` and ``list_filter`` work (taken from
the ``auth.user`` model)::
list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff'),
list_filter = ('is_staff', 'is_superuser'),
list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff'),
list_filter = ('is_staff', 'is_superuser'),
results in a admin that looks like:
results in a admin that looks like:
.. image:: http://media.djangoproject.com/img/doc/users_changelist.png
.. image:: images/users_changelist.png
(This example also has ``search_fields`` defined; see below).
(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.
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.
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.
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.
A list of fields to provide a text search for. These fields should,
obviously, be some kind of text field.

808
docs/templates.txt
View File

@ -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,550 +256,469 @@ tags/filters.
Built-in tag reference
----------------------
block
`````
``block``
Define a block that can be overridden by child templates. See `Template
inheritance`_ for more information.
Define a block that can be overridden by child templates. See `Template
inheritance`_ for more information.
``comment``
Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
comment
```````
``cycle``
Cycle among the given strings each time this tag is encountered.
Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
Within a loop, cycles among the given strings each time through
the loop::
cycle
`````
{% for o in some_list %}
<tr class="{% cycle row1,row2 %}">
...
</tr>
{% endfor %}
Cycle among the given strings each time this tag is encountered.
Outside of a loop, give the values a unique name the first time you call it,
then use that name each successive time through::
Within a loop, cycles among the given strings each time through
the loop::
<tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
{% for o in some_list %}
<tr class="{% cycle row1,row2 %}">
...
</tr>
{% endfor %}
You can use any number of values, separated by commas. Make sure not to put
spaces between the values -- only commas.
Outside of a loop, give the values a unique name the first time you call it,
then use that name each successive time through::
``debug``
Output a whole load of debugging information, including the current context and
imported modules.
<tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
``extends``
Signal that this template extends a parent template.
You can use any number of values, separated by commas. Make sure not to put
spaces between the values -- only commas.
This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
the literal value "base" as the name of the parent template to extend, or ``{%
extends variable %}`` uses the value of ``variable`` as the name of the parent
template to extend.
debug
`````
See `Template inheritance`_ for more information.
Output a whole load of debugging information, including the current context and
imported modules.
``filter``
Filter the contents of the blog through variable filters.
extends
```````
Filters can also be piped through each other, and they can have arguments --
just like in variable syntax.
Signal that this template extends a parent template.
Sample usage::
This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
the literal value "base" as the name of the parent template to extend, or ``{%
extends variable %}`` uses the value of ``variable`` as the name of the parent
template to extend.
{% filter escape|lower %}
This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}
See `Template inheritance`_ for more information.
``firstof``
Outputs the first variable passed that is not False. Outputs nothing if all the
passed variables are False.
filter
``````
Sample usage::
Filter the contents of the blog through variable filters.
{% firstof var1 var2 var3 %}
Filters can also be piped through each other, and they can have arguments --
just like in variable syntax.
This is equivalent to::
Sample usage::
{% if var1 %}
{{ var1 }}
{% else %}{% if var2 %}
{{ var2 }}
{% else %}{% if var3 %}
{{ var3 }}
{% endif %}{% endif %}{% endif %}
{% filter escape|lower %}
This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}
but obviously much cleaner!
firstof
```````
``for``
Loop over each item in an array. For example, to display a list of athletes
given ``athlete_list``::
Outputs the first variable passed that is not False. Outputs nothing if all the
passed variables are False.
Sample usage::
{% firstof var1 var2 var3 %}
This is equivalent to::
{% if var1 %}
{{ var1 }}
{% else %}{% if var2 %}
{{ var2 }}
{% else %}{% if var3 %}
{{ var3 }}
{% endif %}{% endif %}{% endif %}
but obviously much cleaner!
for
```
Loop over each item in an array. For example, to display a list of athletes
given ``athlete_list``::
<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
</ul>
You can also loop over a list in reverse by using ``{% for obj in list reversed %}``.
The for loop sets a number of variables available within the loop:
========================== ================================================
Variable Description
========================== ================================================
``forloop.counter`` The current iteration of the loop (1-indexed)
``forloop.counter0`` The current iteration of the loop (0-indexed)
``forloop.first`` True if this is the first time through the loop
``forloop.last`` True if this is the last time through the loop
``forloop.parentloop`` For nested loops, this is the loop "above" the
current one
========================== ================================================
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::
{% if athlete_list %}
Number of athletes: {{ athlete_list|count }}
{% else %}
No athletes.
{% endif %}
In the above, if ``athlete_list`` is not empty, the number of athletes will be
displayed by the ``{{ athlete_list|count }}`` variable.
As you can see, the ``if`` tag can take an option ``{% else %}`` clause that
will be displayed if the test fails.
``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate
a given variable::
{% if not athlete_list %}
There are no athletes.
{% endif %}
{% if athlete_list or coach_list %}
There are some athletes or some coaches.
{% endif %}
{% if not athlete_list or coach_list %}
There are no athletes or there are some coaches (OK, so
writing English translations of boolean logic sounds
stupid; it's not my fault).
{% endif %}
For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if``
tags instead::
{% if athlete_list %}
{% if coach_list %}
Number of athletes: {{ athlete_list|count }}.
Number of coaches: {{ coach_list|count }}.
{% endif %}
{% endif %}
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
contents against its previous state and only displays its content if the value
has changed::
<h1>Archive for {{ year }}</h1>
{% for date in days %}
{% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
<a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
{% endfor %}
ifnotequal
``````````
Output the contents of the block if the two arguments do not equal each other.
Example::
{% ifnotequal user.id_ comment.user_id %}
...
{% endifnotequal %}
load
````
Load a custom template tag set.
See `Custom tag and filter libraries`_ for more information.
now
```
Display the date, formatted according to the given string.
Uses the same format as PHP's ``date()`` function; see http://php.net/date
for all the possible values.
Sample usage::
It is {% now "jS F Y H:i" %}
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``
is a list of ``Person`` objects that have ``first_name``, ``last_name``, and
``gender`` attributes, and you'd like to display a list that looks like:
* Male:
* George Bush
* Bill Clinton
* Female:
* Margaret Thatcher
* Colendeeza Rice
* Unknown:
* Janet Reno
The following snippet of template code would accomplish this dubious task::
{% regroup people by gender as grouped %}
<ul>
{% for group in grouped %}
<li>{{ group.grouper }}
<ul>
{% for item in group.list %}
<li>{{ item }}</li>
{% endfor %}
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
</ul>
{% endfor %}
</ul>
As you can see, ``{% regroup %}`` populates a variable with a list of objects
with ``grouper`` and ``list`` attributes. ``grouper`` contains the item that
was grouped by; ``list`` contains the list of objects that share that
``grouper``. In this case, ``grouper`` would be ``Male``, ``Female`` and
``Unknown``, and ``list`` is the list of people with those genders.
You can also loop over a list in reverse by using ``{% for obj in list reversed %}``.
Note that ``{% regroup %}`` does not work when the list to be grouped is not
sorted by the key you are grouping by! This means that if your list of people
was not sorted by gender, you'd need to make sure it is sorted before using it,
i.e.::
The for loop sets a number of variables available within the loop:
{% regroup people|dictsort:"gender" by gender as grouped %}
========================== ================================================
Variable Description
========================== ================================================
``forloop.counter`` The current iteration of the loop (1-indexed)
``forloop.counter0`` The current iteration of the loop (0-indexed)
``forloop.first`` True if this is the first time through the loop
``forloop.last`` True if this is the last time through the loop
``forloop.parentloop`` For nested loops, this is the loop "above" the
current one
========================== ================================================
ssi
```
``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::
Output the contents of a given file into the page.
{% if athlete_list %}
Number of athletes: {{ athlete_list|count }}
{% else %}
No athletes.
{% endif %}
Like a simple "include" tag, the ``ssi`` tag includes the contents
of another file -- which must be specified using an absolute page --
in the current page::
In the above, if ``athlete_list`` is not empty, the number of athletes will be
displayed by the ``{{ athlete_list|count }}`` variable.
{% ssi /home/html/ljworld.com/includes/right_generic.html %}
As you can see, the ``if`` tag can take an option ``{% else %}`` clause that
will be displayed if the test fails.
If the optional "parsed" parameter is given, the contents of the included
file are evaluated as template code, with the current context::
``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate
a given variable::
{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
{% if not athlete_list %}
There are no athletes.
{% endif %}
templatetag
```````````
{% if athlete_list or coach_list %}
There are some athletes or some coaches.
{% endif %}
Output one of the bits used to compose template tags.
{% if not athlete_list or coach_list %}
There are no athletes or there are some coaches (OK, so
writing English translations of boolean logic sounds
stupid; it's not my fault).
{% endif %}
Since the template system has no concept of "escaping", to display one of the
bits used in template tags, you must use the ``{% templatetag %}`` tag.
For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if``
tags instead::
The argument tells which template bit to output:
{% if athlete_list %}
{% if coach_list %}
Number of athletes: {{ athlete_list|count }}.
Number of coaches: {{ coach_list|count }}.
{% endif %}
{% endif %}
================== =======
Argument Outputs
================== =======
``openblock`` ``{%``
``closeblock`` ``%}``
``openvariable`` ``{{``
``closevariable`` ``}}``
================== =======
``ifchanged``
Check if a value has changed from the last iteration of a loop.
widthratio
``````````
The 'ifchanged' block tag is used within a loop. It checks its own rendered
contents against its previous state and only displays its content if the value
has changed::
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.
<h1>Archive for {{ year }}</h1>
For example::
{% for date in days %}
{% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
<a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
{% endfor %}
<img src='bar.gif' height='10' width='{% widthratio this_value max_value 100 %}' />
``ifnotequal``
Output the contents of the block if the two arguments do not equal each other.
Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the
above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
which is rounded up to 88).
Example::
{% ifnotequal user.id_ comment.user_id %}
...
{% endifnotequal %}
``load``
Load a custom template tag set.
See `Custom tag and filter libraries`_ for more information.
``now``
Display the date, formatted according to the given string.
Uses the same format as PHP's ``date()`` function; see http://php.net/date
for all the possible values.
Sample usage::
It is {% now "jS F Y H:i" %}
``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``
is a list of ``Person`` objects that have ``first_name``, ``last_name``, and
``gender`` attributes, and you'd like to display a list that looks like:
* Male:
* George Bush
* Bill Clinton
* Female:
* Margaret Thatcher
* Colendeeza Rice
* Unknown:
* Janet Reno
The following snippet of template code would accomplish this dubious task::
{% regroup people by gender as grouped %}
<ul>
{% for group in grouped %}
<li>{{ group.grouper }}
<ul>
{% for item in group.list %}
<li>{{ item }}</li>
{% endfor %}
</ul>
{% endfor %}
</ul>
As you can see, ``{% regroup %}`` populates a variable with a list of objects
with ``grouper`` and ``list`` attributes. ``grouper`` contains the item that
was grouped by; ``list`` contains the list of objects that share that
``grouper``. In this case, ``grouper`` would be ``Male``, ``Female`` and
``Unknown``, and ``list`` is the list of people with those genders.
Note that ``{% regroup %}`` does not work when the list to be grouped is not
sorted by the key you are grouping by! This means that if your list of people
was not sorted by gender, you'd need to make sure it is sorted before using it,
i.e.::
{% regroup people|dictsort:"gender" by gender as grouped %}
``ssi``
Output the contents of a given file into the page.
Like a simple "include" tag, the ``ssi`` tag includes the contents
of another file -- which must be specified using an absolute page --
in the current page::
{% ssi /home/html/ljworld.com/includes/right_generic.html %}
If the optional "parsed" parameter is given, the contents of the included
file are evaluated as template code, with the current context::
{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
``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
bits used in template tags, you must use the ``{% templatetag %}`` tag.
The argument tells which template bit to output:
================== =======
Argument Outputs
================== =======
``openblock`` ``{%``
``closeblock`` ``%}``
``openvariable`` ``{{``
``closevariable`` ``}}``
================== =======
``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.
For example::
<img src='bar.gif' height='10' width='{% widthratio this_value max_value 100 %}' />
Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the
above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
which is rounded up to 88).
Built-in filter reference
-------------------------
add
```
Adds the arg to the value
``add``
Adds the arg to the value
addslashes
``````````
Adds slashes - useful for passing strings to JavaScript, for example.
``addslashes``
Adds slashes - useful for passing strings to JavaScript, for example.
capfirst
````````
Capitalizes the first character of the value
``capfirst``
Capitalizes the first character of the value
center
``````
Centers the value in a field of a given width
``center``
Centers the value in a field of a given width
cut
```
Removes all values of arg from the given string
``cut``
Removes all values of arg from the given string
date
````
Formats a date according to the given format (same as the now_ tag)
``date``
Formats a date according to the given format (same as the now_ tag)
default
```````
If value is unavailable, use given default
``default``
If value is unavailable, use given default
dictsort
````````
Takes a list of dicts, returns that list sorted by the property given in the
argument.
``dictsort``
Takes a list of dicts, returns that list sorted by the property given in the
argument.
dictsortreversed
````````````````
Takes a list of dicts, returns that list sorted in reverse order by the property
given in the argument.
``dictsortreversed``
Takes a list of dicts, returns that list sorted in reverse order by the property
given in the argument.
divisibleby
```````````
Returns true if the value is divisible by the argument
``divisibleby``
Returns true if the value is divisible by the argument
escape
``````
Escapes a string's HTML
``escape``
Escapes a string's HTML
filesizeformat
``````````````
Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
bytes, etc).
``filesizeformat``
Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
bytes, etc).
first
`````
Returns the first item in a list
``first``
Returns the first item in a list
fix_ampersands
``````````````
Replaces ampersands with ``&amp;`` entities
``fix_ampersands``
Replaces ampersands with ``&amp;`` entities
floatformat
```````````
Displays a floating point number as 34.2 (with one decimal places) - but
only if there's a point to be displayed
``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
`````````
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.
``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
````
Joins a list with a string, like Python's ``str.join(list)``
``join``
Joins a list with a string, like Python's ``str.join(list)``
length
``````
Returns the length of the value - useful for lists
``length``
Returns the length of the value - useful for lists
length_is
`````````
Returns a boolean of whether the value's length is the argument
``length_is``
Returns a boolean of whether the value's length is the argument
linebreaks
``````````
Converts newlines into <p> and <br />s
``linebreaks``
Converts newlines into <p> and <br />s
linebreaksbr
````````````
Converts newlines into <br />s
``linebreaksbr``
Converts newlines into <br />s
linenumbers
```````````
Displays text with line numbers
``linenumbers``
Displays text with line numbers
ljust
`````
Left-aligns the value in a field of a given width
``ljust``
Left-aligns the value in a field of a given width
Argument: field size
Argument: field size
lower
`````
Converts a string into all lowercase
``lower``
Converts a string into all lowercase
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.
``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
`````````````
Takes a phone number and converts it in to its numerical equivalent
``phone2numeric``
Takes a phone number and converts it in to its numerical equivalent
pluralize
`````````
Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'
``pluralize``
Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'
pprint
``````
A wrapper around pprint.pprint -- for debugging, really
``pprint``
A wrapper around pprint.pprint -- for debugging, really
random
``````
Returns a random item from the list
``random``
Returns a random item from the list
removetags
```````````
Removes a space separated list of [X]HTML tags from the output
``removetags``
Removes a space separated list of [X]HTML tags from the output
rjust
`````
Right-aligns the value in a field of a given width
``rjust``
Right-aligns the value in a field of a given width
Argument: field size
Argument: field size
slice
`````
Returns a slice of the list.
``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.
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
```````
Converts to lowercase, removes non-alpha chars and converts spaces to hyphens
``slugify``
Converts to lowercase, removes non-alpha chars and converts spaces to hyphens
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.
``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.
See http://docs.python.org/lib/typesseq-strings.html for documentation
of Python string formatting
See http://docs.python.org/lib/typesseq-strings.html for documentation
of Python string formatting
striptags
`````````
Strips all [X]HTML tags
``striptags``
Strips all [X]HTML tags
time
````
Formats a time according to the given format (same as the now_ tag).
``time``
Formats a time according to the given format (same as the now_ tag).
timesince
`````````
Formats a date as the time since that date (i.e. "4 days, 6 hours")
``timesince``
Formats a date as the time since that date (i.e. "4 days, 6 hours")
title
`````
Converts a string into titlecase
``title``
Converts a string into titlecase
truncatewords
`````````````
Truncates a string after a certain number of words
``truncatewords``
Truncates a string after a certain number of words
Argument: Number of words to truncate after
Argument: Number of words to truncate after
unordered_list
``````````````
Recursively takes a self-nested list and returns an HTML unordered list --
WITHOUT opening and closing <ul> tags.
``unordered_list``
Recursively takes a self-nested list and returns an HTML unordered list --
WITHOUT opening and closing <ul> tags.
The list is assumed to be in the proper format. For example, if ``var`` contains
``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``,
then ``{{ var|unordered_list }}`` would return::
The list is assumed to be in the proper format. For example, if ``var`` contains
``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``,
then ``{{ var|unordered_list }}`` would return::
<li>States
<ul>
<li>Kansas
<ul>
<li>Lawrence</li>
<li>Topeka</li>
</ul>
</li>
<li>Illinois</li>
</ul>
</li>
<li>States
<ul>
<li>Kansas
<ul>
<li>Lawrence</li>
<li>Topeka</li>
</ul>
</li>
<li>Illinois</li>
</ul>
</li>
upper
`````
Converts a string into all uppercase
``upper``
Converts a string into all uppercase
urlencode
`````````
Escapes a value for use in a URL
``urlencode``
Escapes a value for use in a URL
urlize
``````
Converts URLs in plain text into clickable links
``urlize``
Converts URLs in plain text into clickable links
urlizetrunc
```````````
Converts URLs into clickable links, truncating URLs to the given character limit
``urlizetrunc``
Converts URLs into clickable links, truncating URLs to the given character limit
Argument: Length to truncate URLs to.
Argument: Length to truncate URLs to.
wordcount
`````````
Returns the number of words
``wordcount``
Returns the number of words
wordwrap
````````
Wraps words at specified line length
``wordwrap``
Wraps words at specified line length
Argument: number of words to wrap the text at.
Argument: number of words to wrap the text at.
yesno
`````
Given a string mapping values for true, false and (optionally) None,
returns one of those strings according to the value:
``yesno``
Given a string mapping values for true, false and (optionally) None,
returns one of those strings according to the value:
========== ====================== ==================================
Value Argument Outputs
========== ====================== ==================================
``True`` ``"yeah,no,maybe"`` ``yeah``
``False`` ``"yeah,no,maybe"`` ``no``
``None`` ``"yeah,no,maybe"`` ``maybe``
``None`` ``"yeah,no"`` ``"no"`` (converts None to False
if no mapping for None is given.
========== ====================== ==================================
========== ====================== ==================================
Value Argument Outputs
========== ====================== ==================================
``True`` ``"yeah,no,maybe"`` ``yeah``
``False`` ``"yeah,no,maybe"`` ``no``
``None`` ``"yeah,no,maybe"`` ``maybe``
``None`` ``"yeah,no"`` ``"no"`` (converts None to False
if no mapping for None is given.
========== ====================== ==================================