[Django] #23535: A bit vague instructions about modifying templates in tutorial 2
Django
--------------------------------------+---------------------------------
Reporter: velis74 | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Severity: Normal | Keywords: tutorial, templates
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+---------------------------------
I'm running through tutorials @ django sprint PyConUK and I just had a bit
of a problem with the section "Customize the admin look and feel"
(https://docs.djangoproject.com/en/1.7/intro/tutorial02/).
In the tutorial, it says: "Then, just edit the file and replace ''{{
site_header }}'' with your own site’s name as you see fit."
There are two issues with this:
1. the tag in base_site.html itself is actually ''{{
site_header|default:_('Django administration') }}''
2. changing the default part (''default:_('Django administration')'')
doesn't work since the ''site_header'' variable is actually defined.
The documentation mentions the ''site_header'' variable location in the
same paragraph, but for a new user (such as myself) it is not immediately
obvious what the entire thing means.
I would like to discuss two issues regarding this:
1. The necessity of the ''default:'' specification in the template itself
(Daniele Procida's suggestion)
2. Appropriate change in the documentation where the text would be more
specific about what to change
Argumentation for issue 1:
The ''default:'' specification may not even be necessary since the
site_header variable is declared by default and automatically works.
Setting it to ''None'' or even ''del''eting it seems like a pretty stupid
idea, so I would argue that the ''default:'' spec in the template might be
redundant. I have not tested how the framework reacts to the variable not
being defined or ''None'' though.
I propose to fix this by editing the template to remove the ''default:''
specifications both for ''site_title'' and ''site_header'' variables.
Argumentation for issue 2:
I propose to change the text of this paragraph to:
Then, just edit the file and replace ''{{ site_header }}'' tag with your
own site’s name as you see fit. Note that in the template, the tag itself
also contains a ''default'' specification for when the ''site_header''
variable wouldn't be defined. Since the variable IS defined, you have to
replace the entire tag text with your own, to e.g. ''{{_('Polls
administration') }}''
'''Note:''' 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/23535>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
--------------------------------------+------------------------------------
Reporter: velis74 | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Keywords: tutorial, templates | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by timgraham):
* needs_docs: => 0
* needs_better_patch: => 0
* needs_tests: => 0
* stage: Unreviewed => Accepted
Comment:
You can use git blame to find the commit that added the `default` filter
to the template ([5ea34f3f]). It should stay, but a documentation update
for the second issue would be welcome.
--
Ticket URL: <https://code.djangoproject.com/ticket/23535#comment:1>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Keywords: tutorial, templates | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by velis74):
I created a pull request 3258.
https://github.com/django/django/pull/3258
It contains modification for docs only as proposed in the original ticket.
--
Ticket URL: <https://code.djangoproject.com/ticket/23535#comment:2>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: 1.7
Severity: Normal | Resolution: fixed
Keywords: tutorial, templates | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: new => closed
* resolution: => fixed
Comment:
In [changeset:"24aa85cea9d741fcbc288f12f59e22f1d05f79d7"]:
{{{
#!CommitTicketReference repository=""
revision="24aa85cea9d741fcbc288f12f59e22f1d05f79d7"
Fixed #23535 -- Updated tutorial to account for default filter added in
5ea34f3f86.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23535#comment:3>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: 1.7
Severity: Normal | Resolution: fixed
Keywords: tutorial, templates | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"1c1f418802503a78589171a540a4b795c5f53875"]:
{{{
#!CommitTicketReference repository=""
revision="1c1f418802503a78589171a540a4b795c5f53875"
[1.7.x] Fixed #23535 -- Updated tutorial to account for default filter
added in 5ea34f3f86.
Backport of 24aa85cea9 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23535#comment:4>