1
0
mirror of https://github.com/django/django.git synced 2025-07-04 09:49:12 +00:00

magic-removal: Proofread docs/templates.txt

git-svn-id: http://code.djangoproject.com/svn/django/branches/magic-removal@2794 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2006-04-29 19:13:06 +00:00
parent 716cd0c451
commit 5917d90e30

View File

@ -13,9 +13,8 @@ or CheetahTemplate_, you should feel right at home with Django's templates.
Templates
=========
A template is simply a text file. All Django templates, by convention, have
".html" extensions, but they can generate any text-based format (HTML, XML,
CSV, etc.).
A template is simply a text file. It can generate any text-based format (HTML,
XML, CSV, etc.).
A template contains **variables**, which get replaced with values when the
template is evaluated, and **tags**, which control the logic of the template.
@ -23,7 +22,7 @@ template is evaluated, and **tags**, which control the logic of the template.
Below is a minimal template that illustrates a few basics. Each element will be
explained later in this document.::
{% extends "base_generic" %}
{% extends "base_generic.html" %}
{% block title %}{{ section.title }}{% endblock %}
@ -48,6 +47,8 @@ explained later in this document.::
JavaScript and CSV. You can use the template language for any text-based
format.
Oh, and one more thing: Making humans edit XML is masochistic!
Variables
=========
@ -74,26 +75,23 @@ If you use a variable that doesn't exist, the template system will insert
the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''``
(the empty string) by default.
If you use a variable that doesn't exist, it will be silently ignored. The
variable will be replaced by nothingness.
See `Using the built-in reference`_, below, for help on finding what variables
are available in a given template.
You can modify variables for display by using **filters**.
Filters
=======
You can modify variables for display by using **filters**.
Filters look like this: ``{{ name|lower }}``. This displays the value of the
``{{ name }}`` variable after being filtered through the ``lower`` filter,
which converts text to lowercase. Use a pipe (``|``) to apply a filter.
Filters can be "chained." The output of one filter applied to the next:
``{{ text|escape|linebreaks }}`` is a common idiom for escaping text contents
and then converting line breaks to ``<p>`` tags.
Filters can be "chained." The output of one filter is applied to the next.
``{{ text|escape|linebreaks }}`` is a common idiom for escaping text contents,
then converting line breaks to ``<p>`` tags.
Certain filters take arguments. A filter argument looks like this:
Some filters take arguments. A filter argument looks like this:
``{{ bio|truncatewords:"30" }}``. This will display the first 30 words of the
``bio`` variable. Filter arguments always are in double quotes.
@ -154,7 +152,7 @@ engine that a child template may override those portions of the template.
A child template might look like this::
{% extends "base" %}
{% extends "base.html" %}
{% block title %}My amazing blog{% endblock %}
@ -167,12 +165,12 @@ A child template might look like this::
The ``{% extends %}`` tag is the key here. It tells the template engine that
this template "extends" another template. When the template system evaluates
this template, first it locates the parent -- in this case, "base" (note the
lack of an ".html" extension in the ``{% extends %}`` tag).
this template, first it locates the parent -- in this case, "base.html".
At that point, the template engine will notice the three blocks in
``base.html`` and replace those blocks with the contents of the child template.
Depending on the value of ``blog_entries``, the output might look like::
At that point, the template engine will notice the three ``{% block %}`` tags
in ``base.html`` and replace those blocks with the contents of the child
template. Depending on the value of ``blog_entries``, the output might look
like::
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
@ -203,29 +201,36 @@ Note that since the child template didn't define the ``sidebar`` block, the
value from the parent template is used instead. Content within a ``{% block %}``
tag in a parent template is always used as a fallback.
Template inheritance isn't limited to a single level. Multi-level inheritance
is possible and, indeed, quite useful.
You can use as many levels of inheritance as needed. One common way of using
inheritance is the following three-level approach:
* Create a ``base.html`` template that holds the main look-and-feel of your
site.
* Create a ``base_SECTIONNAME.html`` template for each "section" of your
site. For example, ``base_news.html``, ``base_sports.html``. These
templates all extend ``base.html`` and include section-specific
styles/design.
* Create individual templates for each type of page, such as a news
article or blog entry. These templates extend the appropriate section
template.
This approach maximizes code reuse and makes it easy to add items to shared
content areas, such as section-wide navigation.
Here are some tips for working with inheritance:
* If you use ``{% extends %}`` in a template, it must be the first template
tag in that template.
tag in that template. Template inheritance won't work, otherwise.
* More ``{% block %}`` tags in your base templates are better. Remember,
child templates don't have to define all parent blocks, so you can fill
in reasonable defaults in a number of blocks, then only define the ones
you need later.
you need later. It's better to have more hooks than fewer hooks.
* If you find yourself duplicating content in a number of templates, it
probably means you should move that content to a ``{% block %}`` in a
parent template.
* The recommended template layout is to use three levels: a single base
template for the entire site, a set of mid-level templates for each
section of the site, and then the individual templates for each view.
This maximizes code reuse and makes it easier to add items to shared
content areas (such as section-wide navigation).
* If you need to get the content of the block from the parent template,
the ``{{ block.super }}`` variable will do the trick. This is useful
if you want to add to the contents of a parent block instead of
@ -241,15 +246,11 @@ wouldn't know which one of the blocks' content to use.
Using the built-in reference
============================
Because Django can be used to develop any sort of site, the tags, filters and
variables available are different depending on the application. To make it
easy to figure out what's available in a given site, the admin interface has a
complete reference of all the template goodies available to that site. To get
that reference, go to your Django admin interface and click the "Documentation"
link in the upper right of any page.
Django's admin interface includes a complete reference of all template tags and
filters available for a given site. To see it, go to your admin interface and
click the "Documentation" link in the upper right of the page.
The reference is integrated into the administration interface for your site(s)
and is divided into 4 sections: tags, filters, models, and views.
The reference is divided into 4 sections: tags, filters, models, and views.
The **tags** and **filters** sections describe all the built-in tags (in fact,
the tag and filter references below come directly from those pages) as well as
@ -260,13 +261,13 @@ entry here, and clicking on a URL will show you:
* The name of the view function that generates that view.
* A short description of what the view does.
* The **context**, or a list of variables available in the view.
* The **context**, or a list of variables available in the view's template.
* The name of the template or templates that are used for that view.
Each view documentation page also has a bookmarklet that you can use to jump
from any page to the documentation page for that view.
Because Django generally revolves around database objects, the **models**
Because Django-powered sites usually use database objects, the **models**
section of the documentation page describes each type of object in the system
along with all the fields available on that object.
@ -300,9 +301,9 @@ available to the current template -- not any parent or child templates along
the template-inheritance path.
For example, if a template ``foo.html`` has ``{% load comments %}``, a child
template (e.g., one that has ``{% extends foo %}`` will *not* have access to
the comments template tags and filters. The child template is responsible for
its own ``{% load comments %}``.
template (e.g., one that has ``{% extends "foo.html" %}``) will *not* have
access to the comments template tags and filters. The child template is
responsible for its own ``{% load comments %}``.
This is a feature for the sake of maintainability and sanity.
@ -362,10 +363,10 @@ extends
Signal that this template extends a parent template.
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.
This tag may be used in two ways: ``{% extends "base.html" %}`` (with quotes)
uses the literal value "base.html" 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.
See `Template inheritance`_ for more information.
@ -485,7 +486,7 @@ 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
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::
@ -763,7 +764,7 @@ 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 %}' />
<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
@ -844,8 +845,8 @@ Escapes a string's HTML. Specifically, it makes these replacements:
filesizeformat
~~~~~~~~~~~~~~
Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
bytes, etc).
Format the value like a 'human-readable' file size (i.e. ``'13 KB'``,
``'4.1 MB'``, ``'102 bytes'``, etc).
first
~~~~~
@ -893,12 +894,12 @@ Returns a boolean of whether the value's length is the argument.
linebreaks
~~~~~~~~~~
Converts newlines into <p> and <br />s.
Converts newlines into ``<p>`` and ``<br />``s.
linebreaksbr
~~~~~~~~~~~~
Converts newlines into <br />s.
Converts newlines into ``<br />``s.
linenumbers
~~~~~~~~~~~
@ -936,7 +937,11 @@ any string.
pluralize
~~~~~~~~~
Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'.
Returns ``'s'`` if the value is not 1.
Example::
You have {{ num_messages }} message{{ num_messages|pluralize }}.
pprint
~~~~~~