From e225481f2fa2df153d2a9fb2f120051979bc29fe Mon Sep 17 00:00:00 2001
From: Tim Heap <tim@timheap.me>
Date: Thu, 1 Oct 2015 15:52:04 +1000
Subject: [PATCH] Add documentation for using Jinja2

---
 docs/advanced_topics/index.rst    |  1 +
 docs/advanced_topics/jinja2.rst   | 97 +++++++++++++++++++++++++++++++
 docs/topics/writing_templates.rst | 12 +++-
 3 files changed, 107 insertions(+), 3 deletions(-)
 create mode 100644 docs/advanced_topics/jinja2.rst

diff --git a/docs/advanced_topics/index.rst b/docs/advanced_topics/index.rst
index 50909406b..ce28b9e41 100644
--- a/docs/advanced_topics/index.rst
+++ b/docs/advanced_topics/index.rst
@@ -12,3 +12,4 @@ Advanced topics
     privacy
     customisation/index
     third_party_tutorials
+    jinja2
diff --git a/docs/advanced_topics/jinja2.rst b/docs/advanced_topics/jinja2.rst
new file mode 100644
index 000000000..9913a592b
--- /dev/null
+++ b/docs/advanced_topics/jinja2.rst
@@ -0,0 +1,97 @@
+.. _jinja2:
+
+=======================
+Jinja2 template support
+=======================
+
+Wagtail supports Jinja2 templating for all front end features. More information on each of the template tags below can be found in the :ref:`writing_templates` documentation.
+
+Configuring Django
+==================
+
+Django needs to be configured to support Jinja2 templates. As the Wagtail admin is written using regular Django templates, Django has to be configured to use both templating engines. Wagtail supports the Jinja2 backend that ships with Django 1.8 and above. Add the following configuration to the ``TEMPLATES`` setting for your app:
+
+.. code-block:: python
+
+    TEMPLATES = [
+        # ...
+        {
+            'BACKEND': 'django.template.backends.jinja2.Jinja2',
+            'APP_DIRS': True,
+            'OPTIONS': {
+                'extensions': [
+                    'wagtail.wagtailcore.templatetags.jinja2.core',
+                    'wagtail.wagtailadmin.templatetags.jinja2.userbar',
+                    'wagtail.wagtailimages.templatetags.jinja2.images',
+                ],
+            },
+        }
+    ]
+
+``self`` in templates
+=====================
+
+In Django templates, ``self`` is used to refer to the current page, stream block, or field panel. In Jinja, ``self`` is reserved for internal use. When writing Jinja templates, use ``page`` to refer to pages, ``value`` for stream blocks, and ``field_panel`` for field panels.
+
+Template functions & filters
+============================
+
+``pageurl()``
+~~~~~~~~~~~~~
+
+Generate a URL for a Page instance:
+
+.. code-block:: html+jinja
+
+    <a href="{{ pageurl(page.more_information) }}">More information</a>
+
+See :ref:`pageurl_tag` for more information
+
+``slugurl()``
+~~~~~~~~~~~~~
+
+Generate a URL for a Page with a slug:
+
+.. code-block:: html+jinja
+
+    <a href="{{ pageurl("about") }}">About us</a>
+
+See :ref:`slugurl_tag` for more information
+
+``image()``
+~~~~~~~~~~~
+
+Resize an image, and print an ``<img>`` tag:
+
+.. code-block:: html+jinja
+
+    {# Print an image tag #}
+    {{ image(page.header_image, "fill-1024x200", class="header-image") }}
+
+    {# Resize an image #}
+    {% set background=image(page.background_image, "max-1024x1024") %}
+    <div class="wrapper" style="background-image: url({{ background.url }});">
+
+See :ref:`image_tag` for more information
+
+``|richtext``
+~~~~~~~~~~~~~
+
+Transform Wagtail's internal HTML representation, expanding internal references to pages and images.
+
+.. code-block:: html+jinja
+
+    {{ page.body|richtext }}
+
+See :ref:`rich-text-filter` for more information
+
+``wagtailuserbar()``
+~~~~~~~~~~~~~~~~~~~~
+
+Output the Wagtail contextual flyout menu for editing pages from the front end
+
+.. code-block:: html+jinja
+
+    {{ wagtailuserbar() }}
+
+See :ref:`wagtailuserbar_tag` for more information
diff --git a/docs/topics/writing_templates.rst b/docs/topics/writing_templates.rst
index d8c85f720..8f6f0aa28 100644
--- a/docs/topics/writing_templates.rst
+++ b/docs/topics/writing_templates.rst
@@ -1,3 +1,5 @@
+.. _writing_templates:
+
 =================
 Writing templates
 =================
@@ -80,7 +82,6 @@ In addition to Django's standard tags and filters, Wagtail provides some of its
 Images (tag)
 ~~~~~~~~~~~~
 
-
 The ``image`` tag inserts an XHTML-compatible ``img`` element into the page, setting its ``src``, ``width``, ``height`` and ``alt``. See also :ref:`image_tag_alt`.
 
 The syntax for the tag is thus::
@@ -147,6 +148,8 @@ Wagtail embeds and images are included at their full width, which may overflow t
 Internal links (tag)
 ~~~~~~~~~~~~~~~~~~~~
 
+.. _pageurl_tag:
+
 ``pageurl``
 -----------
 
@@ -158,8 +161,10 @@ Takes a Page object and returns a relative URL (``/foo/bar/``) if within the sam
     ...
     <a href="{% pageurl self.blog_page %}">
 
-slugurl
---------
+.. _slugurl_tag:
+
+``slugurl``
+------------
 
 Takes any ``slug`` as defined in a page's "Promote" tab and returns the URL for the matching Page. Like ``pageurl``, will try to provide a relative link if possible, but will default to an absolute link if on a different site. This is most useful when creating shared page furniture e.g top level navigation or site-wide links.
 
@@ -186,6 +191,7 @@ Used to load anything from your static files directory. Use of this tag avoids r
 Notice that the full path name is not required and the path snippet you enter only need begin with the parent app's directory name.
 
 
+.. _wagtailuserbar_tag:
 
 Wagtail User Bar
 ================