From 397b3705c5f762b359cdb494f9447c8a60685adf Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Tue, 17 Jan 2017 10:12:56 -0500 Subject: [PATCH] Removed settings.TEMPLATES upgrade guide. --- docs/ref/templates/index.txt | 1 - docs/ref/templates/upgrading.txt | 217 ------------------------------- docs/releases/1.10.txt | 4 +- docs/releases/1.8.txt | 5 +- 4 files changed, 3 insertions(+), 224 deletions(-) delete mode 100644 docs/ref/templates/upgrading.txt diff --git a/docs/ref/templates/index.txt b/docs/ref/templates/index.txt index e5730488c1..efc97494ae 100644 --- a/docs/ref/templates/index.txt +++ b/docs/ref/templates/index.txt @@ -14,7 +14,6 @@ material, see :doc:`/topics/templates` topic guide. language builtins api - upgrading .. seealso:: diff --git a/docs/ref/templates/upgrading.txt b/docs/ref/templates/upgrading.txt deleted file mode 100644 index de2c6558ff..0000000000 --- a/docs/ref/templates/upgrading.txt +++ /dev/null @@ -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 ` 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. diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt index adca25e0ac..a84912941a 100644 --- a/docs/releases/1.10.txt +++ b/docs/releases/1.10.txt @@ -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 - ` 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`` diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index 578f53a5b4..3e5778417b 100644 --- a/docs/releases/1.8.txt +++ b/docs/releases/1.8.txt @@ -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 ` and check the -:doc:`upgrade instructions ` 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 -` 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