Opened 4 years ago

Last modified 4 years ago

#14831 new New feature

Django Template Style Guide

Reported by: DrMeers Owned by: nobody
Component: Documentation Version: 1.2
Severity: Normal Keywords: template, style, format
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

It would be nice to have a standard template style that should be followed. For example, I like to indent my Django templates by two additional spaces every time I enter a new HTML or template block. The Django core templates vary greatly in regards to style and indentation. Much of the time template readability is sacrificed in favour of attempting to preserve the "appearance" of the generated HTML code.

Regardless of what is decided, it would be great to have at least some guidelines for templates added to http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style

Change History (5)

comment:1 Changed 4 years ago by gabrielhurley

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

I'm in favor of standards in general. What will probably bring this issue to a consensus most quickly would be the following:

  1. An overview of the various styles found in the current templates,
  2. A draft patch based on whatever the most common/best practice seems to be,
  3. A thread on Django Developers to let folks debate the options.

A few points that should be specified in a style guide for templates:

  • Indentation: how many spaces?
  • Placement of extends and load tags (at the top seems pretty standard).
  • Whether HTML inside a block should always be on its own line or if short blocks should be kept on one line. See the admin base_site template for examples of both.
  • Whether all code inside a block should be indented. (commonly the answer seems to be "no")

There are probably others, but this is what springs to mind so far.

Just to toss my two cents into the ring (how's that for a mixed metaphor?), here's what I think:

Even though there's no guiding document like PEP 8 for HTML, I think applying as much of PEP 8 as makes sense is going to be the simplest answer. It's an established and understood document that Python developers are accustomed to. A couple of items that would tend to apply:

  • Where whitespace will not affect rendered output, break up nested tags onto their own lines to keep from running over 80 characters.
  • Separate blocks (or other discrete groups of tags or logical sections) by blank lines.
  • Imports (i.e. load and extends) should be at the top of the file, on separate lines.
  • Proper whitespace within HTML tags. (<span class="timestamp hidden"> not <span class = " timestamp hidden" >)

I think overall readability and proper indentation of each individual template file is more important than what the HTML output looks like. I wrap my base templates with the spaceless tag though, so it matters less to me.

Use 4 spaces for indentation. (I know 2 spaces is popular for HTML among many developers, but PEP 8 recommends 4 and changing to 2 for templates doesn't offer any substantive improvement while it decreases the visual separation).

comment:2 Changed 4 years ago by ramen

I would like to see such a standards guide as well, especially regarding indentation. In addition to whether all code inside a block should be indented, there seems to be a variety of approaches to indentation around other template tags such as conditionals and loops. My preference would be to indent inside of all template tags that span multiple lines.

comment:3 Changed 4 years ago by anonymous

  • Severity set to Normal
  • Type set to New feature

comment:4 Changed 4 years ago by DrMeers

  • Easy pickings unset
  • UI/UX unset

I think much of Gabriel's suggestions here make good sense. Though:

  • I think {% load A B C %} is OK; loading in templates is simpler than importing in python since there are no relative imports, from x import y, etc.
  • I think 4-spaces is too much; in python, nesting can (and should) be avoided; in HTML, deep nesting is unavoidable. I'd therefore advocate 2-space indentation or tabs (the width of which can be configured by your editor)

I personally also indent template tags and HTML tags alike; e.g.

  <ul>
    {% for x in y %}
      <li>{{ x }}</li>
    {% endfor %}
  </ul>

(though this obviously doesn't produce terribly pretty HTML, if anyone cares. I prefer pretty templates.)

This is dangerous bikeshedding territory, but it seems sensible to have a standard within core code, and would also allow the production of django-template emacs modes, TextMate bundles, etc.

comment:5 Changed 4 years ago by DrMeers

Actually you can use "from" syntax in the load tag, can't you; in those cases it certainly makes sense to keep them on separate lines. Though perhaps that isn't what Gabriel was advocating in the first place; on re-reading he may have been simply saying it shouldn't be on the same line as {% extends %} (which of course must be at the top).

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