[Django] #23587: Paragraph on over-riding base_html can be misread as to WHAT needs to be changed...
Django
changed...
-------------------------------+---------------------------------------
Reporter: Pyrrhicv | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.7
Severity: Normal | Keywords: base_site.html tutorial 2
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+---------------------------------------
In Django 1.7 (1.6 is the same) Tutorial 2 - Section: "Customizing your
project’s templates" At approximately para. 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
--
Ticket URL: <https://code.djangoproject.com/ticket/23587>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
changed...
Reporter: Pyrrhicv | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.7
Keywords: base_site.html | Triage Stage:
tutorial 2 | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Pyrrhicv):
* needs_better_patch: => 0
* needs_tests: => 0
* needs_docs: => 0
Old description:
New description:
In Django 1.7 (1.6 is the same) Tutorial 2 - Section: "Customizing your
project’s templates" At approximately para. #5it reads:
Best,
Pyrrhic
--
--
Ticket URL: <https://code.djangoproject.com/ticket/23587#comment:1>
Django
changed...
Reporter: Pyrrhicv | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.7
Keywords: base_site.html | Triage Stage:
tutorial 2 | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Description changed by Pyrrhicv:
Old description:
> In Django 1.7 (1.6 is the same) Tutorial 2 - Section: "Customizing your
> project’s templates" At approximately para. #5it reads:
New description:
In Django 1.7 (1.6 is the same) Tutorial 2 - Section: "Customizing your
project’s templates" At approximately para. 5 it reads:
Best,
Pyrrhic
--
--
Ticket URL: <https://code.djangoproject.com/ticket/23587#comment:2>
Django
changed...
Reporter: Pyrrhicv | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.7
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: base_site.html | Needs documentation: 0
tutorial 2 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
Changes (by timgraham):
* has_patch: 0 => 1
* type: Uncategorized => Cleanup/optimization
* stage: Unreviewed => Accepted
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/23587#comment:3>
Django
changed...
Reporter: Pyrrhicv | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.7
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: base_site.html | Needs documentation: 0
tutorial 2 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
Comment (by 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
--
Ticket URL: <https://code.djangoproject.com/ticket/23587#comment:4>
Django
changed...
Reporter: Pyrrhicv | Owner: nobody
Type: | Status: closed
Cleanup/optimization | Version: 1.7
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Accepted
Keywords: base_site.html | Needs documentation: 0
tutorial 2 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
* status: new => closed
* resolution: => fixed
Comment:
In [changeset:"e949f4435fb8fb0b874cf8bb0ba9d61d423152f2"]:
{{{
#!CommitTicketReference repository=""
revision="e949f4435fb8fb0b874cf8bb0ba9d61d423152f2"
Fixed #23587 -- Clarified admin template overriding in tutorial 2.
Thanks Petrus van Bork for the report.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23587#comment:5>
Django
changed...
Reporter: Pyrrhicv | Owner: nobody
Type: | Status: closed
Cleanup/optimization | Version: 1.7
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Accepted
Keywords: base_site.html | Needs documentation: 0
tutorial 2 | Patch needs improvement: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"b2f7b517e52b9b6b08e47e783f8b6a949b690dbb"]:
{{{
#!CommitTicketReference repository=""
revision="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
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23587#comment:6>