Removed settings.TEMPLATES upgrade guide.

This commit is contained in:
Tim Graham 2017-01-17 10:12:56 -05:00
parent 6192bffb13
commit 397b3705c5
4 changed files with 3 additions and 224 deletions

View File

@ -14,7 +14,6 @@ material, see :doc:`/topics/templates` topic guide.
language
builtins
api
upgrading
.. seealso::

View File

@ -1,217 +0,0 @@
=================================
Upgrading templates to Django 1.8
=================================
Django's template system was overhauled in Django 1.8 when it gained support
for multiple template engines. This document complements the :doc:`release
notes </releases/1.8>` with detailed upgrade instructions on some topics.
The :setting:`TEMPLATES` settings
=================================
A new setting was introduced in Django 1.8: :setting:`TEMPLATES`. All existing
template-related settings were deprecated.
During the deprecation period, Django will create a backwards-compatible
:setting:`TEMPLATES` based on the ``TEMPLATE_*`` settings if you don't define
it yourself.
Here's how to define :setting:`TEMPLATES` in your settings module.
If you're using the default value of ``TEMPLATE_LOADERS``, that is, if it
isn't defined in your settings file or if it's set to::
['django.template.loaders.filesystem.Loader',
'django.template.loaders.app_directories.Loader']
then you should define :setting:`TEMPLATES` as follows::
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [
# insert your TEMPLATE_DIRS here
],
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
# Insert your TEMPLATE_CONTEXT_PROCESSORS here or use this
# list if you haven't customized them:
'django.contrib.auth.context_processors.auth',
'django.template.context_processors.debug',
'django.template.context_processors.i18n',
'django.template.context_processors.media',
'django.template.context_processors.static',
'django.template.context_processors.tz',
'django.contrib.messages.context_processors.messages',
],
},
},
]
If you aren't using the default value of ``TEMPLATE_LOADERS``, then you should
define :setting:`TEMPLATES` as follows::
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [
# insert your TEMPLATE_DIRS here
],
'OPTIONS': {
'context_processors': [
# Insert your TEMPLATE_CONTEXT_PROCESSORS here or use this
# list if you haven't customized them:
'django.contrib.auth.context_processors.auth',
'django.template.context_processors.debug',
'django.template.context_processors.i18n',
'django.template.context_processors.media',
'django.template.context_processors.static',
'django.template.context_processors.tz',
'django.contrib.messages.context_processors.messages',
],
'loaders': [
# insert your TEMPLATE_LOADERS here
]
},
},
]
Furthermore you should replace ``django.core.context_processors`` with
``django.template.context_processors`` in the names of context processors.
If your settings module defines ``ALLOWED_INCLUDE_ROOTS`` or
``TEMPLATE_STRING_IF_INVALID``, include their values under the
``'allowed_include_roots'`` and ``'string_if_invalid'`` keys in the
``'OPTIONS'`` dictionary.
If it sets ``TEMPLATE_DEBUG`` to a value that differs from :setting:`DEBUG`,
include that value under the ``'debug'`` key in ``'OPTIONS'``.
Once you have defined :setting:`TEMPLATES`, you can safely remove
``ALLOWED_INCLUDE_ROOTS``, ``TEMPLATE_CONTEXT_PROCESSORS``,
``TEMPLATE_DEBUG``, ``TEMPLATE_DIRS``, ``TEMPLATE_LOADERS``, and
``TEMPLATE_STRING_IF_INVALID``.
If you are overriding some of these settings in tests, you should override the
entire :setting:`TEMPLATES` setting instead.
:mod:`django.template.loader`
=============================
.. _get_template-upgrade-django-18:
:func:`~django.template.loader.get_template` and :func:`~django.template.loader.select_template`
------------------------------------------------------------------------------------------------
In Django 1.8 :func:`~django.template.loader.get_template` and
:func:`~django.template.loader.select_template` return a backend-dependent
``Template`` instead of a :class:`django.template.Template`.
For example, if :func:`~django.template.loader.get_template` loads a template
with a :class:`~django.template.backends.django.DjangoTemplates` backend, then
it returns a ``django.template.backends.django.Template``.
``Template`` objects must provide a
:meth:`~django.template.backends.base.Template.render` method whose signature
differs slightly from the Django template language's
:meth:`~django.template.Template.render`.
Instead of::
from django.template import Context
from django.template.loader import get_template
template = get_template('hello.html')
html = template.render(Context({'name': 'world'}))
You should write::
from django.template.loader import get_template
template = get_template('hello.html')
html = template.render({'name': 'world'})
And instead of::
from django.template import RequestContext
from django.template.loader import get_template
template = get_template('hello.html')
html = template.render(RequestContext(request, {'name': 'world'}))
You should write::
from django.template.loader import get_template
template = get_template('hello.html')
html = template.render({'name': 'world'}, request)
Passing a :class:`~django.template.Context` or a
:class:`~django.template.RequestContext` is still possible when the template
is loaded by a :class:`~django.template.backends.django.DjangoTemplates`
backend but it's deprecated and won't be supported in Django 1.10.
If you're loading a template while you're rendering another template with the
Django template language and you have access to the current context, for
instance in the ``render()`` method of a template tag, you can use the current
:class:`~django.template.Engine` directly. Instead of::
from django.template.loader import get_template
template = get_template('included.html')
You can write::
template = context.template.engine.get_template('included.html')
This will load the template with the current engine without triggering the
multiple template engines machinery, which is usually the desired behavior.
Unlike previous solutions, this returns a :class:`django.template.Template`,
like :func:`~django.template.loader.get_template` used to in Django 1.7 and
earlier, avoiding all backwards-compatibility problems.
``get_template_from_string()``
------------------------------
Private API ``get_template_from_string(template_code)`` was removed in Django
1.8 because it had no way to choose an engine to compile the template.
Three alternatives are available.
If you control the project's setting, you can use one of the configured
engines::
from django.template import engines
template = engines['django'].from_string(template_code)
This returns a backend-dependent ``Template`` object.
For trivial templates that don't need context processors nor anything else,
you can create a bare-bones engine and use its ``from_string()`` method::
from django.template import Engine
template = Engine().from_string(template_code)
This returns a :class:`django.template.Template` because
:class:`~django.template.Engine` is part of the Django template language's
APIs. The multiple template engines machinery isn't involved here.
Finally, if you have access to the current context, you can use the same trick
as above::
template = context.template.engine.from_string(template_code)
``Template()``
==============
To a lesser extent, instantiating a template with ``Template(template_code)``
suffers from the same issue as ``get_template_from_string()``.
It still works when the :setting:`TEMPLATES` setting defines exactly one
:class:`~django.template.backends.django.DjangoTemplates` backend, but
pluggable applications can't control this requirement.
The last two solutions described in the previous section are recommended in
that case.

