Fixed #7943: added documentation on overriding admin templates. Thanks, mwdiers

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8858 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jacob Kaplan-Moss 2008-09-02 16:47:45 +00:00
parent 23f012dbfa
commit b1f5ed00cb
1 changed files with 98 additions and 0 deletions

View File

@ -851,6 +851,104 @@ and ``GenericStackedInline`` and behave just like any other inline. See the
:ref:`contenttypes documentation <ref-contrib-contenttypes>` for more specific
information.
Overriding Admin Templates
==========================
It is relatively easy to override many of the templates which the admin module
uses to generate the various pages of an admin site. You can even override a few
of these templates for a specific app, or a specific model.
Set up your projects admin template directories
-----------------------------------------------
The admin template files are located in the ``contrib/admin/templates/admin``
directory.
In order to override one or more of them, first create an ``admin`` directory in
your project's ``templates`` directory. This can be any of the directories you
specified in ``TEMPLATE_DIRS``.
Within this ``admin`` directory, create sub-directories named after your app.
Within these app subdirectories create sub-directories named after your models.
Note, that the admin app will lowercase the model name when looking for the
directory, so make sure you name the directory in all lowercase if you are going
to run your app on a case-sensitive filesystem.
To override an admin template for a specific app, copy and edit the template
from the ``django/contrib/admin/templates/admin`` directory, and save it to one
of the directories you just created.
For example, if we wanted to add a tool to the change list view for all the
models in an app named ``my_app``, we would copy
``contrib/admin/templates/admin/change_list.html`` to the
``templates/admin/my_app/`` directory of our project, and make any necessary
changes.
If we wanted to add a tool to the change list view for only a specific model
named 'Page', we would copy that same file to the
``templates/admin/my_app/page`` directory of our project.
Overriding vs. replacing an admin template
------------------------------------------
Because of the modular design of the admin templates, it is usually neither
necessary nor advisable to replace an entire template. It is almost always
better to override only the section of the template which you need to change.
To continue the example above, we want to add a new link next to the ``History``
tool for the ``Page`` model. After looking at ``change_form.html`` we determine
that we only need to override the ``object-tools`` block. Therefore here is our
new ``change_form.html`` ::
{% extends "admin/change_form.html" %}
{% load i18n %}
{% block object-tools %}
{% if change %}{% if not is_popup %}
<ul class="object-tools">
<li><a href="history/" class="historylink">{% trans "History" %}</a></li>
<li><a href="mylink/" class="historylink">My Link</a></li>
{% if has_absolute_url %}
<li><a href="../../../r/{{ content_type_id }}/{{ object_id }}/" class="viewsitelink">
{% trans "View on site" %}</a>
</li>
{% endif%}
</ul>
{% endif %}{% endif %}
{% endblock %}
And that's it! If we placed this file in the ``templates/admin/my_app``
directory, our link would appear on every model's change form.
Templates which may be overridden per app or model
--------------------------------------------------
Not every template in ``contrib\admin\templates\admin`` may be overridden per
app or per model. The following can:
* ``change_form.html``
* ``change_list.html``
* ``delete_confirmation.html``
* ``object_history.html``
For those templates that cannot be overridden in this way, you may still
override them for your entire project. Just place the new version in your
``templates/admin`` directory. This is particularly useful to create custom 404
and 500 pages.
.. note::
Some of the admin templates, such as ``change_list_request.html`` are used
to render custom inclusion tags. These may be overridden, but in such cases
you are probably better off creating your own version of the tag in question
and giving it a different name. That way you can use it selectively.
Root and login templates
------------------------
If you wish to change the index or login templates, you are better off creating
your own ``AdminSite`` instance (see below), and changing the ``index_template``
or ``login_template`` properties.
``AdminSite`` objects
=====================