Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#23535 closed Cleanup/optimization (fixed)

Clarify presence of default filter in tutorial 2

Reported by: Jure Erznožnik Owned by: nobody
Component: Documentation Version: 1.7
Severity: Normal Keywords: tutorial, templates
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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

Change History (4)

comment:1 Changed 4 years ago by Tim Graham

Summary: A bit vague instructions about modifying templates in tutorial 2Clarify presence of default filter in tutorial 2
Triage Stage: UnreviewedAccepted

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.

comment:2 Changed 4 years ago by Jure Erznožnik

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.

comment:3 Changed 4 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: newclosed

In 24aa85cea9d741fcbc288f12f59e22f1d05f79d7:

Fixed #23535 -- Updated tutorial to account for default filter added in 5ea34f3f86.

comment:4 Changed 4 years ago by Tim Graham <timograham@…>

In 1c1f418802503a78589171a540a4b795c5f53875:

[1.7.x] Fixed #23535 -- Updated tutorial to account for default filter added in 5ea34f3f86.

Backport of 24aa85cea9 from master

Note: See TracTickets for help on using tickets.
Back to Top