From dacdcec767ae23b4c7107bfe447d29a1c88af48c Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Mon, 6 Mar 2017 13:34:48 -0500 Subject: [PATCH] Fixed #26817 -- Doc'd downsides and alternatives to Jinja2 context processors. Thanks Aymeric Augustin and Carl Meyer. --- docs/topics/templates.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index df5bd9d460..3c71608a45 100644 --- a/docs/topics/templates.txt +++ b/docs/topics/templates.txt @@ -415,6 +415,32 @@ adds defaults that differ from Jinja2's for a few options: It defaults to an empty list. + .. admonition:: Using context processors with Jinja2 templates is discouraged. + + Context processors are useful with Django templates because Django templates + don't support calling functions with arguments. Since Jinja2 doesn't have + that limitation, it's recommended to put the function that you would use as a + context processor in the global variables available to the template using + ``jinja2.Environment`` as described below. You can then call that function in + the template: + + .. code-block:: jinja + + {{ function(request) }} + + Some Django templates context processors return a fixed value. For Jinja2 + templates, this layer of indirection isn't necessary since you can add + constants directly in ``jinja2.Environment``. + + The original use case for adding context processors for Jinja2 involved: + + * Making an expensive computation that depends on the request. + * Needing the result in every template. + * Using the result multiple times in each template. + + Unless all of these conditions are met, passing a function to the template is + simpler and more in line with the design of Jinja2. + .. versionadded:: 1.11 The ``'context_processors'`` option was added.