diff --git a/docs/ref/contrib/admin.txt b/docs/ref/contrib/admin.txt index 645cc02916d14..ceb33bc40a370 100644 --- a/docs/ref/contrib/admin.txt +++ b/docs/ref/contrib/admin.txt @@ -851,6 +851,104 @@ and ``GenericStackedInline`` and behave just like any other inline. See the :ref:`contenttypes documentation ` 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 %} + + {% 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 =====================