138701 - Developers' guide update for new template procedures.

Status: RESOLVED FIXED

(Bugzilla :: bugzilla.org, defect, P1)

Description

[Matthew Tuck [:CodeMachine]]

We need to fully document in the developers' guide the things we have decided
for templates for 2.16.

These include:

- extensions (I believe this is correct in the guide already ...)
- basename nameing conventions (verb-object?)
- use of PROCESS/INCLUDE/etc
- use of filters (uri, html, url_quote etc)
- everything else we have fixed up recently

Please summarise what needs to be done below.

Comment 1

[Gervase Markham [:gerv]]

- extensions (I believe this is correct in the guide already ...)

Yes, these are already documented correctly.

- basename nameing conventions (verb-object?)

Indeed. Also, for things which are editable, we have a
"create/list/edit/created/delete"-style naming convention. People should look at
existing templates for guidance.

- use of PROCESS/INCLUDE/etc

"When including other templates in yours, use PROCESS, unless you need to change
variables in the included template and have the changes _not_ show up in the
including template, in which case use INCLUDE.

- use of filters (uri, html, url_quote etc)

The simplest rule is to html filter everything that comes from the DB. It's not
worth trying to define an exception list. I don't understand the difference
between uri and url_quote clearly enough; someone else will have to write that.

- everything else we have fixed up recently

We need to document the three error commands - ThrowTemplateError,
ThrowUserError and ThrowCodeError. Their documentation can be found in my
message to the newsgroup on this subject.

Gerv

Comment 2

[David D. Kilzer (ddk)]

>- use of filters (uri, html, url_quote etc)
>
>The simplest rule is to html filter everything that comes from
>the DB. It's not worth trying to define an exception list. I
>don't understand the difference between uri and url_quote
>clearly enough; someone else will have to write that.

The 'uri' filter is only intended for full URLs, not individual
variables and values before they are added to a query string.

For example, the 'uri' filter would encode this URL (think of
it as a string containing no special or escape characters):

http://www.domain.tld/my file.cgi?var1=val1&var2=20%&var3=[`^|\]

Into this:

http://www.domain.tld/my%20file.cgi?var1=val1&var2=20%25&var3=%5B%60%5E%7C%5C%5D

Note that is does NOT encode '&', '?', '=' or other special
characters!  This makes it useful for encoding URLs that
happen to contain some unescaped characters, but if you try
to encode a variable or value that contains '&', '?' or '=',
the result will not be correct:

http://www.domain.tld/my%20file.cgi?var1=[%- '2&2=four' FILTER uri %]

prints:

http://www.domain.tld/my%20file.cgi?var1=2&2=four

This is clearly not what is wanted.  For this situation (when
encoding individual variable and value strings before assembling
into a query string), one should use the 'url_quote' filter:

http://www.domain.tld/my%20file.cgi?var1=[%- '2&2=four' FILTER url_quote %]

prints:

http://www.domain.tld/my%20file.cgi?var1=2%262%3Dfour

To summarize, the 'uri' filter should only be used to escape 
characters in full URLs that may contain some characters like
space, '%', '^' and others without parsing the whole URL into
pieces.  The 'url_quote' filter should only be used to escape
individual variables and values before they are assembled
into a query string.

Clear as mud, right?

Comment 3

[Gervase Markham [:gerv]]

-> barnboy.

Gerv

Comment 4

[Matthew Tuck [:CodeMachine]]

Gerv, this is not barnboy's area.

Comment 5

[Matthew Tuck [:CodeMachine]]

I've checked in a new version that does this, please let me know whether all
this is OK, especially the section on URL filtering.

Comment 6

[Gervase Markham [:gerv]]

It would help to know what file the Developer Guide lives in :-)

Gerv

Comment 7

[Matthew Tuck [:CodeMachine]]

bugzilla.org component, therefore www.bugzilla.org.  And it's linked pretty
clearly.  =)

Comment 8

[Gervase Markham [:gerv]]

Ah. I expected it to be in our CVS, as everything else is.

Looks OK, except for the "Dumb user" message. Please change that, and add a note:

"As far as possible, the code should be written so it's impossible for a user to
make the error, rather than beating them round the head with it."

Gerv

Comment 9

[Matthew Tuck [:CodeMachine]]

Ahh, people can't take a joke, yes?  I thought the dumb programmer message
balanced that out nicely.

Comment 10

[Gervase Markham [:gerv]]

It's OK to be rude about ourselves :-) Seriously, I don't want to encourage
people to write error messages even vaguely approximating that.

How about ("Sorry, Mr User, Bugzilla is too dumb to prevent you making an error.");

Gerv

Comment 11

[Dave Miller [:justdave]]

> Ah. I expected it to be in our CVS, as everything else is.

It is, just on "gila" instead of "cvs".

mozilla-org/html/projects/bugzilla/developerguide.html

Comment 12

[Gervase Markham [:gerv]]

I can't be bothered with this bug any more. Leave it as-is if you must. :-)

Gerv