View File

@ -1269,8 +1269,8 @@ to remove usage of these features.
* The backwards compatibility shim to allow ``FormMixin.get_form()`` to be
defined with no default value for its ``form_class`` argument is removed.
* The following settings are removed, and :doc:`you must upgrade
</ref/templates/upgrading>` to the :setting:`TEMPLATES` setting:
* The following settings are removed, and you must upgrade to the
:setting:`TEMPLATES` setting:
* ``ALLOWED_INCLUDE_ROOTS``
* ``TEMPLATE_CONTEXT_PROCESSORS``

View File

@ -61,7 +61,7 @@ built-in support for the Django template language and for
:class:`~django.template.backends.jinja2.Jinja2`. It supports rendering
templates with multiple engines within the same project. Learn more about the
new features in the :doc:`topic guide </topics/templates>` and check the
:doc:`upgrade instructions </ref/templates/upgrading>` for details.
upgrade instructions in older versions of the documentation.
Security enhancements
---------------------
@ -1522,9 +1522,6 @@ Both classes provide a ``render()`` method, however, the former takes a
:class:`dict`. This change is enforced through a deprecation path for Django
templates.
Since it's easier to understand with examples, the :ref:`upgrade guide
<get_template-upgrade-django-18>` shows how to adapt affected code.
All this also applies to :func:`~django.template.loader.select_template()`.
:class:`~django.template.Template` and :class:`~django.template.Context` classes in template responses