Added missing reference.

[jinja2.git] / docs / api.rst

diff --git a/docs/api.rst b/docs/api.rst
index 35b4cf624eb20c9ffe4a9190346314c3cfe1b2fd..89fe11da09911f5c654da5c3b50f9d967f0aa7f0 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -220,6 +220,38 @@ useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
     :members: disable_buffering, enable_buffering, dump
 
 
+Autoescaping
+------------
+
+.. versionadded:: 2.4
+
+As of Jinja 2.4 the preferred way to do autoescaping is to enable the
+:ref:`autoescape-extension` and to configure a sensible default for
+autoescaping.  This makes it possible to enable and disable autoescaping
+on a per-template basis (HTML versus text for instance).
+
+Here a recommended setup that enables autoescaping for templates ending
+in ``'.html'``, ``'.htm'`` and ``'.xml'`` and disabling it by default
+for all other extensions::
+
+    def guess_autoescape(template_name):
+        if template_name is None or '.' not in template_name:
+            return False
+        ext = template_name.rsplit('.', 1)[1]
+        return ext in ('html', 'htm', 'xml')
+
+    env = Environment(autoescape=guess_autoescape,
+                      loader=PackageLoader('mypackage'),
+                      extensions=['jinja2.ext.autoescape'])
+
+When implementing a guessing autoescape function, make sure you also
+accept `None` as valid template name.  This will be passed when generating
+templates from strings.
+
+Inside the templates the behaviour can be temporarily changed by using
+the `autoescape` block (see :ref:`autoescape-overrides`).
+
+
 .. _identifier-naming:
 
 Notes on Identifiers
@@ -353,6 +385,10 @@ The Context
         blocks registered.  The last item in each list is the current active
         block (latest in the inheritance chain).
 
+    .. attribute:: eval_ctx
+
+        The current :ref:`eval-context`.
+
     .. automethod:: jinja2.runtime.Context.call(callable, \*args, \**kwargs)
 
 
@@ -450,10 +486,14 @@ functions to a Jinja2 environment.
 
 .. autofunction:: jinja2.contextfilter
 
+.. autofunction:: jinja2.evalcontextfilter
+
 .. autofunction:: jinja2.environmentfunction
 
 .. autofunction:: jinja2.contextfunction
 
+.. autofunction:: jinja2.evalcontextfunction
+
 .. function:: escape(s)
 
     Convert the characters ``&``, ``<``, ``>``, ``'``, and ``"`` in string `s`
@@ -545,7 +585,8 @@ Inside the template it can then be used as follows:
 Filters can also be passed the current template context or environment.  This
 is useful if a filter wants to return an undefined value or check the current
 :attr:`~Environment.autoescape` setting.  For this purpose two decorators
-exist: :func:`environmentfilter` and :func:`contextfilter`.
+exist: :func:`environmentfilter`, :func:`contextfilter` and
+:func:`evalcontextfilter`.
 
 Here a small example filter that breaks a text into HTML line breaks and
 paragraphs and marks the return value as safe HTML string if autoescaping is
@@ -556,11 +597,11 @@ enabled::
 
     _paragraph_re = re.compile(r'(?:\r\n|\r|\n){2,}')
 
-    @environmentfilter
-    def nl2br(environment, value):
+    @evalcontextfilter
+    def nl2br(eval_ctx, value):
         result = u'\n\n'.join(u'<p>%s</p>' % p.replace('\n', '<br>\n')
                               for p in _paragraph_re.split(escape(value)))
-        if environment.autoescape:
+        if eval_ctx.autoescape:
             result = Markup(result)
         return result
 
@@ -568,6 +609,68 @@ Context filters work the same just that the first argument is the current
 active :class:`Context` rather then the environment.
 
 
+.. _eval-context:
+
+Evaluation Context
+------------------
+
+The evaluation context (short eval context or eval ctx) is a new object
+introducted in Jinja 2.4 that makes it possible to activate and deactivate
+compiled features at runtime.
+
+Currently it is only used to enable and disable the automatic escaping but
+can be used for extensions as well.
+
+In previous Jinja versions filters and functions were marked as
+environment callables in order to check for the autoescape status from the
+environment.  In new versions it's encouraged to check the setting from the
+evaluation context instead.
+
+Previous versions::
+
+    @environmentfilter
+    def filter(env, value):
+        result = do_something(value)
+        if env.autoescape:
+            result = Markup(result)
+        return result
+
+In new versions you can either use a :func:`contextfilter` and access the
+evaluation context from the actual context, or use a
+:func:`evalcontextfilter` which directly passes the evaluation context to
+the function::
+
+    @contextfilter
+    def filter(context, value):
+        result = do_something(value)
+        if context.eval_ctx.autoescape:
+            result = Markup(result)
+        return result
+
+    @evalcontextfilter
+    def filter(eval_ctx, value):
+        result = do_something(value)
+        if eval_ctx.autoescape:
+            result = Markup(result)
+        return result
+
+The evaluation context must not be modified at runtime.  Modifications
+must only happen with a :class:`nodes.EvalContextModifier` and
+:class:`nodes.ScopedEvalContextModifier` from an extension, not on the
+eval context object itself.
+
+.. autoclass:: jinja2.nodes.EvalContext
+
+   .. attribute:: autoescape
+
+      `True` or `False` depending on if autoescaping is active or not.
+
+   .. attribute:: volatile
+
+      `True` if the compiler cannot evaluate some expressions at compile
+      time.  At runtime this should always be `False`.
+
+
 .. _writing-tests:
 
 Custom Tests