From d84ec46a1c6a11a53ed8f1f517e597425a406217 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Tue, 29 Apr 2008 13:43:16 +0200 Subject: [PATCH] again documentation updates fixed another python 2.4 bug. Imports are not evaluated with the template context any longer which makes it possible to keep them in memory --HG-- branch : trunk --- docs/api.rst | 2 +- docs/templates.rst | 287 ++++++++++++++++++++++++++++++++++-------- jinja2/compiler.py | 9 +- jinja2/environment.py | 44 +++---- jinja2/ext.py | 12 +- jinja2/nodes.py | 9 ++ jinja2/runtime.py | 11 +- jinja2/utils.py | 10 +- 8 files changed, 287 insertions(+), 97 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 7dacf36..18ef9a2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -83,7 +83,7 @@ High Level API .. autoclass:: jinja2.Template - :members: render, stream, generate, include + :members: render, stream, generate, module .. autoclass:: jinja2.environment.TemplateStream diff --git a/docs/templates.rst b/docs/templates.rst index 9700cda..384d27e 100644 --- a/docs/templates.rst +++ b/docs/templates.rst @@ -1,6 +1,8 @@ Template Designer Documentation =============================== +.. highlight:: html+jinja + This document describes the syntax and semantics of the template engine and will be most useful as reference to those creating Jinja templates. As the template engine is very flexible the configuration from the application might @@ -20,9 +22,7 @@ values when the template is evaluated, and tags, which control the logic of the template. The template syntax is heavily inspired by Django and Python. Below is a minimal template that illustrates a few basics. We will cover -the details later in that document: - -.. sourcecode:: html+jinja +the details later in that document:: @@ -60,9 +60,7 @@ those. You can use a dot (``.``) to access attributes of a variable, alternative the so-called "subscribe" syntax (``[]``) can be used. The following lines do -the same: - -.. sourcecode:: jinja +the same:: {{ foo.bar }} {{ foo['bar'] }} @@ -106,9 +104,7 @@ which will then return true or false depening on if `name` is defined. Tests can accept arguments too. If the test only takes one argument you can leave out the parentheses to group them. For example the following two -expressions do the same: - -.. sourcecode:: jinja +expressions do the same:: {% if loop.index is divisibleby 3 %} {% if loop.index is divisibleby(3) %} @@ -122,9 +118,7 @@ Comments To comment-out part of a line in a template, use the comment syntax which is by default set to ``{# ... #}``. This is useful to comment out parts of the template for debugging or to add information for other template designers or -yourself: - -.. sourcecode:: jinja +yourself:: {# note: disabled template because we no longer user this {% for user in users %} @@ -132,6 +126,7 @@ yourself: {% endfor %} #} +.. _template-inheritance: Template Inheritance -------------------- @@ -149,9 +144,7 @@ Base Template This template, which we'll call ``base.html``, defines a simple HTML skeleton document that you might use for a simple two-column page. It's the job of -"child" templates to fill the empty blocks with content: - -.. sourcecode:: html+jinja +"child" templates to fill the empty blocks with content:: @@ -178,9 +171,7 @@ child template may override those portions of the template. Child Template ~~~~~~~~~~~~~~ -A child template might look like this: - -.. sourcecode:: html+jinja +A child template might look like this:: {% extends "base.html" %} {% block title %}Index{% endblock %} @@ -205,9 +196,7 @@ may cause confusion. The filename of the template depends on the template loader. For example the :class:`FileSystemLoader` allows you to access other templates by giving the -filename. You can access templates in subdirectories with an slash: - -.. sourcecode:: jinja +filename. You can access templates in subdirectories with an slash:: {% extends "layout/default.html" %} @@ -223,9 +212,7 @@ were two similarly-named ``{% block %}`` tags in a template, that template's parent wouldn't know which one of the blocks' content to use. If you want to print a block multiple times you can however use the special -`self` variable and call the block with that name: - -.. sourcecode:: jinja +`self` variable and call the block with that name:: {% block title %}{% endblock %}

{{ self.title() }}

@@ -240,9 +227,7 @@ Super Blocks ~~~~~~~~~~~~ It's possible to render the contents of the parent block by calling `super`. -This gives back the results of the parent block: - -.. sourcecode:: jinja +This gives back the results of the parent block:: {% block sidebar %}

Table Of Contents

@@ -310,13 +295,11 @@ program - conditionals (i.e. if/elif/else), for-loops, as well as things like macros and blocks. Control structures appear inside ``{% ... %}`` blocks in the default syntax. -For Loops -~~~~~~~~~ +For +~~~ Loop over each item in a sequece. For example, to display a list of users -provided in a variable called `users`: - -.. sourcecode:: html+jinja +provided in a variable called `users`::

Members