Opened 9 years ago

Closed 8 years ago

Last modified 5 years ago

#7943 closed (fixed)

Admin docs do not contain instructions on overriding Admin templates

Reported by: Martin Diers Owned by: Brian Rosner
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:


Though there is cursory information on this subject in the wiki, the admin docs contain nothing about overriding admin templates. In particular, there is no mention of the "magic" of adding an admin/APP_NAME/MODEL_NAME tree inside a project's templates folder, and how admin templates may be overridden at the app or model level.

Attachments (1)

admin_templates.diff (4.3 KB) - added by Martin Diers 9 years ago.
Added note about lowercasing directory name.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 9 years ago by Martin Diers

Ok. There's my attempt.

comment:2 Changed 9 years ago by Martin Diers

Has patch: set

comment:3 Changed 9 years ago by Brian Rosner

Owner: changed from nobody to Brian Rosner
Status: newassigned
Triage Stage: UnreviewedReady for checkin

This looks good. I'll run over it in more detail later, marking for RFC.

comment:4 Changed 9 years ago by Juri Pakaste

Two of issues with the patch (having just managed to add a button next to History in change_form.html):

  • The example should include {% load i18n %}
  • There should be a mention of the fact that the model name will be lowercased when looking for the templates (I now realize this is consistent with how other bits of Django work, but it wasn't quite obvious when I was wondering why it wasn't showing my HELLO WORLD message...)

comment:5 Changed 9 years ago by Martin Diers

I updated the example to include {% load i18n %}

However, I don't know what you mean by "the model name will be lowercased when looking for templates". The directory named after the model? If so, you are incorrect. The directory must be named after your model exactly, caps included.

comment:6 Changed 9 years ago by Juri Pakaste

The directory named after the model, yes. At least on SVN rev 8154, if I have a model named FooOverview in application fooapp, templates/admin/fooapp/foooverview/change_form.html is used by admin, templates/admin/fooapp/FooOverview/change_form.html is not.

See also ModelAdmin.render_change_form in django/contrib/admin/, line 466 (revision 8154):

        return render_to_response(self.change_form_template or [
            "admin/%s/%s/change_form.html" % (app_label, opts.object_name.lower()),
            "admin/%s/change_form.html" % app_label,
        ], context, context_instance=template.RequestContext(request))

That lower() call on the second line lowercases the model name.

I'm no expert on this and can be persuaded that I'm wrong, but that's the behaviour I've observed and the line I (after inserting debug outputs) believe causes it.

comment:7 Changed 9 years ago by Martin Diers

My bad.

I'm running on OS X with a case insensitive volume (the default), so of course I didn't notice this before. Correcting docs now . . .

Changed 9 years ago by Martin Diers

Attachment: admin_templates.diff added

Added note about lowercasing directory name.

comment:8 Changed 9 years ago by Brian Rosner

milestone: 1.0
Triage Stage: Ready for checkinAccepted

Bumping back to Accepted for now. After reading this in detail I am wanting to do a bit of refactoring of the template related bits in the admin docs. This is an excellent jump start, but all the available overrides/context needs to be noted at the right levels in the docs as well as the overriding via the template loader as described in the patch.

comment:9 Changed 8 years ago by Jacob

Resolution: fixed
Status: assignedclosed

(In [8858]) Fixed #7943: added documentation on overriding admin templates. Thanks, mwdiers

comment:10 Changed 5 years ago by Jacob

milestone: 1.0

Milestone 1.0 deleted

Note: See TracTickets for help on using tickets.
Back to Top