Closed Bug 138701 Opened 22 years ago Closed 22 years ago

Developers' guide update for new template procedures.

Categories

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

2.15
defect

Tracking

()

RESOLVED FIXED
Bugzilla 2.16

People

(Reporter: CodeMachine, Assigned: CodeMachine)

Details

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.
- 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
Priority: -- → P1
Target Milestone: --- → Bugzilla 2.16
>- 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?
-> barnboy.

Gerv
Assignee: matty → mbarnson
Gerv, this is not barnboy's area.
Assignee: mbarnson → matty
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.
It would help to know what file the Developer Guide lives in :-)

Gerv
bugzilla.org component, therefore www.bugzilla.org.  And it's linked pretty
clearly.  =)
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
Ahh, people can't take a joke, yes?  I thought the dumb programmer message
balanced that out nicely.
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
> 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
I can't be bothered with this bug any more. Leave it as-is if you must. :-)

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