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
Last Resolved: 16 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.