diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/deprecation.txt | 1 | ||||
| -rw-r--r-- | docs/intro/overview.txt | 4 | ||||
| -rw-r--r-- | docs/intro/tutorial02.txt | 34 | ||||
| -rw-r--r-- | docs/ref/contrib/sites.txt | 4 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 5 | ||||
| -rw-r--r-- | docs/ref/templates/api.txt | 43 | ||||
| -rw-r--r-- | docs/releases/1.7.txt | 2 | ||||
| -rw-r--r-- | docs/releases/1.8.txt | 3 | ||||
| -rw-r--r-- | docs/topics/settings.txt | 5 |
9 files changed, 67 insertions, 34 deletions
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index f3d50d3c90..5dc7b2d28c 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_DIRS`` * ``TEMPLATE_LOADERS`` * ``TEMPLATE_STRING_IF_INVALID`` diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index d1e9a458f5..f8aea47890 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -254,8 +254,8 @@ The code above loads the ``news/year_archive.html`` template. Django has a template search path, which allows you to minimize redundancy among templates. In your Django settings, you specify a list of directories to check -for templates with :setting:`TEMPLATE_DIRS`. If a template doesn't exist in the -first directory, it checks the second, and so on. +for templates with :setting:`DIRS <TEMPLATES-DIRS>`. If a template doesn't exist +in the first directory, it checks the second, and so on. Let's say the ``news/year_archive.html`` template was found. Here's what that might look like: diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index ae32a448e9..8039994f40 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -488,15 +488,32 @@ whatever user your server runs.) However, keeping your templates within the project is a good convention to follow. Open your settings file (:file:`mysite/settings.py`, remember) and add a -:setting:`TEMPLATE_DIRS` setting: +:setting:`DIRS <TEMPLATES-DIRS>` option in the :setting:`TEMPLATES` setting: .. snippet:: :filename: mysite/settings.py - TEMPLATE_DIRS = [os.path.join(BASE_DIR, 'templates')] + TEMPLATES = [ + { + 'BACKEND': 'django.template.backends.django.DjangoTemplates', + 'DIRS': [os.path.join(BASE_DIR, 'templates')], + 'APP_DIRS': True, + 'OPTIONS': { + 'context_processors': [ + 'django.template.context_processors.debug', + 'django.template.context_processors.i18n', + 'django.template.context_processors.tz', + 'django.template.context_processors.media', + 'django.template.context_processors.static', + 'django.contrib.auth.context_processors.auth', + 'django.contrib.messages.context_processors.messages', + ], + }, + }, + ] -:setting:`TEMPLATE_DIRS` is an iterable of filesystem directories to check when -loading Django templates; it's a search path. +:setting:`DIRS <TEMPLATES-DIRS>` is a list of filesystem directories to check +when loading Django templates; it's a search path. Now create a directory called ``admin`` inside ``templates``, and copy the template ``admin/base_site.html`` from within the default Django admin @@ -547,10 +564,11 @@ changes. Customizing your *application's* templates ------------------------------------------ -Astute readers will ask: But if :setting:`TEMPLATE_DIRS` was empty by default, -how was Django finding the default admin templates? The answer is that, by -default, Django automatically looks for a ``templates/`` subdirectory within -each application package, for use as a fallback (don't forget that +Astute readers will ask: But if :setting:`DIRS <TEMPLATES-DIRS>` was empty by +default, how was Django finding the default admin templates? The answer is +that, since :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` is set to ``True``, +Django automatically looks for a ``templates/`` subdirectory within each +application package, for use as a fallback (don't forget that ``django.contrib.admin`` is an application). Our poll application is not very complex and doesn't need custom admin diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index b8dc7ef9ca..da7b73caed 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -209,8 +209,8 @@ subscribing to LJWorld.com alerts." Same goes for the email's message body. Note that an even more flexible (but more heavyweight) way of doing this would be to use Django's template system. Assuming Lawrence.com and LJWorld.com have -different template directories (:setting:`TEMPLATE_DIRS`), you could simply -farm out to the template system like so:: +different template directories (:setting:`DIRS <TEMPLATES-DIRS>`), you could +simply farm out to the template system like so:: from django.core.mail import send_mail from django.template import loader, Context diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index ae387023e7..befc40cf9d 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2422,6 +2422,11 @@ TEMPLATE_DIRS Default: ``()`` (Empty tuple) +.. deprecated:: 1.8 + + Set the :setting:`DIRS <TEMPLATES-DIRS>` option of a ``DjangoTemplates`` + backend instead. + List of locations of the template source files searched by :class:`django.template.loaders.filesystem.Loader`, in search order. diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 7ab29ab276..01f3445114 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -620,21 +620,30 @@ specified as a **template directory**. Django searches for template directories in a number of places, depending on your template-loader settings (see "Loader types" below), but the most basic -way of specifying template directories is by using the :setting:`TEMPLATE_DIRS` -setting. +way of specifying template directories is by using the :setting:`DIRS +<TEMPLATES-DIRS>` option. -The TEMPLATE_DIRS setting -~~~~~~~~~~~~~~~~~~~~~~~~~ +The DIRS option +~~~~~~~~~~~~~~~ + +.. versionchanged:: 1.8 -Tell Django what your template directories are by using the -:setting:`TEMPLATE_DIRS` setting in your settings file. This should be set to a -list or tuple of strings that contain full paths to your template -directory(ies). Example:: + This value used to be defined by the ``TEMPLATE_DIRS`` setting. - TEMPLATE_DIRS = ( - "/home/html/templates/lawrence.com", - "/home/html/templates/default", - ) +Tell Django what your template directories are by using the :setting:`DIRS +<TEMPLATES-DIRS>` option in the :setting:`TEMPLATES` setting in your settings +file. This should be set to a list of strings that contain full paths to your +template directory(ies). Example:: + + TEMPLATES = [ + { + 'BACKEND': 'django.template.backends.django.DjangoTemplates', + 'DIRS': [ + '/home/html/templates/lawrence.com', + '/home/html/templates/default', + ], + }, + ] Your templates can go anywhere you want, as long as the directories and templates are readable by the Web server. They can have any extension you want, @@ -679,8 +688,8 @@ The Python API The ``dirs`` parameter was deprecated. For example, if you call ``get_template('story_detail.html')`` and have the -above :setting:`TEMPLATE_DIRS` setting, here are the files Django will look for, -in order: +above :setting:`DIRS <TEMPLATES-DIRS>` option, here are the files Django will +look for, in order: * ``/home/html/templates/lawrence.com/story_detail.html`` * ``/home/html/templates/default/story_detail.html`` @@ -718,8 +727,8 @@ To load a template that's within a subdirectory, just use a slash, like so:: get_template('news/story_detail.html') -Using the same :setting:`TEMPLATE_DIRS` setting from above, this example -``get_template()`` call will attempt to load the following templates: +Using the same :setting:`DIRS <TEMPLATES-DIRS>` option from above, this +example ``get_template()`` call will attempt to load the following templates: * ``/home/html/templates/lawrence.com/news/story_detail.html`` * ``/home/html/templates/default/news/story_detail.html`` @@ -976,7 +985,7 @@ in :ref:`settings-without-django-settings-module`. Simply import the appropriate pieces of the templating system and then, *before* you call any of the templating functions, call :func:`django.conf.settings.configure()` with any settings you wish to specify. You might want to consider setting at least -:setting:`TEMPLATE_DIRS` (if you're going to use template loaders), +:setting:`DIRS <TEMPLATES-DIRS>` (if you're going to use template loaders), :setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine) and :setting:`TEMPLATE_DEBUG`. If you plan to use the :ttag:`url` template tag, you will also need to set the :setting:`ROOT_URLCONF` setting. All available diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index 782bc8d8a9..0140f58311 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -853,7 +853,7 @@ Templates rendering of a template. * The following functions now accept a ``dirs`` parameter which is a list or - tuple to override :setting:`TEMPLATE_DIRS`: + tuple to override ``TEMPLATE_DIRS``: * :func:`django.template.loader.get_template()` * :func:`django.template.loader.select_template()` diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index 0cc074b24b..30ce6b5a60 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_DIRS`` * ``TEMPLATE_LOADERS`` * ``TEMPLATE_STRING_IF_INVALID`` @@ -1249,7 +1250,7 @@ templates through the ``context`` dict. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following functions will no longer accept a ``dirs`` parameter to override -:setting:`TEMPLATE_DIRS` in Django 2.0: +``TEMPLATE_DIRS`` in Django 2.0: * :func:`django.template.loader.get_template()` * :func:`django.template.loader.select_template()` diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt index edec6c5ad5..e84b344e53 100644 --- a/docs/topics/settings.txt +++ b/docs/topics/settings.txt @@ -13,9 +13,9 @@ A settings file is just a Python module with module-level variables. Here are a couple of example settings:: + ALLOWED_HOSTS = ['www.example.com'] DEBUG = False DEFAULT_FROM_EMAIL = 'webmaster@example.com' - TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john') .. note:: @@ -188,8 +188,7 @@ Example:: from django.conf import settings - settings.configure(DEBUG=True, TEMPLATE_DEBUG=True, - TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base')) + settings.configure(DEBUG=True, TEMPLATE_DEBUG=True) Pass ``configure()`` as many keyword arguments as you'd like, with each keyword argument representing a setting and its value. Each argument name should be all |