Django template standards

[anselmbradford]

Some prominent projects at the bureau use the Jinja2 templating awesome_͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇sauce. Maybe it's arguably not a front-end thing, but front-ends do work on it. There are some coding style areas where there's ambiguity that would be helpful to standardize. I thought I'd just jot down some areas for discussion:

Nesting jinja markup

Should nesting be indented for easier reading of jinja:

 <div>
    {%- if cond1 %}
        <ul>
        {%- if cond2 %}
            {%- for item in items %}
                <li>
                    {%- if cond3 %}
                        <p>

Or to preserve HTML nesting output:

 <div>
    {%- if cond1 %}
    <ul>
    {%- if cond2 %}
       {%- for item in items %}
       <li>
           {%- if cond3 %}
           <p>

Importing templates

Should templates be imported at the top of the file, or just above where they are used? Note that some templates are only conditionally included, so their implementation appears in if blocks.

Spacing, etc

Should filters be spaced, var | length, or not var|length.

Should parentheses be spaced, macro.render(m), or not macro.render( m ).

[Scotchester]

Before getting into the meat of the issue, what's the deal with that character between "awesome" and "sauce"?

[KimberlyMunoz]

I think that most projects have a bias towards making things easier to read for the developers working on the project. When we stack classes, it doesn't always look nice and neat in the browser, but it makes our jobs easier to do.

With that in mind, we should probably make the standard to nest for easier reading.

We probably shouldn't set a standard for importing templates if we're going to have pretty consistent exceptions. Right now, informally, I see folks putting things that will be called multiple times at the top of the page and putting things that are only used once just above where they are used. Switching to just one doesn't actually makes our jobs easier. I think we should have a standard if it makes sense and makes our jobs easier, not just to have a standard in these edge cases.

I really dislike how JavaScript linter wants everything so spaced out, so I personally don't want to force a spacing standard on jinja. I'll defer to folks who have stronger opinions on this.

[ascott1]

:+1: I like this idea. Does cfgov-refresh currently follow a pretty standard set of rules?

[Scotchester]

On nesting/indentation:

I think there's a third/middle path that I find works really well for me, which is to try to keep the HTML output "correct" when possible, but achieve this through decoupling, to a degree, the Jinja indentation and the HTML indentation. With a Jinja syntax highlighting package for your text editor, I don't find it hard to maintain two separate indentation structures in the same file.

For example, in the second example given above, I'd deindent the first JInja command. That one little step keeps the Jinja indentation internally consistent, and outputs HTML with consistent indentation.

<div>
{%- if cond1 %}
    <ul>
    {%- if cond2 %}
        {%- for item in items %}
        <li>
            {%- if cond3 %}
            <p>

Admittedly, this requires a bit more thought and case-by-case analysis than a bulletproof indent-everything rule, but it works for me. I certainly understand the argument for making it easier on the developer and ignoring the HTML output.

[ascott1]

Now that we're moving away from jinja templates - should we create some guidelines for Django's templating engine?

[Scotchester]

The syntax is almost exactly the same, I think. We could probably just rename this issue to "Django template standards" and keep going :)

[ascott1]

Done.