Admin docs do not contain instructions on overriding Admin templates

[Martin Diers]

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.

[Martin Diers]

Ok. There's my attempt.

[Brian Rosner]

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

[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...)

[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.

[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/options.py, 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,
            "admin/change_form.html"
        ], 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.

[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 . . .

[Martin Diers]

Added note about lowercasing directory name.

[Brian Rosner]

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.

[Jacob]

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

[Jacob]

Milestone 1.0 deleted