Opened 4 years ago

Closed 4 years ago

#32521 closed Cleanup/optimization (invalid)

Possible documentation error re. template directories

Reported by: Mike Slinn Owned by: nobody
Component: Documentation Version: 3.1
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The docs say "Since you’re overriding templates located outside of one of your project’s apps, it’s more common to use the first method and put template overrides in a project’s templates folder."

It is unclear what "the first method" might be. Earlier in the page there was no mention of an enumeration of options.

I believe I know what the page is trying to communicate, that there are two places to put templates:

1) Per app (template subdirectory within each app directory)

2) Per project (top-level /templates directory)

I believe that the first place shown above is "the first method". It would be less confusing if this was spelled out better. The rest of the page continues the confusion. Apparently per-app templates are preferred, but there is not a single example of this, nor a directory layout image, and instead all the detail goes to the per-project option.

Even the section entitled Overriding from an app’s template directory does not discuss per-app templates, and again shows a per-project template directory.

A newbie like me is left scratching his head.

Change History (1)

comment:1 by Mariusz Felisiak, 4 years ago

Resolution: invalid
Status: newclosed
Type: UncategorizedCleanup/optimization

This page describes how to override templates in three ways:

  • "Overriding from the project’s templates directory"
  • "Overriding from an app’s template directory"
  • "Extending an overridden template"

It is unclear what "the first method" might be. Earlier in the page there was no mention of an enumeration of options.

TBH I cannot imagine how we could be clearer. "... it’s more common to use the first method and put template overrides in a project’s templates folder." so the first method is to "...put template overrides in a project’s templates folder..." i.e. the first way described on this page.

Apparently per-app templates are preferred, but there is not a single example of this, nor a directory layout image, and instead all the detail goes to the per-project option.

That's not true, this is described in the Overriding from an app’s template directory section, with an example of directory structure:

"If you want to put the template overrides in an app called myapp and the templates to override are named blog/list.html and blog/post.html, then your directory structure will look like:"

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