Django

Code

Changeset 2794

Show
Ignore:
Timestamp:
04/29/06 14:13:06 (2 years ago)
Author:
adrian
Message:

magic-removal: Proofread docs/templates.txt

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/branches/magic-removal/docs/templates.txt

    r2744 r2794  
    1414========= 
    1515 
    16 A template is simply a text file. All Django templates, by convention, have 
    17 ".html" extensions, but they can generate any text-based format (HTML, XML, 
    18 CSV, etc.). 
     16A template is simply a text file. It can generate any text-based format (HTML, 
     17XML, CSV, etc.). 
    1918 
    2019A template contains **variables**, which get replaced with values when the 
    …… 
    2423explained later in this document.:: 
    2524 
    26     {% extends "base_generic" %} 
     25    {% extends "base_generic.html" %} 
    2726 
    2827    {% block title %}{{ section.title }}{% endblock %} 
    …… 
    4948    format. 
    5049 
     50    Oh, and one more thing: Making humans edit XML is masochistic! 
     51 
    5152Variables 
    5253========= 
    …… 
    7576(the empty string) by default. 
    7677 
    77 If you use a variable that doesn't exist, it will be silently ignored. The 
    78 variable will be replaced by nothingness. 
    79  
    8078See `Using the built-in reference`_, below, for help on finding what variables 
    8179are available in a given template. 
    8280 
    83 You can modify variables for display by using **filters**. 
    84  
    8581Filters 
    8682======= 
     83 
     84You can modify variables for display by using **filters**. 
    8785 
    8886Filters look like this: ``{{ name|lower }}``. This displays the value of the 
    …… 
    9088which converts text to lowercase. Use a pipe (``|``) to apply a filter. 
    9189 
    92 Filters can be "chained." The output of one filter applied to the next: 
    93 ``{{ text|escape|linebreaks }}`` is a common idiom for escaping text contents 
    94 and then converting line breaks to ``<p>`` tags. 
    95  
    96 Certain filters take arguments. A filter argument looks like this: 
     90Filters can be "chained." The output of one filter is applied to the next. 
     91``{{ text|escape|linebreaks }}`` is a common idiom for escaping text contents, 
     92then converting line breaks to ``<p>`` tags. 
     93 
     94Some filters take arguments. A filter argument looks like this: 
    9795``{{ bio|truncatewords:"30" }}``. This will display the first 30 words of the 
    9896``bio`` variable. Filter arguments always are in double quotes. 
    …… 
    155153A child template might look like this:: 
    156154 
    157     {% extends "base" %} 
     155    {% extends "base.html" %} 
    158156 
    159157    {% block title %}My amazing blog{% endblock %} 
    …… 
    168166The ``{% extends %}`` tag is the key here. It tells the template engine that 
    169167this template "extends" another template. When the template system evaluates 
    170 this template, first it locates the parent -- in this case, "base" (note the 
    171 lack of an ".html" extension in the ``{% extends %}`` tag). 
    172  
    173 At that point, the template engine will notice the three blocks in 
    174 ``base.html`` and replace those blocks with the contents of the child template. 
    175 Depending on the value of ``blog_entries``, the output might look like:: 
     168this template, first it locates the parent -- in this case, "base.html". 
     169 
     170At that point, the template engine will notice the three ``{% block %}`` tags 
     171in ``base.html`` and replace those blocks with the contents of the child 
     172template. Depending on the value of ``blog_entries``, the output might look 
     173like:: 
    176174 
    177175    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    …… 
    204202tag in a parent template is always used as a fallback. 
    205203 
    206 Template inheritance isn't limited to a single level. Multi-level inheritance 
    207 is possible and, indeed, quite useful. 
     204You can use as many levels of inheritance as needed. One common way of using 
     205inheritance is the following three-level approach: 
     206 
     207    * Create a ``base.html`` template that holds the main look-and-feel of your 
     208      site. 
     209    * Create a ``base_SECTIONNAME.html`` template for each "section" of your 
     210      site. For example, ``base_news.html``, ``base_sports.html``. These 
     211      templates all extend ``base.html`` and include section-specific 
     212      styles/design. 
     213    * Create individual templates for each type of page, such as a news 
     214      article or blog entry. These templates extend the appropriate section 
     215      template. 
     216 
     217This approach maximizes code reuse and makes it easy to add items to shared 
     218content areas, such as section-wide navigation. 
    208219 
    209220Here are some tips for working with inheritance: 
    210221 
    211222    * If you use ``{% extends %}`` in a template, it must be the first template 
    212       tag in that template. 
     223      tag in that template. Template inheritance won't work, otherwise. 
    213224 
    214225    * More ``{% block %}`` tags in your base templates are better. Remember, 
    215226      child templates don't have to define all parent blocks, so you can fill 
    216227      in reasonable defaults in a number of blocks, then only define the ones 
    217       you need later. 
     228      you need later. It's better to have more hooks than fewer hooks. 
    218229 
    219230    * If you find yourself duplicating content in a number of templates, it 
    220231      probably means you should move that content to a ``{% block %}`` in a 
    221232      parent template. 
    222  
    223     * The recommended template layout is to use three levels: a single base 
    224       template for the entire site, a set of mid-level templates for each 
    225       section of the site, and then the individual templates for each view. 
    226       This maximizes code reuse and makes it easier to add items to shared 
    227       content areas (such as section-wide navigation). 
    228233 
    229234    * If you need to get the content of the block from the parent template, 
    …… 
    242247============================ 
    243248 
    244 Because Django can be used to develop any sort of site, the tags, filters and 
    245 variables available are different depending on the application. To make it 
    246 easy to figure out what's available in a given site, the admin interface has a 
    247 complete reference of all the template goodies available to that site. To get 
    248 that reference, go to your Django admin interface and click the "Documentation" 
    249 link in the upper right of any page. 
    250  
    251 The reference is integrated into the administration interface for your site(s) 
    252 and is divided into 4 sections: tags, filters, models, and views. 
     249Django's admin interface includes a complete reference of all template tags and 
     250filters available for a given site. To see it, go to your admin interface and 
     251click the "Documentation" link in the upper right of the page. 
     252 
     253The reference is divided into 4 sections: tags, filters, models, and views. 
    253254 
    254255The **tags** and **filters** sections describe all the built-in tags (in fact, 
    …… 
    261262    * The name of the view function that generates that view. 
    262263    * A short description of what the view does. 
    263     * The **context**, or a list of variables available in the view. 
     264    * The **context**, or a list of variables available in the view's template. 
    264265    * The name of the template or templates that are used for that view. 
    265266 
    …… 
    267268from any page to the documentation page for that view. 
    268269 
    269 Because Django generally revolves around database objects, the **models** 
     270Because Django-powered sites usually use database objects, the **models** 
    270271section of the documentation page describes each type of object in the system 
    271272along with all the fields available on that object. 
    …… 
    301302 
    302303For example, if a template ``foo.html`` has ``{% load comments %}``, a child 
    303 template (e.g., one that has ``{% extends foo %}`` will *not* have access to 
    304 the comments template tags and filters. The child template is responsible for 
    305 its own ``{% load comments %}``. 
     304template (e.g., one that has ``{% extends "foo.html" %}``) will *not* have 
     305access to the comments template tags and filters. The child template is 
     306responsible for its own ``{% load comments %}``. 
    306307 
    307308This is a feature for the sake of maintainability and sanity. 
    …… 
    363364Signal that this template extends a parent template. 
    364365 
    365 This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses 
    366 the literal value "base" as the name of the parent template to extend, or ``{% 
    367 extends variable %}`` uses the value of ``variable`` as the name of the parent 
    368 template to extend. 
     366This tag may be used in two ways: ``{% extends "base.html" %}`` (with quotes) 
     367uses the literal value "base.html" as the name of the parent template to 
     368extend, or ``{% extends variable %}`` uses the value of ``variable`` as the 
     369name of the parent template to extend. 
    369370 
    370371See `Template inheritance`_ for more information. 
    …… 
    486487Check if a value has changed from the last iteration of a loop. 
    487488 
    488 The 'ifchanged' block tag is used within a loop. It checks its own rendered 
     489The ``ifchanged`` block tag is used within a loop. It checks its own rendered 
    489490contents against its previous state and only displays its content if the value 
    490491has changed:: 
    …… 
    764765For example:: 
    765766 
    766     <img src='bar.gif' height='10' width='{% widthratio this_value max_value 100 %}' /> 
     767    <img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" /> 
    767768 
    768769Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the 
    …… 
    845846~~~~~~~~~~~~~~ 
    846847 
    847 Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102 
    848 bytes, etc). 
     848Format the value like a 'human-readable' file size (i.e. ``'13 KB'``, 
     849``'4.1 MB'``, ``'102 bytes'``, etc). 
    849850 
    850851first 
    …… 
    894895~~~~~~~~~~ 
    895896 
    896 Converts newlines into <p> and <br />s. 
     897Converts newlines into ``<p>`` and ``<br />``s. 
    897898 
    898899linebreaksbr 
    899900~~~~~~~~~~~~ 
    900901 
    901 Converts newlines into <br />s. 
     902Converts newlines into ``<br />``s. 
    902903 
    903904linenumbers 
    …… 
    937938~~~~~~~~~ 
    938939 
    939 Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'. 
     940Returns ``'s'`` if the value is not 1. 
     941 
     942Example:: 
     943 
     944    You have {{ num_messages }} message{{ num_messages|pluralize }}. 
    940945 
    941946pprint