Deprecated TEMPLATE_STRING_IF_INVALID.

docs/internals/deprecation.txt

@@ -90,6 +90,7 @@ details on these changes.
 * The following settings will be removed:
 
   * ``ALLOWED_INCLUDE_ROOTS``
+  * ``TEMPLATE_STRING_IF_INVALID``
 
 * The backwards compatibility alias ``django.template.loader.BaseLoader`` will
   be removed.

docs/ref/settings.txt

@@ -2452,6 +2452,11 @@ TEMPLATE_STRING_IF_INVALID
 
 Default: ``''`` (Empty string)
 
+.. deprecated:: 1.8
+
+    Set the ``'string_if_invalid'`` option in the :setting:`OPTIONS
+    <TEMPLATES-OPTIONS>` of a ``DjangoTemplates`` backend instead.
+
 Output, as a string, that the template system should use for invalid (e.g.
 misspelled) variables. See :ref:`invalid-template-variables`.
 

docs/ref/templates/api.txt

@@ -171,7 +171,7 @@ straight lookups. Here are some things to keep in mind:
   ``silent_variable_failure`` whose value is ``True``. If the exception
   *does* have a ``silent_variable_failure`` attribute whose value is
   ``True``, the variable will render as the value of the
-  :setting:`TEMPLATE_STRING_IF_INVALID` setting (an empty string, by default).
+  ``string_if_invalid`` configuration option (an empty string, by default).
   Example::
 
     >>> t = Template("My name is {{ person.first_name }}.")
@@ -200,7 +200,7 @@ straight lookups. Here are some things to keep in mind:
   silently.
 
 * A variable can only be called if it has no required arguments. Otherwise,
-  the system will return the value of :setting:`TEMPLATE_STRING_IF_INVALID`.
+  the system will return the value of the ``string_if_invalid`` option.
 
 .. _alters-data-description:
 
@@ -217,7 +217,7 @@ straight lookups. Here are some things to keep in mind:
   To prevent this, set an ``alters_data`` attribute on the callable
   variable. The template system won't call a variable if it has
   ``alters_data=True`` set, and will instead replace the variable with
-  :setting:`TEMPLATE_STRING_IF_INVALID`, unconditionally.  The
+  ``string_if_invalid``, unconditionally.  The
   dynamically-generated :meth:`~django.db.models.Model.delete` and
   :meth:`~django.db.models.Model.save` methods on Django model objects get
   ``alters_data=True`` automatically. Example::
@@ -239,36 +239,34 @@ How invalid variables are handled
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Generally, if a variable doesn't exist, the template system inserts the
-value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to
+value of the ``string_if_invalid`` configuration option, which is set to
 ``''`` (the empty string) by default.
 
 Filters that are applied to an invalid variable will only be applied if
-:setting:`TEMPLATE_STRING_IF_INVALID` is set to ``''`` (the empty string). If
+``string_if_invalid`` is set to ``''`` (the empty string). If
-:setting:`TEMPLATE_STRING_IF_INVALID` is set to any other value, variable
+``string_if_invalid`` is set to any other value, variable filters will be
-filters will be ignored.
+ignored.
 
 This behavior is slightly different for the ``if``, ``for`` and ``regroup``
 template tags. If an invalid variable is provided to one of these template
 tags, the variable will be interpreted as ``None``. Filters are always
 applied to invalid variables within these template tags.
 
-If :setting:`TEMPLATE_STRING_IF_INVALID` contains a ``'%s'``, the format marker will
+If ``string_if_invalid`` contains a ``'%s'``, the format marker will be
-be replaced with the name of the invalid variable.
+replaced with the name of the invalid variable.
 
 .. admonition:: For debug purposes only!
 
-    While :setting:`TEMPLATE_STRING_IF_INVALID` can be a useful debugging tool,
+    While ``string_if_invalid`` can be a useful debugging tool, it is a bad
-    it is a bad idea to turn it on as a 'development default'.
+    idea to turn it on as a 'development default'.
 
