From 6b68559c9a85ebdad896f54986beda90f02ed5d2 Mon Sep 17 00:00:00 2001 From: Wilson Miner Date: Fri, 15 Jul 2005 21:44:19 +0000 Subject: [PATCH] Clarified template documentation git-svn-id: http://code.djangoproject.com/svn/django/trunk@73 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/templates.txt | 110 +++++++++++++++++++++++---------------------- 1 file changed, 56 insertions(+), 54 deletions(-) diff --git a/docs/templates.txt b/docs/templates.txt index 671ad75123..678dec8761 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -21,10 +21,10 @@ To actually be useful, a template will contain **variables**, which get replaced with values from the database when the template is evaluated, and **tags**, which control the logic of the template. -Below is a minimal template that I'll be using to illustrate the parts of a -template throughout this introduction:: +Below is a minimal template that illustrates the basic parts of a +template. Each element will be explained later in this document.:: - {% extends base_generic %} + {% extends "base_generic" %} {% block title %}{{ section.title }}{% endblock %} @@ -47,8 +47,8 @@ What's a variable? Variables look like this: ``{{ variable }}``. When the template engine encounters a variable, it evaluates that variable and replaces the variable with the result. Many variables will be structures with named attributes; you can -"drill down" into these structures with dots (``.``), so in the above example `` -{{ section.title }}`` will be replaced with the ``title`` attribute of the +"drill down" into these structures with dots (``.``), so in the above example +``{{ section.title }}`` will be replaced with the ``title`` attribute of the ``section`` object. If you use a variable that doesn't exist, it will be silently ignored; the @@ -68,10 +68,9 @@ as you might have guessed, lowercases the text passed through it. We use the pipe character to apply filters to emphasize the analogy with filters on a water pipe: text enters one side, has some operation performed on it, and -"flows" out the other side. Stretching the analogy to the breaking point, -filters may 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 ``

`` tags. +"flows" out the other side. Filters may 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 ``

`` tags. Certain filters take arguments; a filter argument looks like this: ``{{ bio|truncatewords:"30" }}``. This will display the first 30 words of the @@ -120,34 +119,36 @@ It's easiest to understand template inheritance by starting with an example:: This template, which we'll call ``base.html`` defines a simple HTML skeleton -document that you might use for a simple two-column page. Since this template -won't actually be used directly, I've used the ``{% block %}`` tag to define the -three blocks that child templates will fill in. All that the ``block`` tag does -is to signal to the template engine that a child template may override those -portions of the template. +document that you might use for a simple two-column page. This template +won't actually be used directly on any pages, but other "child" templates will +extend it and fill in the empty blocks with content. + +I've used the ``{% block %}`` tag to define the three blocks that child templates +will fill in. All that the ``block`` tag does is to signal to the template engine +that a child template may override those portions of the template. To use this template, I might define a child template as follows:: {% extends "base" %} - {% block title %}My Amazing Blog{% endblock %} + {% block title %}My Amazing Blog{% endblock %} - {% block content %} + {% block content %} - {% for entry in blog_entries %} -

{{ entry.title }}

-

{{ entry.body }}

- {% endfor %} + {% for entry in blog_entries %}

{{ entry.title }}

{{ entry.body + }}

{% endfor %} - {% endblock %} + {% endblock %} The ``{% extends %}`` tag is the key here; it tells the template engine that -this template "extends" another template. When this template is evaluated, the -first step the template engine will perform is to locate the parent template -- -in this case, "base" (note the dropping of the ".html" extension). 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:: +this template "extends" another template. When this template is evaluated, +the first step the template engine will perform is to locate the parent +template -- in this case, "base" (note the dropping of the ".html" +extension). + +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:: @@ -192,8 +193,8 @@ Here are some tips for working with inheritance: * We often prefer to use three-level inheritance: 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 page. This - maximizes code reuse, and makes adding items to places like the - section-wide navigation possible. + maximizes code reuse, and makes it easier to add items to shared + content areas (like 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 @@ -204,39 +205,40 @@ 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 your admin interface -has a complete reference of all the template goodies available to you. +variables available will be different depending on the application. To make it +simple 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. This documentation is integrated into the administration interface for your -sites and 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 any custom -tag or filter libraries available. +sites and is divided into 4 sections: tags, filters, models, and views. -The views page is perhaps the most valuable. Each URL in your site has a +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 +any custom tag or filter libraries available. + +The **views** page is perhaps the most valuable. Each URL in your site has a separate 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 each variable available in the view. + * The **context**, or a list of variables available in the view. * The name of the template or templates that are used for that view. - -The documentation page also has a bookmarklet that you can use to jump from any -page to the documentation page for that view. -Since most of Django revolves around 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. +Each view documentation page also has a bookmarklet that you can use to jump +from any page to the documentation page for that view. -Take together, the documentation pages should tell you every tag, filter, +Since most of Django revolves around 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. + +Taken together, the documentation pages should tell you every tag, filter, variable and object available to you in a given template. Custom tag and filter libraries =============================== As mentioned above, certain applications will provide custom tag and filter -libraries. To use them, use the ``{% load %}`` tag:: +libraries. To access them in a template, use the ``{% load %}`` tag:: {% load comments %} @@ -251,8 +253,8 @@ Built-in tag and filter reference For those without an admin site available, the reference for the stock tags and filters follows. Since Django is highly customizable, the documentation -references in your admin should be considered the final word on these -tags/filters. +references in your admin should be considered the final word on what +tags and filters are available and their functions. Built-in tag reference ---------------------- @@ -604,7 +606,7 @@ Built-in filter reference ``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 @@ -631,7 +633,7 @@ Built-in filter reference ``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. @@ -666,7 +668,7 @@ Built-in filter reference ``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 -- @@ -700,7 +702,7 @@ Built-in filter reference ``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 @@ -708,7 +710,7 @@ Built-in filter reference ``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, @@ -721,5 +723,5 @@ Built-in filter reference ``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. + if no mapping for None is given) ========== ====================== ==================================