{"title":"Upgrading templates to Django 1.8","version":"1.9","locale":"en","docname":"ref/templates/upgrading","url":"/en/1.9/ref/templates/upgrading/","canonical":"https://djangodocs.dev/en/1.9/ref/templates/upgrading/","summary":"Django’s template system was overhauled in Django 1.8 when it gained support for multiple template engines. This document complements the release notes with…","html":"

Upgrading templates to Django 1.8Link to this heading#

\n

Django’s template system was overhauled in Django 1.8 when it gained support\nfor multiple template engines. This document complements the release\nnotes with detailed upgrade instructions on some topics.

\n
\n

The TEMPLATES settingsLink to this heading#

\n

A new setting was introduced in Django 1.8: TEMPLATES. All existing\ntemplate-related settings were deprecated.

\n

During the deprecation period, Django will create a backwards-compatible\nTEMPLATES based on the TEMPLATE_* settings if you don’t define\nit yourself.

\n

Here’s how to define TEMPLATES in your settings module.

\n

If you’re using the default value of TEMPLATE_LOADERS, that is, if it\nisn’t defined in your settings file or if it’s set to:

\n
Code
['django.template.loaders.filesystem.Loader',\n 'django.template.loaders.app_directories.Loader']\n
\n

then you should define TEMPLATES as follows:

\n
Code
TEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [\n            # insert your TEMPLATE_DIRS here\n        ],\n        'APP_DIRS': True,\n        'OPTIONS': {\n            'context_processors': [\n                # Insert your TEMPLATE_CONTEXT_PROCESSORS here or use this\n                # list if you haven't customized them:\n                'django.contrib.auth.context_processors.auth',\n                'django.template.context_processors.debug',\n                'django.template.context_processors.i18n',\n                'django.template.context_processors.media',\n                'django.template.context_processors.static',\n                'django.template.context_processors.tz',\n                'django.contrib.messages.context_processors.messages',\n            ],\n        },\n    },\n]\n
\n

If you aren’t using the default value of TEMPLATE_LOADERS, then you should\ndefine TEMPLATES as follows:

\n
Code
TEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [\n            # insert your TEMPLATE_DIRS here\n        ],\n        'OPTIONS': {\n            'context_processors': [\n                # Insert your TEMPLATE_CONTEXT_PROCESSORS here or use this\n                # list if you haven't customized them:\n                'django.contrib.auth.context_processors.auth',\n                'django.template.context_processors.debug',\n                'django.template.context_processors.i18n',\n                'django.template.context_processors.media',\n                'django.template.context_processors.static',\n                'django.template.context_processors.tz',\n                'django.contrib.messages.context_processors.messages',\n            ],\n            'loaders': [\n                # insert your TEMPLATE_LOADERS here\n            ]\n        },\n    },\n]\n
\n

Furthermore you should replace django.core.context_processors with\ndjango.template.context_processors in the names of context processors.

\n

If your settings module defines ALLOWED_INCLUDE_ROOTS or\nTEMPLATE_STRING_IF_INVALID, include their values under the\n'allowed_include_roots' and 'string_if_invalid' keys in the\n'OPTIONS' dictionary.

\n

If it sets TEMPLATE_DEBUG to a value that differs from DEBUG,\ninclude that value under the 'debug' key in 'OPTIONS'.

\n

Once you have defined TEMPLATES, you can safely remove\nALLOWED_INCLUDE_ROOTS, TEMPLATE_CONTEXT_PROCESSORS,\nTEMPLATE_DEBUG, TEMPLATE_DIRS, TEMPLATE_LOADERS, and\nTEMPLATE_STRING_IF_INVALID.

\n

If you are overriding some of these settings in tests, you should override the\nentire TEMPLATES setting instead.

\n
\n
\n

django.template.loaderLink to this heading#

\n
\n

get_template() and select_template()Link to this heading#

\n

In Django 1.8 get_template() and\nselect_template() return a backend-dependent\nTemplate instead of a django.template.Template.

\n

For example, if get_template() loads a template\nwith a DjangoTemplates backend, then\nit returns a django.template.backends.django.Template.

\n

Template objects must provide a\nrender() method whose signature\ndiffers slightly from the Django template language’s\nrender().

\n

Instead of:

\n
Code
from django.template import Context\nfrom django.template.loader import get_template\n\ntemplate = get_template('hello.html')\nhtml = template.render(Context({'name': 'world'}))\n
\n

You should write:

\n
Code
from django.template.loader import get_template\n\ntemplate = get_template('hello.html')\nhtml = template.render({'name': 'world'})\n
\n

And instead of:

\n
Code
from django.template import RequestContext\nfrom django.template.loader import get_template\n\ntemplate = get_template('hello.html')\nhtml = template.render(RequestContext(request, {'name': 'world'}))\n
\n

You should write:

\n
Code
from django.template.loader import get_template\n\ntemplate = get_template('hello.html')\nhtml = template.render({'name': 'world'}, request)\n
\n

Passing a Context or a\nRequestContext is still possible when the template\nis loaded by a DjangoTemplates\nbackend but it’s deprecated and won’t be supported in Django 1.10.

\n

If you’re loading a template while you’re rendering another template with the\nDjango template language and you have access to the current context, for\ninstance in the render() method of a template tag, you can use the current\nEngine directly. Instead of:

\n
Code
from django.template.loader import get_template\ntemplate = get_template('included.html')\n
\n

You can write:

\n
Code
template = context.template.engine.get_template('included.html')\n
\n

This will load the template with the current engine without triggering the\nmultiple template engines machinery, which is usually the desired behavior.\nUnlike previous solutions, this returns a django.template.Template,\nlike get_template() used to in Django 1.7 and\nearlier, avoiding all backwards-compatibility problems.

\n
\n
\n

get_template_from_string()Link to this heading#

\n

Private API get_template_from_string(template_code) was removed in Django\n1.8 because it had no way to choose an engine to compile the template.

\n

Three alternatives are available.

\n

If you control the project’s setting, you can use one of the configured\nengines:

\n
Code
from django.template import engines\n\ntemplate = engines['django'].from_string(template_code)\n
\n

This returns a backend-dependent Template object.

\n

For trivial templates that don’t need context processors nor anything else,\nyou can create a bare-bones engine and use its from_string() method:

\n
Code
from django.template import Engine\n\ntemplate = Engine().from_string(template_code)\n
\n

This returns a django.template.Template because\nEngine is part of the Django template language’s\nAPIs. The multiple template engines machinery isn’t involved here.

\n

Finally, if you have access to the current context, you can use the same trick\nas above:

\n
Code
template = context.template.engine.from_string(template_code)\n
\n
\n
\n
\n

Template()Link to this heading#

\n

To a lesser extent, instantiating a template with Template(template_code)\nsuffers from the same issue as get_template_from_string().

\n

It still works when the TEMPLATES setting defines exactly one\nDjangoTemplates backend, but\npluggable applications can’t control this requirement.

\n

The last two solutions described in the previous section are recommended in\nthat case.

\n
","rootId":"upgrading-templates-to-django-1-8","toc":[{"title":"The TEMPLATES settings","anchor":"the-templates-settings","children":[]},{"title":"django.template.loader","anchor":"django-template-loader","children":[{"title":"get_template() and select_template()","anchor":"get-template-and-select-template","children":[]},{"title":"get_template_from_string()","anchor":"get-template-from-string","children":[]}]},{"title":"Template()","anchor":"template","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API Reference","url":"/en/1.9/ref/"},{"docname":"ref/templates/index","title":"Templates","url":"/en/1.9/ref/templates/"}],"prev":{"docname":"ref/templates/api","title":"The Django template language: for Python programmers","url":"/en/1.9/ref/templates/api/"},"next":{"docname":"ref/template-response","title":"TemplateResponse and SimpleTemplateResponse","url":"/en/1.9/ref/template-response/"},"formats":{"html":"/en/1.9/ref/templates/upgrading/","markdown":"/en/1.9/ref/templates/upgrading.md","json":"/en/1.9/ref/templates/upgrading.json"},"source":"https://github.com/django/django/blob/stable/1.9.x/docs/ref/templates/upgrading.txt","official":"https://docs.djangoproject.com/en/1.9/ref/templates/upgrading/","inVersions":["1.11","1.10","1.9","1.8"],"inLocales":["en","fr","ja","id","pt-br","es"]}