Closed Bug 107917 Opened 23 years ago Closed 20 years ago

Template Style


(Bugzilla ::, defect, P2)




Bugzilla 2.20


(Reporter: CodeMachine, Assigned: gerv)



We need to work out the style guide for templates.  In particular, whether we
indent to make templates look right, or the source code to look right.

Once this is done we need to document it in the hackers' guide.
Let's do both per Gerv's post in n.p.m.webtools.

Priority: -- → P2
Target Milestone: --- → Bugzilla 2.18
Does this need pushing out? Can't we just decide on something?

Style Rule: Use template comments rather than HTML comments, etc, so the comment
doesn't pass through to the browser and bloat the download.
Fixing component ...
Assignee: justdave → barnboy
Component: Bugzilla-General → Documentation
What I said:

"We need to talk about this, because templates are not the same as code.

The problem is that it's good to nest tags using indentation, but there are
often a large number of levels of tags. Here's what I propose:

2-space indent. Embedded code sections on their own line, in line with outer
tags. So:

[% IF foo %]
  [% FOREACH x = barney %]
        [% x %]
  [% END %]
[% END %]

I also recommend we turn on PRE_CHOMP in the template initialisation; this
prevents us bloating the resulting HTML with a load of whitespace the client is
just going to ignore. Combining that with the above indenting scheme happens to
produce nicely-formatted resulting source, as well."

Do we need to define anything else? I prefer to stick to an 80-char line length;
we should certainly define _some_ maximum line length. We might want to add
points about using hashes for readability, as Myk recommended for query.cgi.

Lastly, we should be allowed to reset the indentation back to zero, if it gets
too deep, by using two blank lines:


<baz rel="yaya" href="">
  <another-tag />
  <another-tag />
  <another-tag />


The docs should always be up-to-date when we release.  Forgot to exclude
Documentation when I mass-retargetted.
Target Milestone: Bugzilla 2.18 → Bugzilla 2.16
I am putting this into the docs as 4-space indent so that there's no disconnect
between Perl coding standards and Template coding standards.
how does that compare to what's already in use?
Guess I'll go need to check out the code on this one, not bothering trying to
resolve it right now.
A 4-space indent is inappropriate, and the disconnect is intentional. Please
read again what I wrote above.

In code, multi-levels of indentation indicates logic problems, and makes you
lean towards a restructuring. Also, lines of code tend to be long.

In HTML, a line can be a single tag, and deep nesting is common. A 4-line indent
would cause a great deal of trouble because most of the important code would
need to be crammed into the last 30 characters of the line it's on!

Also, all my templates (don't know about Myk's, but he backs my views) are 2-space.

As I said in IRC yesterday:

12:47:30 <myk>	i agree with Gerv.  first of all, there is no reason to maintain a
single indentation standard across totally different kinds of documents just so
we can say we have a standard.
12:48:16 <myk>	the number of different kinds of documents should dictate the number of
12:49:48 <myk>	so there is no conflict at all between the template and Perl code
standards... each one expresses the optimal formatting for those kinds of files
12:51:04 <myk>	second of all, two-space indents work well for HTML files and HTML
templates for the reason already mentioned: there are often numerous levels of
12:53:26 <myk>	also, in my personal opinion, two-space indentation strikes the optimal
balance between no indentation and too much indentation, both of which make it
difficult to discern the document's structure
12:56:36 <myk>	it should also be noted that indentation is not the only mechanism by
which the structure of code or markup can be delineated, and we should not treat
it as such
12:57:24 <myk>	syntax highlighting, code tree generation, and other mechanisms can and
should be used in addition to indentation by Bugzilla hackers to help them read
the code

As with Gerv's templates, all mine are two-space indented, and as far as I know
that means all current Bugzilla templates use two-space indentation.

Document template versioning information:

For HTML-based templates:
<!-- -->

For non-HTML-based (or, all other) templates:
[%# %]

NOTE: This comment MUST appear as the first line of the file!
major version update -> incompatible change; an old template won't work
minor version update -> compatiable change; an older template may not be able to
take advantage of new features, but what it had still works.
Barnboy changed his email address and opened a new account instead of having the
address changed on his existing one.  Reassigning all docs bugs to his new account.
Assignee: barnboy → mbarnson
MattyT: are you going to put this stuff in the Developers Guide? If so, this bug
is yours, not barnboy's :-)

MattyT: ping?

Everything is pretty much within the guide except the indentation policy
mentioned on the first line.  I didn't document because I disagreed with it and
hadn't got around to raising the issue.

As far as I know you're the only one who supports it Gerv.
What exactly about the indentation policy don't you like? Every single template
in Bugzilla (and there are now over 50) that I am aware of conforms to my
suggestions for indentation (2-space etc.) So I'm not alone :-)

First Line = "... In particular, whether we indent to make templates look right,
or the source code to look right."

That's what I have a problem with.  And no, they aren't all the same style.  A
quick look shows Myk still uses template-looks-right indentation, even though
all my templates are currently on branches I think.
> > In particular, [we need to consider] whether we indent to make templates 
> > look right, or the source code to look right.
> That's what I have a problem with.

You have a problem with me suggesting we consider that question? :-)

I suggested an indentation scheme which made the templates look nice, and
mentioned in passing that it also produced readable HTML. It doesn't have to be
one or the other; we can have both. But I agree template readability is more
important than HTML readability - and I chose the scheme I did on that basis.

You must be looking at different templates than me.

Anyway, nothing more is happening here for 2.16.
Target Milestone: Bugzilla 2.16 → Bugzilla 2.18
I'm not touching this one with a 10-foot pole :)  Tell me what you want, and
I'll change the Guide if necessary.
Changed my mind.  Lumped this into the FAQ section so we can get the bug off the
boards; if someone later decides to relocate this information, by all means feel
free :)
Closed: 22 years ago
Resolution: --- → FIXED
This should not be in the FAQ section of the Bugzilla Guide; in fact, it should
not be in the Bugzilla Guide at all. We have a perfectly good Developers' Guide,
where developers look for information relating to development. They will not
look in the Bugzilla Guide FAQ for details of how to write templates.

Please reopen this bug until the information is in the right place :-)

Resolution: FIXED → ---
Assignee: matthew → matty
Component: Documentation →
QA Contact: matty → justdave
Hmm... help me out, I'm not seeing a "Developer's Guide" in my CVS checkout of
the source or on the website.  What am I missing?
it's in the website.

Try cvs update -dP
This is sitting too long.  Looks from the comments we have here that we already
have a decision.  Someone just needs to put it in place on the website.
Assignee: matty → gerv
*** Bug 120925 has been marked as a duplicate of this bug. ***
Depends on: 140527
Unloved bugs targetted for 2.18 but untouched since 9-15-2003 are being
retargeted to 2.20
If you plan to act on one immediately, go ahead and pull it back to 2.18.
Target Milestone: Bugzilla 2.18 → Bugzilla 2.20
After reading the Developer's Guide at, it seems that the information this
bug deals with in already in place:

# Indentation - HTML Templates should have a 2-space indent.
Fair enough :-)

Closed: 22 years ago20 years ago
Resolution: --- → FIXED
QA Contact: justdave → default-qa
You need to log in before you can comment on or make changes to this bug.