From d5e924a83c8627570ca6a04c52a20d5384446e00 Mon Sep 17 00:00:00 2001
From: Ben Darnell <ben@bendarnell.com>
Date: Sat, 10 Sep 2011 15:10:31 -0700
Subject: [PATCH] Add reference docs for all template directives.

Closes #355.
---
 tornado/template.py           | 85 +++++++++++++++++++++++++++++++++++
 tornado/test/template_test.py | 14 ++++++
 website/sphinx/template.rst   | 18 +++++++-
 3 files changed, 116 insertions(+), 1 deletion(-)

diff --git a/tornado/template.py b/tornado/template.py
index db4305b4..f28f4035 100644
--- a/tornado/template.py
+++ b/tornado/template.py
@@ -82,6 +82,91 @@ Typical applications do not create `Template` or `Loader` instances by
 hand, but instead use the `render` and `render_string` methods of
 `tornado.web.RequestHandler`, which load templates automatically based
 on the ``template_path`` `Application` setting.
+
+Syntax Reference
+----------------
+
+Template expressions are surrounded by double curly braces: ``{{ ... }}``.
+The contents may be any python expression, which will be escaped according
+to the current autoescape setting and inserted into the output.  Other
+template directives use ``{% %}``.  These tags may be escaped as ``{{!``
+and ``{%!`` if you need to include a literal ``{{`` or ``{%`` in the output.
+
+``{% apply *function* %}...{% end %}``
+    Applies a function to the output of all template code between ``apply``
+    and ``end``::
+
+        {% apply linkify %}{{name}} said: {{message}}{% end %}
+
+``{% autoescape *function* %}``
+    Sets the autoescape mode for the current file.  This does not affect
+    other files, even those referenced by ``{% include %}``.  Note that
+    autoescaping can also be configured globally, at the `Application`
+    or `Loader`.::
+
+        {% autoescape xhtml_escape %}
+        {% autoescape None %}
+
+``{% block *name* %}...{% end %}``
+    Indicates a named, replaceable block for use with ``{% extends %}``.
+    Blocks in the parent template will be replaced with the contents of
+    the same-named block in a child template.::
+
+        <!-- base.html -->
+        <title>{% block title %}Default title{% end %}</title>
+
+        <!-- mypage.html -->
+        {% extends "base.html" %}
+        {% block title %}My page title{% end %}
+
+``{% comment ... %}``
+    A comment which will be removed from the template output.  Note that
+    there is no ``{% end %}`` tag; the comment goes from the word ``comment``
+    to the closing ``%}`` tag.
+
+``{% extends *filename* %}``
+    Inherit from another template.  Templates that use ``extends`` should
+    contain one or more ``block`` tags to replace content from the parent
+    template.  Anything in the child template not contained in a ``block``
+    tag will be ignored.  For an example, see the ``{% block %}`` tag.
+
+``{% for *var* in *expr* %}...{% end %}``
+    Same as the python ``for`` statement.
+    
+``{% from *x* import *y* %}``
+    Same as the python ``import`` statement.
+
+``{% if *condition* %}...{% elif *condition* %}...{% else %}...{% end %}``
+    Conditional statement - outputs the first section whose condition is
+    true.  (The ``elif`` and ``else`` sections are optional)
+
+``{% import *module* %}``
+    Same as the python ``import`` statement.
+
+``{% include *filename* %}``
+    Includes another template file.  The included file can see all the local
+    variables as if it were copied directly to the point of the ``include``
+    directive (the ``{% autoescape %}`` directive is an exception).
+    Alternately, ``{% module Template(filename, **kwargs) %}`` may be used
+    to include another template with an isolated namespace.
+
+``{% module *expr* %}``
+    Renders a `~tornado.web.UIModule`.  The output of the ``UIModule`` is
+    not escaped::
+
+        {% module Template("foo.html", arg=42) %}
+
+``{% raw *expr* %}``
+    Outputs the result of the given expression without autoescaping.
+
+``{% set *x* = *y* %}``
+    Sets a local variable.
+
+``{% try %}...{% except %}...{% finally %}...{% end %}``
+    Same as the python ``try`` statement.
+
+``{% while *condition* %}... {% end %}``
+    Same as the python ``while`` statement.
 """
 
 from __future__ import with_statement
diff --git a/tornado/test/template_test.py b/tornado/test/template_test.py
index a903f61e..0d5fad9e 100644
--- a/tornado/test/template_test.py
+++ b/tornado/test/template_test.py
@@ -79,6 +79,20 @@ class TemplateTest(LogTrapTestCase):
         loader = DictLoader({"test.html": "{{ inc(5) }}"}, namespace={"inc": lambda x: x+1})
         self.assertEqual(loader.load("test.html").generate(), b("6"))
 
+    def test_apply(self):
+        def upper(s): return s.upper()
+        template = Template(utf8("{% apply upper %}foo{% end %}"))
+        self.assertEqual(template.generate(upper=upper), b("FOO"))
+
+    def test_if(self):
+        template = Template(utf8("{% if x > 4 %}yes{% else %}no{% end %}"))
+        self.assertEqual(template.generate(x=5), b("yes"))
+        self.assertEqual(template.generate(x=3), b("no"))
+
+    def test_comment(self):
+        template = Template(utf8("{% comment blah blah %}foo"))
+        self.assertEqual(template.generate(), b("foo"))
+
 
 class AutoEscapeTest(LogTrapTestCase):
     def setUp(self):
diff --git a/website/sphinx/template.rst b/website/sphinx/template.rst
index bb546d10..40d0be2b 100644
--- a/website/sphinx/template.rst
+++ b/website/sphinx/template.rst
@@ -2,4 +2,20 @@
 ===================================================
 
 .. automodule:: tornado.template
-   :members:   
+
+   Class reference
+   ---------------
+
+   .. autoclass:: Template
+      :members:
+
+   .. autoclass:: BaseLoader
+      :members:
+
+   .. autoclass:: Loader
+      :members:
+
+   .. autoclass:: DictLoader
+      :members:
+
+   .. autoexception:: ParseError