diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/deprecation.txt | 1 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 5 | ||||
| -rw-r--r-- | docs/ref/templates/api.txt | 36 | ||||
| -rw-r--r-- | docs/releases/1.6.txt | 2 | ||||
| -rw-r--r-- | docs/releases/1.8.txt | 1 | ||||
| -rw-r--r-- | docs/topics/templates.txt | 6 |
6 files changed, 28 insertions, 23 deletions
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index eaaec49349..415b61eafd 100644 --- a/docs/internals/deprecation.txt +++ b/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. diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index de50302e97..dd01e9e1cd 100644 --- a/docs/ref/settings.txt +++ b/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`. diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index ce28fbff74..5aacb2bc09 100644 --- a/docs/ref/templates/api.txt +++ b/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 -:setting:`TEMPLATE_STRING_IF_INVALID` is set to any other value, variable -filters will be ignored. +``string_if_invalid`` is set to ``''`` (the empty string). If +``string_if_invalid`` is set to any other value, variable filters will be +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 -be replaced with the name of the invalid variable. +If ``string_if_invalid`` contains a ``'%s'``, the format marker will be +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, - it is a bad idea to turn it on as a 'development default'. + While ``string_if_invalid`` can be a useful debugging tool, it is a bad + idea to turn it on as a 'development default'. - Many templates, including those in the Admin site, rely upon the - silence of the template system when a non-existent variable is - encountered. If you assign a value other than ``''`` to - :setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering - problems with these templates and sites. + Many templates, including those in the Admin site, rely upon the silence + of the template system when a non-existent variable is encountered. If you + assign a value other than ``''`` to ``string_if_invalid``, you will + experience rendering problems with these templates and sites. - Generally, :setting:`TEMPLATE_STRING_IF_INVALID` should only be enabled - in order to debug a specific template problem, then cleared - once debugging is complete. + Generally, ``string_if_invalid`` should only be enabled in order to debug + a specific template problem, then cleared once debugging is complete. Builtin variables ~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index bdf4e2f918..538394b2a3 100644 --- a/docs/releases/1.6.txt +++ b/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 diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index 8ce36fcb6c..d43ab2e51b 100644 --- a/docs/releases/1.8.txt +++ b/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`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index e245a7899e..dc145924c9 100644 --- a/docs/topics/templates.txt +++ b/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 -the value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set -to ``''`` (the empty string) by default. +If you use a variable that doesn't exist, the template system will insert the +value of the ``string_if_invalid`` option, which is set to ``''`` (the empty +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", |