Opened 8 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: mwdiers Owned by: brosner
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 mwdiers 8 years ago.
Added note about lowercasing directory name.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 8 years ago by mwdiers

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

Ok. There's my attempt.

comment:2 Changed 8 years ago by mwdiers

  • Has patch set

comment:3 Changed 8 years ago by brosner

  • Owner changed from nobody to brosner
  • Status changed from new to assigned
  • Triage Stage changed from Unreviewed to Ready for checkin

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

comment:4 Changed 8 years ago by juri

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 8 years ago by mwdiers

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 8 years ago by juri

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 8 years ago by mwdiers

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 8 years ago by mwdiers

Added note about lowercasing directory name.

comment:8 Changed 8 years ago by brosner

  • milestone set to 1.0
  • Triage Stage changed from Ready for checkin to Accepted

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 set to fixed
  • Status changed from assigned to closed

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

comment:10 Changed 5 years ago by jacob

  • milestone 1.0 deleted

Milestone 1.0 deleted

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