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 %} +