#23587: Paragraph on over-riding base_html can be misread as to WHAT needs to be
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.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/051.dd960e792a8d50acd12e7b9ebb0bf831%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
