From 22ee68961a2bf44c6a395b7c746e6bdfceebf8f3 Mon Sep 17 00:00:00 2001 From: Malcolm Tredinnick Date: Sat, 20 Oct 2007 11:05:15 +0000 Subject: [PATCH] Added a section to the template documentation to clarify the arbitrary Python code should not be expected to work. The might help balance expectations. Thanks, James Bennett. Fixed #5125. git-svn-id: http://code.djangoproject.com/svn/django/trunk@6562 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/templates.txt | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/templates.txt b/docs/templates.txt index 41b15f3d193..eab4b129ce6 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -11,9 +11,26 @@ ease. It's designed to feel comfortable to those used to working with HTML. If you have any exposure to other text-based template languages, such as Smarty_ or CheetahTemplate_, you should feel right at home with Django's templates. +.. admonition:: Philosophy + + If you have a background in programming, or if you're used to languages + like PHP which mix programming code directly into HTML, you'll want to + bear in mind that the Django template system is not simply Python embedded + into HTML. This is by design: the template system is meant to express + presentation, not program logic. + + The Django template system provides tags which function similarly to some + programming constructs -- an ``{% if %}`` tag for boolean tests, a ``{% + for %}`` tag for looping, etc. -- but these are not simply executed as the + corresponding Python code, and the template system will not execute + arbitrary Python expressions. Only the tags, filters and syntax listed + below are supported by default (although you can add `your own + extensions`_ to the template language as needed). + .. _`The Django template language: For Python programmers`: ../templates_python/ .. _Smarty: http://smarty.php.net/ .. _CheetahTemplate: http://www.cheetahtemplate.org/ +.. _your own extensions: ../templates_python/#extending-the-template-system Templates ========= @@ -382,7 +399,7 @@ loop:: ... {% endfor %} - + Outside of a loop, give the values a unique name the first time you call it, then use that name each successive time through:: @@ -390,16 +407,16 @@ then use that name each successive time through:: ... ... -You can use any number of values, separated by spaces. Values enclosed in -single (') or double quotes (") are treated as string literals, while values -without quotes are assumed to refer to context variables. +You can use any number of values, separated by spaces. Values enclosed in +single (') or double quotes (") are treated as string literals, while values +without quotes are assumed to refer to context variables. You can also separate values with commas:: {% cycle row1,row2,row3 %} - -In this syntax, each value will be interpreted as literal text. The -comma-based syntax exists for backwards-compatibility, and should not be + +In this syntax, each value will be interpreted as literal text. The +comma-based syntax exists for backwards-compatibility, and should not be used for new projects. debug @@ -477,13 +494,13 @@ You can loop over a list in reverse by using ``{% for obj in list reversed %}``. If you need to loop over a list of lists, you can unpack the values in eachs sub-list into a set of known names. For example, if your context contains a list of (x,y) coordinates called ``points``, you could use the following -to output the list of points:: +to output the list of points:: {% for x, y in points %} There is a point at {{ x }},{{ y }} {% endfor %} - -This can also be useful if you need to access the items in a dictionary. + +This can also be useful if you need to access the items in a dictionary. For example, if your context contained a dictionary ``data``, the following would display the keys and values of the dictionary::