Ticket #7943: admin_templates.diff

File admin_templates.diff, 4.3 KB (added by mwdiers, 7 years ago)

Added note about lowercasing directory name.

  • docs/admin.txt

     
    736736        ('^basic-admin/(.*)', basic_site.root),
    737737        ('^advanced-admin/(.*)', advanced_site.root),
    738738    )
     739
     740Overriding Admin Templates
     741==========================
     742
     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.
     746
     747Set up your projects admin template directories
     748-----------------------------------------------
     749
     750The admin template files are located in the
     751``contrib/admin/templates/admin`` directory.
     752
     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``.
     756
     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.
     762
     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.
     766
     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
     771changes.
     772
     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.
     776
     777
     778Overriding vs. replacing an admin template
     779------------------------------------------
     780
     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.
     784
     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`` ::
     789
     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 %}
     800
     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.
     803
     804Templates which may be overridden per app or model
     805--------------------------------------------------
     806
     807Not every template in ``contrib\admin\templates\admin`` may be overridden per
     808app or per model. The following can:
     809
     810* ``change_form.html``
     811* ``change_list.html``
     812* ``delete_confirmation.html``
     813* ``object_history.html``
     814
     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.
     819
     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.
     824
     825Root and login templates
     826------------------------
     827
     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