All variables are now quoted by default, except those -explicitly protected by ;noquote or -;literal;.+explicitly protected by ;noquote or +;literal;. This means that the only way your code can fail is if the new code quotes a variable which is not meant to be quoted. Which is where -;noquote +;noquote needs to be added. That's all porting effort that is required. Actually, the variables are subject to HTML-quoting -and internationalization. The suffix ;noquote +and internationalization. The suffix ;noquote means that the variable's content will be internationalized, but not -HTML-quoted, while ;no18n +HTML-quoted, while ;no18n means quote, but don't -internationalize. Finally ;literal +internationalize. Finally ;literal means: don't quote and don't internationalize.
This is not hard because most variables will not be affected by @@ -47,11 +47,11 @@ The variables where this behavior is undesired are those that contain HTML which is expected to be included as part of the page, and those that are already quoted by Tcl code. Such -variables should be protected from quoting by the ;noquote +variables should be protected from quoting by the ;noquote modifier.
@@ -71,7 +71,7 @@ ACS has a convenience function for creating hidden form variables, -export_form_vars +export_form_vars . It accepts a list of variables and returns the HTML code containing the hidden input tags that map variable names to variable values, as found in the Tcl environment. @@ -81,7 +81,7 @@ -The ADP will simply refer to the form_vars +The ADP will simply refer to the form_vars variable:
<form>
@@ -91,12 +91,12 @@
-@@ -121,7 +121,7 @@Another example of widgets is the context bar often found on top of ACS pgages.
Obviously, all widgets should be treated as HTML and therefore -adorned with the ;noquote qualifier. This also assumes +adorned with the ;noquote qualifier. This also assumes that the routines that build the widget are correctly written and that they will quote the components used to build the widget.
@@ -132,13 +132,13 @@ HTML or text. If it is HTML, we transmit it as is; if not, we perform quoting, word-wrapping, etc. In both cases it is obvious that quoting performed by the templating system would be redundant, -so we must be careful to add ;noquote to the ADP. -The property and include Gotchas.
+so we must be careful to add ;noquote to the ADP. +The property and include Gotchas.
Transfer of parameters between included ADPs often requires manual -addition of ;noquote +addition of ;noquote . Let's review why. -The property tag is used to pass a piece of information +
The property tag is used to pass a piece of information to the master template. This is used by the ADP whose writer consciously chose to let the master template handle a variable given by the Tcl code. Typically page titles, headings, and context @@ -166,14 +166,14 @@ to provide a "title" and a "heading" of the page in a standardized fashion. The obvious intention of our slave template is to allow its corresponding Tcl code to set a single variable, -title +title , which will be used for both title and heading. What's wrong with this code?
The problem is that title gets quoted twice, once by the slave template, and once by the master template. This is the result of how the templating system works: every -occurrence of \@variable\@ is converted to -[ad_quotehtml $variable], even when it is +occurrence of \@variable\@ is converted to +[ad_quotehtml $variable], even when it is used only to set a property and you would expect the quoting to be suppressed.
Implementation note: Ideally, the @@ -191,19 +191,19 @@ Over-quoting is sometimes hard to detect because things seem to work fine in most cases. To notice the problem in the example above (and in any other over-quoting example), the title needs to contain -one of the characters <, > or -&. If it does, they will appear quoted to the user +one of the characters <, > or +&. If it does, they will appear quoted to the user instead of appearing as-is. -Over-quoting is resolved by adding ;noquote to one of -the variables. We strongly recommend that you add ;literal -inside the property tag rather than in the master. The +
Over-quoting is resolved by adding ;noquote to one of +the variables. We strongly recommend that you add ;literal +inside the property tag rather than in the master. The reason is that, first, it makes sense to do so because conceptually the master is the one that "shows" the variable, so it makes sense -that it gets to quote it. Secondly, a property tag is +that it gets to quote it. Secondly, a property tag is supposed to merely transfer a piece of text to the master; it is much cleaner and more maintainable if this transfer is defined to be non-lossy. This becomes important in practice when -there is a hierarchy of master templates -- e.g. one for +there is a hierarchy of master templates -- e.g. one for the package and one for the whole site.
To reiterate, a bug-free version of the slave template looks like this:
@@ -216,7 +216,7 @@
The exact same problems when the include statement +
The exact same problems when the include statement passes some text. Here is an example:
Including template:
@@ -226,24 +226,24 @@
<form action="do-kick" method=POST>
Kick user \@name\@.<br>
Reason: <textarea name=reason>\@reason\@</textarea><br>
- <input type=submit value="Kick">
+ <input type="submit" value="Kick">
</form>
Here an include statement is used to include an HTML form widget
-parts of which are defined with Tcl variables $id
+parts of which are defined with Tcl variables $id
and
-$default_reason
+$default_reason
whose values presumably come from the
database.
What happens is that reason that prefills the -textarea is over-quoted. The reasons are the same as in +textarea is over-quoted. The reasons are the same as in the last example: it gets quoted once by the includer, and the second time by the included page. The fix is also similar: when you transfer non-constant text to an included page, make sure to add -;literal.
+;literal.Including template, sans over-quoting:<include src="user-kick-form" id=\@kicked_id;literal\@ reason=\@default_reason;literal\@> @@ -259,16 +259,16 @@ frequency of occurrence of the problem.@@ -287,28 +287,28 @@
- Audit the template for variables that export form variables and -add ;noquote to them.
- More generally, audit the template for variables that are known +add ;noquote to them.
- More generally, audit the template for variables that are known to contain HTML, e.g. those that contain widgets or HTML content -provided by the user. Add ;noquote to them.
- Add ;literal to variables used inside the -property tag.
- Add ;noquote to textual variables whose values are -attributes to the include tag.
- Audit the template for occurrences of -<%= [ns_quotehtml \@variable\@] => -and replace them with \@variable\@.
- Audit the Tcl code for occurrences of ns_quotehtml. If +provided by the user. Add ;noquote to them.
- Add ;literal to variables used inside the +property tag.
- Add ;noquote to textual variables whose values are +attributes to the include tag.
- Audit the template for occurrences of +<%= [ns_quotehtml \@variable\@] => +and replace them with \@variable\@.
- Audit the Tcl code for occurrences of ns_quotehtml. If it is used to build an HTML component, leave it, but take note of the variable the result gets saved to. Otherwise, remove the -quoting.
- Add ;noquote to the "HTML component" variables noted +quoting.
- Add ;noquote to the "HTML component" variables noted in the previous step.
HTML junk appearing in the page.
Literal HTML visible to the user typically comes from an -"export_form_vars" or a widget variable that lacks -;noquote. To fix the problem, simply add ;noquote +"export_form_vars" or a widget variable that lacks +;noquote. To fix the problem, simply add ;noquote to the variable.Over-quoting and under-quoting.
To detect quoting defects, you need to assume an active role in naming your objects. The best way to do it is to create objects (bboard forums, messages, news items, etc.) with names that contain -the representation of an entity, e.g. "©". This +the representation of an entity, e.g. "©". This looks like the copyright SGML entity, and intentionally so. The testing consists of checking that the browser prints exactly what you typed in as the name. Thus if your forum/message/etc. is listed -as "©", everything is OK. If it is listed as -"&copy;", it means that the string was quoted +as "©", everything is OK. If it is listed as +"&copy;", it means that the string was quoted twice, i.e. over-quoted. Finally, if the entity is interpreted (shown as ©), it means that the string lacks quoting, i.e. it is under-quoted.To get rid of over-quoting, make sure that the variables don't -get quoted in transport, such as in the property -tag or as an attribute of the include tag. Also, make sure +get quoted in transport, such as in the property +tag or as an attribute of the include tag. Also, make sure that your Tcl code is not quoting the variable name.
To get rid of under-quoting, make sure that your variable gets quoted exactly once. This can be achieved either by removing a -(presumably overzealous) ;noquote or by quoting the string +(presumably overzealous) ;noquote or by quoting the string from Tcl. The latter is necessary when building HTML components, such as a context bar, from strings that come from the database or from the user.