Debian Codegraph @

docs/howto/overriding-templates.txt

raw
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.