[1.11.x] Fixed #26817 -- Doc'd downsides and alternatives to Jinja2 context processors.

Thanks Aymeric Augustin and Carl Meyer.

Backport of dacdcec767ae23b4c7107bfe447d29a1c88af48c from master

1 files changed, 26 insertions, 0 deletions

diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt
index 37a39c0607..854596bc37 100644
--- a/docs/topics/templates.txt
+++ b/docs/topics/templates.txt
@@ -419,6 +419,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.