-    Many templates, including those in the Admin site, rely upon the
+    Many templates, including those in the Admin site, rely upon the silence
-    silence of the template system when a non-existent variable is
+    of the template system when a non-existent variable is encountered. If you
-    encountered. If you assign a value other than ``''`` to
+    assign a value other than ``''`` to ``string_if_invalid``, you will
-    :setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering
+    experience rendering problems with these templates and sites.
-    problems with these templates and sites.
 
-    Generally, :setting:`TEMPLATE_STRING_IF_INVALID` should only be enabled
+    Generally, ``string_if_invalid`` should only be enabled in order to debug
-    in order to debug a specific template problem, then cleared
+    a specific template problem, then cleared once debugging is complete.
-    once debugging is complete.
 
 Builtin variables
 ~~~~~~~~~~~~~~~~~

docs/releases/1.6.txt

@@ -233,7 +233,7 @@ Minor features
   PostgreSQL.
 
 * The :ttag:`blocktrans` template tag now respects
-  :setting:`TEMPLATE_STRING_IF_INVALID` for variables not present in the
+  ``TEMPLATE_STRING_IF_INVALID`` for variables not present in the
   context, just like other template constructs.
 
 * ``SimpleLazyObject``\s will now present more helpful representations in shell

docs/releases/1.8.txt

@@ -1021,6 +1021,7 @@ As a consequence of the multiple template engines refactor, several settings
 are deprecated in favor of :setting:`TEMPLATES`:
 
 * ``ALLOWED_INCLUDE_ROOTS``
+* ``TEMPLATE_STRING_IF_INVALID``
 
 ``django.core.context_processors``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/topics/templates.txt

@@ -116,9 +116,9 @@ Use a dot (``.``) to access attributes of a variable.
 In the above example, ``{{ section.title }}`` will be replaced with the
 ``title`` attribute of the ``section`` object.
 
-If you use a variable that doesn't exist, the template system will insert
+If you use a variable that doesn't exist, the template system will insert the
-the value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set
+value of the ``string_if_invalid`` option, which is set to ``''`` (the empty
-to ``''`` (the empty string) by default.
+string) by default.
 
 Note that "bar" in a template expression like ``{{ foo.bar }}`` will be
 interpreted as a literal string and not using the value of the variable "bar",

tests/template_tests/test_callables.py

@@ -53,7 +53,7 @@ class CallableVariablesTests(TestCase):
         c = template.Context({"my_doodad": my_doodad})
 
         # Since ``my_doodad.alters_data`` is True, the template system will not
-        # try to call our doodad but will use TEMPLATE_STRING_IF_INVALID
+        # try to call our doodad but will use string_if_invalid
         t = template.Template('{{ my_doodad.value }}')
         self.assertEqual(t.render(c), '')
         t = template.Template('{{ my_doodad.the_value }}')

tests/template_tests/tests.py

@@ -258,7 +258,13 @@ class TemplateRegressionTests(SimpleTestCase):
         with self.assertRaises(urlresolvers.NoReverseMatch):
             t.render(c)
 
-    @override_settings(TEMPLATE_STRING_IF_INVALID='%s is invalid', SETTINGS_MODULE='also_something')
+    @override_settings(
+        TEMPLATES=[{
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'OPTIONS': {'string_if_invalid': '%s is invalid'},
+        }],
+        SETTINGS_MODULE='also_something',
+    )
     def test_url_reverse_view_name(self):
         # Regression test for #19827
         t = Template('{% url will_not_match %}')

tests/template_tests/utils.py

@@ -22,14 +22,14 @@ def setup(templates, *args):
     """
     Runs test method multiple times in the following order:
 
-    TEMPLATE_DEBUG      CACHED      TEMPLATE_STRING_IF_INVALID
+    debug       cached      string_if_invalid
-    --------------      ------      --------------------------
+    -----       ------      -----------------
-    False               False
+    False       False
-    False               True
+    False       True
-    False               False       INVALID
+    False       False       INVALID
-    False               True        INVALID
+    False       True        INVALID
-    True                False
+    True        False
-    True                True
+    True        True
     """
 
     for arg in args: