Removed settings.TEMPLATES upgrade guide.
This commit is contained in:
Tim Graham
parent
6192bffb13
commit
397b3705c5
|
|
@ -14,7 +14,6 @@ material, see :doc:`/topics/templates` topic guide.
|
|||
language
|
||||
builtins
|
||||
api
|
||||
upgrading
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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``
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue