Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Initial admin template docs. Needs more work.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8182 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 9d3c921857145b2ab4d3b0c25ca75c23e397dbdc 1 parent ff486b9
Brian Rosner authored August 01, 2008

Showing 1 changed file with 91 additions and 0 deletions. Show diff stats Hide diff stats

  1. 91  docs/admin.txt
91  docs/admin.txt
@@ -774,3 +774,94 @@ respectively::
774 774
         ('^basic-admin/(.*)', basic_site.root),
775 775
         ('^advanced-admin/(.*)', advanced_site.root),
776 776
     )
  777
+
  778
+Overriding Admin Templates
  779
+==========================
  780
+
  781
+It is relatively easy to override many of the templates which the admin module
  782
+uses to generate the various pages of an admin site. You can even override a
  783
+few of these templates for a specific app, or a specific model.
  784
+
  785
+Set up your project-level admin template directory
  786
+--------------------------------------------------
  787
+
  788
+The admin templates are located in the ``contrib/admin/templates/admin``
  789
+directory.
  790
+
  791
+In order to override one or more of them, first create an ``admin`` directory
  792
+in your project-level ``templates`` directory. This can be any of the
  793
+directories you specified in ``TEMPLATE_DIRS``.
  794
+
  795
+Within this ``admin`` directory, create sub-directories named after your app.
  796
+Within these app subdirectories create sub-directories named after your models.
  797
+Note, that the admin app will lowercase the model name when looking for the
  798
+directory, so make sure you name the directory in all lowercase if you are
  799
+going to run your app on a case-sensitive filesystem.
  800
+
  801
+To override an admin template for a specific app, copy and edit the template
  802
+from the ``django/contrib/admin/templates/admin`` directory, and save it
  803
+to one of the directories you just created.
  804
+
  805
+For example, if we wanted to add a tool to the change list view for all the
  806
+models in an app named ``my_app``, we would copy
  807
+``contrib/admin/templates/admin/change_list.html`` to the
  808
+``templates/admin/my_app/`` directory of our project, and make any necessary
  809
+changes.
  810
+
  811
+If we wanted to add a tool to the change list view for only a specific model
  812
+named 'Page', we could copy that same file to the
  813
+``templates/admin/my_app/page`` directory of our project.
  814
+
  815
+Overriding vs. replacing an admin template
  816
+------------------------------------------
  817
+
  818
+Because of the modular design of the admin templates, it is usually neither
  819
+necessary nor advisable to replace an entire template. It is almost always
  820
+better to override only the section of the template which you need to change.
  821
+
  822
+To continue the example above, we want to add a new link next to the ``History``
  823
+tool for the ``Page`` model. After looking at ``change_form.html`` we determine
  824
+that we only need to override the ``object-tools`` block. Therefore here is our
  825
+new ``change_form.html`` ::
  826
+
  827
+    {% extends "admin/change_form.html" %}
  828
+    {% load i18n %}
  829
+    {% block object-tools %}
  830
+    {% if change %}{% if not is_popup %}
  831
+      <ul class="object-tools"><li><a href="history/" class="historylink">{% trans "History" %}</a></li>
  832
+      <li><a href="mylink/" class="historylink">My Link</a></li>
  833
+      {% if has_absolute_url %}<li><a href="../../../r/{{ content_type_id }}/{{ object_id }}/" class="viewsitelink">{% trans "View on site" %}</a></li>{% endif%}
  834
+      </ul>
  835
+    {% endif %}{% endif %}
  836
+    {% endblock %}
  837
+
  838
+And that's it! If we placed this file in the ``templates/admin/my_app``
  839
+directory, our link would appear on every model's change form.
  840
+
  841
+Templates which may be overridden per app or model
  842
+--------------------------------------------------
  843
+
  844
+Not every template in ``contrib\admin\templates\admin`` may be overridden per
  845
+app or per model. The following can:
  846
+
  847
+* ``change_form.html``
  848
+* ``change_list.html``
  849
+* ``delete_confirmation.html``
  850
+* ``object_history.html``
  851
+
  852
+For those templates that cannot be overridden in this way, you may still
  853
+override them for your entire project. Just place the new version in your
  854
+``templates/admin`` directory. This is particularly useful to create custom
  855
+404 and 500 pages.
  856
+
  857
+**Note:** Some of the admin templates, such as ``change_list_request.html`` are
  858
+used to render custom inclusion tags. These may be overridden, but in such cases
  859
+you are probably better off creating your own version of the tag in question and
  860
+giving it a different name. That way you can use it selectively.
  861
+
  862
+Root and login templates
  863
+------------------------
  864
+
  865
+If you wish to change the index or login templates, you are better off creating
  866
+your own ``AdminSite`` instance, and changing the ``index_template`` or
  867
+``login_template`` properties.

0 notes on commit 9d3c921

Please sign in to comment.
Something went wrong with that request. Please try again.