Code

Ticket #7943: admin_templates.diff

File admin_templates.diff, 4.3 KB (added by mwdiers, 6 years ago)

Added note about lowercasing directory name.

Line 
1Index: docs/admin.txt
2===================================================================
3--- docs/admin.txt      (revision 8154)
4+++ docs/admin.txt      (working copy)
5@@ -736,3 +736,95 @@
6         ('^basic-admin/(.*)', basic_site.root),
7         ('^advanced-admin/(.*)', advanced_site.root),
8     )
9+
10+Overriding Admin Templates
11+==========================
12+
13+It is relatively easy to override many of the templates which the admin module
14+uses to generate the various pages of an admin site. You can even override a few
15+of these templates for a specific app, or a specific model.
16+
17+Set up your projects admin template directories
18+-----------------------------------------------
19+
20+The admin template files are located in the
21+``contrib/admin/templates/admin`` directory.
22+
23+In order to override one or more of them, first create an ``admin`` directory in
24+your project's ``templates`` directory. This can be any of the directories you
25+specified in ``TEMPLATE_DIRS``.
26+
27+Within this ``admin`` directory, create sub-directories named after your app.
28+Within these app subdirectories create sub-directories named after your models.
29+Note, that the admin app will lowercase the model name when looking for the
30+directory, so make sure you name the directory in all lowercase if you are
31+going to run your app on a case-sensitive filesystem.
32+
33+To override an admin template for a specific app, copy and edit the template
34+from the ``django/contrib/admin/templates/admin`` directory, and save it
35+to one of the directories you just created.
36+
37+For example, if we wanted to add a tool to the change list view for all the
38+models in an app named ``my_app``, we would copy
39+``contrib/admin/templates/admin/change_list.html`` to the
40+``templates/admin/my_app/`` directory of our project, and make any necessary
41+changes.
42+
43+If we wanted to add a tool to the change list view for only a specific model
44+named 'Page', we would copy that same file to the
45+``templates/admin/my_app/page`` directory of our project.
46+
47+
48+Overriding vs. replacing an admin template
49+------------------------------------------
50+
51+Because of the modular design of the admin templates, it is usually neither
52+necessary nor advisable to replace an entire template. It is almost always
53+better to override only the section of the template which you need to change.
54+
55+To continue the example above, we want to add a new link next to the ``History``
56+tool for the ``Page`` model. After looking at ``change_form.html`` we determine
57+that we only need to override the ``object-tools`` block. Therefore here is our
58+new ``change_form.html`` ::
59+
60+    {% extends "admin/change_form.html" %}
61+    {% load i18n %}
62+    {% block object-tools %}
63+    {% if change %}{% if not is_popup %}
64+      <ul class="object-tools"><li><a href="history/" class="historylink">{% trans "History" %}</a></li>
65+      <li><a href="mylink/" class="historylink">My Link</a></li>
66+      {% if has_absolute_url %}<li><a href="../../../r/{{ content_type_id }}/{{ object_id }}/" class="viewsitelink">{% trans "View on site" %}</a></li>{% endif%}
67+      </ul>
68+    {% endif %}{% endif %}
69+    {% endblock %}
70+
71+And that's it! If we placed this file in the ``templates/admin/my_app``
72+directory, our link would appear on every model's change form.
73+
74+Templates which may be overridden per app or model
75+--------------------------------------------------
76+
77+Not every template in ``contrib\admin\templates\admin`` may be overridden per
78+app or per model. The following can:
79+
80+* ``change_form.html``
81+* ``change_list.html``
82+* ``delete_confirmation.html``
83+* ``object_history.html``
84+
85+For those templates that cannot be overridden in this way, you may still
86+override them for your entire project. Just place the new version in your
87+``templates/admin`` directory. This is particularly useful to create custom
88+404 and 500 pages.
89+
90+**Note:** Some of the admin templates, such as ``change_list_request.html`` are
91+used to render custom inclusion tags. These may be overridden, but in such cases
92+you are probably better off creating your own version of the tag in question and
93+giving it a different name. That way you can use it selectively.
94+
95+Root and login templates
96+------------------------
97+
98+If you wish to change the index or login templates, you are better off creating
99+your own ``AdminSite`` instance, and changing the ``index_template`` or
100+``login_template`` properties.