diff --git a/docs/admin.txt b/docs/admin.txt index 2894b1d57c..ec30dc88c8 100644 --- a/docs/admin.txt +++ b/docs/admin.txt @@ -774,3 +774,94 @@ respectively:: ('^basic-admin/(.*)', basic_site.root), ('^advanced-admin/(.*)', advanced_site.root), ) + +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 project-level admin template directory +-------------------------------------------------- + +The admin templates 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-level ``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 could 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, and changing the ``index_template`` or +``login_template`` properties.