Paragraph on over-riding base_html can be misread as to WHAT needs to be changed...

[Pyrrhicv]

In Django 1.7 (1.6 is the same) Tutorial 2 - Section: "Customizing your project’s templates" At approximately para. 5 it reads:

Then, just edit the file and replace {{ site_header|default:_('Django administration') }} with your own site’s name as you see fit, e.g. {{ _('Polls administration') }}. We use this approach to teach you how to override templates. In an actual project, you would probably use the django.contrib.admin.AdminSite.site_header attribute to more easily make this particular customization.

I would recommend providing a little more of the code surrounding (or just provide all of the small amount of code in base_site.html) to give context to newbie tutorial followers (like me!). What happened to me and it cost me many person-hours was that I read the text as meaning that you replaced what was in the single quotes and the rest was for context. However, I finally found a post on stack overflow in a reference to another post that showed that the whole works had to be replaced. I think it may depend on the state of mind or possibly other variables (such as the 'site header default' portion of the material to be replaced that suggests to the newbies following the tutorial that that is context and not to be replaced. Bottom line: when people read this, based on what I found in the fora, it is not uncommon that they do not read it as replacing all of the code. The instant I read someone else's explanation the original text made 100% sense - but that does not help the poor noob who reads it and mis-constructs what s/he is to do.

Finally, the 'e.g. {{ _('Polls administration') }}.' is not clear to a newbie either. Replacing '{{ _('Polls administration') }}' with '{{ _('Polls administration') }}' throws an error on my CentOS 6.5/django1.7/Python3.4x install. The solution that worked for me is cut&pasted here:

{% block title %}{{ title }} | Django POLLS Site Admin {% endblock %}

Note: NO double curly brackets around "Django POLLS Site Admin" - so...I think that the 'e.g' may be deceptive too.

Just for the record my site-name line in my base_site.html for the tutorial reads:

<h1 id="site-name"><a href="{% url 'admin:index' %}">Django Polls Administration [@ mysites proj. dir]</a></h1>

...also no curly brackets around the text to be displayed.

Bottom line: the tutorial is unclear here, especially about the mysterious curly brackets we newbies are just, barely, getting used to at this point in tutorial 2!

To add clarity for us newbies, the text for this paragraph might read:

Then, just edit the file and replace the line {% block title %}{{ title }} | {{ site_title|default:_('Django admin') }}{% endblock %} with your own site’s name as you see fit, e.g.{% block title %}{{ title }} | Django Polls Administration {% endblock %}. We use this approach to teach you how to override templates. In an actual project, you would probably use the django.contrib.admin.AdminSite.site_header attribute to more easily make this particular customization.

It would be nice to know for us poor newbies WHY just replacing the text in 'site_title|default:_('Django admin') ' does not work. One would think that the text within quotes could be changed to your heart's content and the tutorial text implies that this is the case - but it does not work, at least not on my copy of django!

I hope that all of this is of some use and I am not just making a fool of myself.

Best,

Pyrrhic

[Tim Graham]

What error did you get using {{ _('Polls administration') }}? I think it's probably not important to make this text translatable which is the purpose of the curly braces and underscore and if it adds confusion it seems fine to remove to me.

I didn't include a description of why just replacing the text in 'site_title|default:_('Django admin')' does not work as I thought it could be even more confusing (the default is needed in some edge cases where the site_title variable doesn't exist in the template context). Do you think that explanation would help?

Please take a look at the attached patch and let me know if it looks okay.

[Pyrrhicv]

Dear Tim:

I just went to the base directory and retrieved a new copy of base_site.html and cut&pasted it in to my own (now working) template directory copy. I enclose that copy and I added "FOO" and "FOOBAR" so that it would be easy to see if these changes appeared in admin.

....snip....

{% extends "admin/base.html" %}

{% block title %}{{ title }} | {{ site_title|default:_('Django FOO site admin') }}{% endblock %}

{% block branding %}
<h1 id="site-name"><a href="{% url 'admin:index' %}">{{ site_header|default:_('Django FOOBAR administration') }}</a></h1>
{% endblock %}

{% block nav-global %}{% endblock %}

....end file ... snip ....

The above is what I did first when I got to this section of the tutorial and I think other newbies do so sometimes too. Of course (for reasons I do not yet understand) this does not work at all.

Frankly, at one point, very desperate, I even did a 'locate' on my machine and changed text within the single brackets on every single instance of base_site.html on my workstation, and could not get "FOO" or "FOOBAR" to appear in my otherwise functional admin screen from ANY copy of base_site.html. However, I had an additional problem, I did not realize, originally, as my template file ended up one hierarchical directory level up from where it actually belonged. So...at first, no template changes worked when I experimented with cut&paste variants (including, I think the right one) nothing .... no surprise! When I got the directory location fixed, still nothing worked as I was just trying to copy what was in the single brackets by that point (ie the text that actually is supposed to appear) as I was under the impression that my experiments had shown other things did not work. My problem was compounded by reading too many pieces of documentation written in haste that have the code or examples wrong so when stuff that is cut&pasted does not work, I start to look for other explanations. Of course, being very tired by the time I changed my directories did not help.

I note that if you substitute the material - ALL of it - including the double brace brackets etc, as the text actually suggests you should it works (even for me...now).

Personally, I find the tutorial with its embedded instructions to replace this and that often rather hard to follow. I wonder if someone should take the same text and redo the layout in a fashion more similar to the better books on coding which make things clearer. (Yes, I might be willing to contribute to such an effort), even a change as simple as stating at the beginning of the tutorial series that every piece of text in color "x" is a cut&paste or type-in piece of code.

Bottom line? At the end of the day, I think it is probably safe to say that a fix might be just to make what is getting copied clearer despite the the actual written text being pretty clear.

Apologies for all the fuss but I know others are stubbing their toes on this and everyone wants to be writing code and no one wants to write docs. <sigh>

I note that your response to this ticket was impressively fast and I do want to say that django is pretty amazing and that anyone supporting it deserves a very big thanks.

Best,

Petrus (Pyrrhic) van Bork
cell: 646-319-6545

[Tim Graham <timograham@…>]

In e949f4435fb8fb0b874cf8bb0ba9d61d423152f2:

Fixed #23587 -- Clarified admin template overriding in tutorial 2.

Thanks Petrus van Bork for the report.

[Tim Graham <timograham@…>]

In b2f7b517e52b9b6b08e47e783f8b6a949b690dbb:

[1.7.x] Fixed #23587 -- Clarified admin template overriding in tutorial 2.

Thanks Petrus van Bork for the report.

Backport of e949f4435f from master