Ticket #7943: admin_templates.diff

File admin_templates.diff, 4.3 KB (added by Martin Diers, 10 years ago)

Added note about lowercasing directory name.

  • docs/admin.txt

    736736        ('^basic-admin/(.*)', basic_site.root),
    737737        ('^advanced-admin/(.*)', advanced_site.root),
    738738    )
     740Overriding Admin Templates
     743It is relatively easy to override many of the templates which the admin module
     744uses to generate the various pages of an admin site. You can even override a few
     745of these templates for a specific app, or a specific model.
     747Set up your projects admin template directories
     750The admin template files are located in the
     751``contrib/admin/templates/admin`` directory.
     753In order to override one or more of them, first create an ``admin`` directory in
     754your project's ``templates`` directory. This can be any of the directories you
     755specified in ``TEMPLATE_DIRS``.
     757Within this ``admin`` directory, create sub-directories named after your app.
     758Within these app subdirectories create sub-directories named after your models.
     759Note, that the admin app will lowercase the model name when looking for the
     760directory, so make sure you name the directory in all lowercase if you are
     761going to run your app on a case-sensitive filesystem.
     763To override an admin template for a specific app, copy and edit the template
     764from the ``django/contrib/admin/templates/admin`` directory, and save it
     765to one of the directories you just created.
     767For example, if we wanted to add a tool to the change list view for all the
     768models in an app named ``my_app``, we would copy
     769``contrib/admin/templates/admin/change_list.html`` to the
     770``templates/admin/my_app/`` directory of our project, and make any necessary
     773If we wanted to add a tool to the change list view for only a specific model
     774named 'Page', we would copy that same file to the
     775``templates/admin/my_app/page`` directory of our project.
     778Overriding vs. replacing an admin template
     781Because of the modular design of the admin templates, it is usually neither
     782necessary nor advisable to replace an entire template. It is almost always
     783better to override only the section of the template which you need to change.
     785To continue the example above, we want to add a new link next to the ``History``
     786tool for the ``Page`` model. After looking at ``change_form.html`` we determine
     787that we only need to override the ``object-tools`` block. Therefore here is our
     788new ``change_form.html`` ::
     790    {% extends "admin/change_form.html" %}
     791    {% load i18n %}
     792    {% block object-tools %}
     793    {% if change %}{% if not is_popup %}
     794      <ul class="object-tools"><li><a href="history/" class="historylink">{% trans "History" %}</a></li>
     795      <li><a href="mylink/" class="historylink">My Link</a></li>
     796      {% if has_absolute_url %}<li><a href="../../../r/{{ content_type_id }}/{{ object_id }}/" class="viewsitelink">{% trans "View on site" %}</a></li>{% endif%}
     797      </ul>
     798    {% endif %}{% endif %}
     799    {% endblock %}
     801And that's it! If we placed this file in the ``templates/admin/my_app``
     802directory, our link would appear on every model's change form.
     804Templates which may be overridden per app or model
     807Not every template in ``contrib\admin\templates\admin`` may be overridden per
     808app or per model. The following can:
     810* ``change_form.html``
     811* ``change_list.html``
     812* ``delete_confirmation.html``
     813* ``object_history.html``
     815For those templates that cannot be overridden in this way, you may still
     816override them for your entire project. Just place the new version in your
     817``templates/admin`` directory. This is particularly useful to create custom
     818404 and 500 pages.
     820**Note:** Some of the admin templates, such as ``change_list_request.html`` are
     821used to render custom inclusion tags. These may be overridden, but in such cases
     822you are probably better off creating your own version of the tag in question and
     823giving it a different name. That way you can use it selectively.
     825Root and login templates
     828If you wish to change the index or login templates, you are better off creating
     829your own ``AdminSite`` instance, and changing the ``index_template`` or
     830``login_template`` properties.
Back to Top