| 1 |
========================= |
| 2 |
How to override templates |
| 3 |
========================= |
| 4 |
|
| 5 |
In your project, you might want to override a template in another Django |
| 6 |
application, whether it be a third-party application or a contrib application |
| 7 |
such as ``django.contrib.admin``. You can either put template overrides in your |
| 8 |
project's templates directory or in an application's templates directory. |
| 9 |
|
| 10 |
If you have app and project templates directories that both contain overrides, |
| 11 |
the default Django template loader will try to load the template from the |
| 12 |
project-level directory first. In other words, :setting:`DIRS <TEMPLATES-DIRS>` |
| 13 |
is searched before :setting:`APP_DIRS <TEMPLATES-APP_DIRS>`. |
| 14 |
|
| 15 |
.. seealso:: |
| 16 |
|
| 17 |
Read :ref:`overriding-built-in-widget-templates` if you're looking to |
| 18 |
do that. |
| 19 |
|
| 20 |
Overriding from the project's templates directory |
| 21 |
================================================= |
| 22 |
|
| 23 |
First, we'll explore overriding templates by creating replacement templates in |
| 24 |
your project's templates directory. |
| 25 |
|
| 26 |
Let's say you're trying to override the templates for a third-party application |
| 27 |
called ``blog``, which provides the templates ``blog/post.html`` and |
| 28 |
``blog/list.html``. The relevant settings for your project would look like:: |
| 29 |
|
| 30 |
from pathlib import Path |
| 31 |
|
| 32 |
BASE_DIR = Path(__file__).resolve().parent.parent |
| 33 |
|
| 34 |
INSTALLED_APPS = [ |
| 35 |
..., |
| 36 |
"blog", |
| 37 |
..., |
| 38 |
] |
| 39 |
|
| 40 |
TEMPLATES = [ |
| 41 |
{ |
| 42 |
"BACKEND": "django.template.backends.django.DjangoTemplates", |
| 43 |
"DIRS": [BASE_DIR / "templates"], |
| 44 |
"APP_DIRS": True, |
| 45 |
# ... |
| 46 |
}, |
| 47 |
] |
| 48 |
|
| 49 |
The :setting:`TEMPLATES` setting and ``BASE_DIR`` will already exist if you |
| 50 |
created your project using the default project template. The setting that needs |
| 51 |
to be modified is :setting:`DIRS<TEMPLATES-DIRS>`. |
| 52 |
|
| 53 |
These settings assume you have a ``templates`` directory in the root of your |
| 54 |
project. To override the templates for the ``blog`` app, create a folder |
| 55 |
in the ``templates`` directory, and add the template files to that folder: |
| 56 |
|
| 57 |
.. code-block:: none |
| 58 |
|
| 59 |
templates/ |
| 60 |
blog/ |
| 61 |
list.html |
| 62 |
post.html |
| 63 |
|
| 64 |
The template loader first looks for templates in the ``DIRS`` directory. When |
| 65 |
the views in the ``blog`` app ask for the ``blog/post.html`` and |
| 66 |
``blog/list.html`` templates, the loader will return the files you just created. |
| 67 |
|
| 68 |
Overriding from an app's template directory |
| 69 |
=========================================== |
| 70 |
|
| 71 |
Since you're overriding templates located outside of one of your project's |
| 72 |
apps, it's more common to use the first method and put template overrides in a |
| 73 |
project's templates folder. If you prefer, however, it's also possible to put |
| 74 |
the overrides in an app's template directory. |
| 75 |
|
| 76 |
First, make sure your template settings are checking inside app directories:: |
| 77 |
|
| 78 |
TEMPLATES = [ |
| 79 |
{ |
| 80 |
# ... |
| 81 |
"APP_DIRS": True, |
| 82 |
# ... |
| 83 |
}, |
| 84 |
] |
| 85 |
|
| 86 |
If you want to put the template overrides in an app called ``myapp`` and the |
| 87 |
templates to override are named ``blog/list.html`` and ``blog/post.html``, |
| 88 |
then your directory structure will look like: |
| 89 |
|
| 90 |
.. code-block:: none |
| 91 |
|
| 92 |
myapp/ |
| 93 |
templates/ |
| 94 |
blog/ |
| 95 |
list.html |
| 96 |
post.html |
| 97 |
|
| 98 |
With :setting:`APP_DIRS<TEMPLATES-APP_DIRS>` set to ``True``, the template |
| 99 |
loader will look in the app's templates directory and find the templates. |
| 100 |
|
| 101 |
.. _extending_an_overridden_template: |
| 102 |
|
| 103 |
Extending an overridden template |
| 104 |
================================ |
| 105 |
|
| 106 |
With your template loaders configured, you can extend a template using the |
| 107 |
:ttag:`{% extends %}<extends>` template tag whilst at the same time overriding |
| 108 |
it. This can allow you to make small customizations without needing to |
| 109 |
reimplement the entire template. |
| 110 |
|
| 111 |
For example, you can use this technique to add a custom logo to the |
| 112 |
``admin/base_site.html`` template: |
| 113 |
|
| 114 |
.. code-block:: html+django |
| 115 |
:caption: ``templates/admin/base_site.html`` |
| 116 |
|
| 117 |
{% extends "admin/base_site.html" %} |
| 118 |
|
| 119 |
{% block branding %} |
| 120 |
<img src="link/to/logo.png" alt="logo"> |
| 121 |
{{ block.super }} |
| 122 |
{% endblock %} |
| 123 |
|
| 124 |
Key points to note: |
| 125 |
|
| 126 |
* The example creates a file at ``templates/admin/base_site.html`` that uses |
| 127 |
the configured project-level ``templates`` directory to override |
| 128 |
``admin/base_site.html``. |
| 129 |
* The new template extends ``admin/base_site.html``, which is the same template |
| 130 |
as is being overridden. |
| 131 |
* The template replaces just the ``branding`` block, adding a custom logo, and |
| 132 |
using ``block.super`` to retain the prior content. |
| 133 |
* The rest of the template is inherited unchanged from |
| 134 |
``admin/base_site.html``. |
| 135 |
|
| 136 |
This technique works because the template loader does not consider the already |
| 137 |
loaded override template (at ``templates/admin/base_site.html``) when |
| 138 |
resolving the ``extends`` tag. Combined with ``block.super`` it is a powerful |
| 139 |
technique to make small customizations. |