30

This means that the only way your code can fail is if the new code

31

quotes a variable which is not meant to be quoted. Which is where

32

<kbd>;noquote</kbd>

33

needs to be added. That's all porting effort that

34

is required. Actually, the variables are subject to HTML-quoting

35

and internationalization. The suffix <kbd>;noquote</kbd>

36

means that

37

the variable's content will be internationalized, but not

38

HTML-quoted, while <kbd>;no18n</kbd>

39

means quote, but don't

40

internationalize. Finally <kbd>;literal</kbd>

41

means: don't quote and

42

don't internationalize.

33

needs to be added. That's all porting

34

effort that is required. Actually, the variables are subject to

35

HTML-quoting and internationalization. The suffix

36

<kbd>;noquote</kbd>

37

means that the variable's content will be

38

internationalized, but not HTML-quoted, while <kbd>;no18n</kbd>

39

40

means quote, but don't internationalize. Finally

41

<kbd>;literal</kbd>

42

means: don't quote and don't

43

internationalize.

43

44

This is not hard because most variables will not be affected by

44

45

this change. Most variables either need to be quoted (those

45

46

containing textual data that comes from the database or from the

46

47

user) or are unaffected by quoting (numerical database IDs, etc.)

47

The variables where this behavior is undesired are those that

48

contain HTML which is expected to be included as part of the

49

page, and those that are already quoted by Tcl code. Such

50

variables should be protected from quoting by the <kbd>;noquote</kbd>

51

modifier.

48

The variables where this behavior is undesired are those

49

that contain HTML which is expected to be included as part

50

of the page, and those that are already quoted by

51

Tcl code. Such variables should be protected from quoting by the

52

<kbd>;noquote</kbd> modifier.

52

53

<h3>The Most Common Cases.</h3>

53

54

55

The most common cases where you need to add <kbd>;noquote</kbd>

55

56

to

56

57

the variable name are easy to recognize and identify.

57

58

58

59

Hidden form variables.

59

Also known as "hidden input fields", hidden form variables are form

60

fields with pre-defined values which are not shown to the user.

61

These days they are used for transferring internal state across

62

several form pages. In HTML, hidden form variables look like

63

this:

60

Also known as "hidden input fields", hidden form

61

variables are form fields with pre-defined values which are not

62

shown to the user. These days they are used for transferring

63

internal state across several form pages. In HTML, hidden form

64

variables look like this:

64

65

65

66

<form>

66

67

111

112

widgets

112

113

.

113

114

Normally we try to fit all HTML code into the ADP template and have

114

the Tcl code handle the "logic" of the program. And yet, sometimes

115

pieces of relatively convoluted HTML need to be included in many

116

templates. In such cases, it makes sense to generate the

117

widget programmatically and include it into the template as

118

a variable. A typical widget is a date entry widget which provides

119

the user the input and selection boxes for year, month, and day,

120

all of which default to the current date.

121

Another example of widgets is the context bar often found

122

on top of ACS pgages.

115

the Tcl code handle the "logic" of the program. And yet,

116

sometimes pieces of relatively convoluted HTML need to be included

117

in many templates. In such cases, it makes sense to generate the

118

widget programmatically and include it into the template

119

as a variable. A typical widget is a date entry widget which

120

provides the user the input and selection boxes for year, month,

121

and day, all of which default to the current date.

122

Another example of widgets is the context bar often

123

found on top of ACS pgages.

123

124

Obviously, all widgets should be treated as HTML and therefore

124

125

adorned with the <kbd>;noquote</kbd> qualifier. This also assumes

125

126

that the routines that build the widget are correctly

137

138

139

Transfer of parameters between included ADPs often requires manual

139

140

addition of <kbd>;noquote</kbd>

140

. Let's review why.

141

The <kbd>property</kbd> tag is used to pass a piece of information

142

to the master template. This is used by the ADP whose writer

143

consciously chose to let the master template handle a variable

144

given by the Tcl code. Typically page titles, headings, and context

145

bars are handled this way. For example:

141

. Let's review why.

142

The <kbd>property</kbd> tag is used to pass a piece of

143

information to the master template. This is used by the ADP whose

144

writer consciously chose to let the master template handle a

145

variable given by the Tcl code. Typically page titles, headings,

146

and context bars are handled this way. For example:

146

147

147

148

master:<pre>

148

149

<head>

163

164

</blockquote>

164

165

166

The obvious intention of the master is to allow its slave templates

166

to provide a "title" and a "heading" of the page in a standardized

167

fashion. The obvious intention of our slave template is to allow

168

its corresponding Tcl code to set a single variable,

169

<kbd>title</kbd>

170

, which will be used for both title and heading.

171

What's wrong with this code?

167

to provide a "title" and a "heading" of the

168

page in a standardized fashion. The obvious intention of our slave

169

template is to allow its corresponding Tcl code to set a single

170

variable, <kbd>title</kbd>

171

, which will be used for both title and

172

heading. What's wrong with this code?

172

173

The problem is that title gets quoted twice, once by

173

174

the slave template, and once by the master template. This is the

174

175

result of how the templating system works: every

175

176

occurrence of <kbd>\@<var>variable</var>\@</kbd> is converted to

176

<kbd>[ad_quotehtml $<var>variable</var>]</kbd>, even when it is

177

used only to set a property and you would expect the quoting to be

178

suppressed.

177

<kbd>[ad_quotehtml $<var>variable</var>]</kbd>, even when it

178

is used only to set a property and you would expect the quoting to

179

be suppressed.

179

180

<blockquote>Implementation note: Ideally, the

180

181

templating system should avoid this pitfall by quoting the variable

181

182

(or not) only once, at the point where the value is passed from the

182

183

Tcl code to the templating system. However, no such point in time

183

184

exists because what in fact happens is that the template gets

184

compiled into code that simply takes what it needs from the

185

environment and then does the quoting. Properties are passed

186

to the master so that all the property variables are shoved into an

187

environment; by the time the master template is executed, all

188

information on which variable came from where and whether it might

189

have already been quoted is lost.</blockquote>

185

compiled into code that simply takes what it needs from

186

the environment and then does the quoting. Properties are

187

passed to the master so that all the property variables are shoved

188

into an environment; by the time the master template is executed,

189

all information on which variable came from where and whether it

190

might have already been quoted is lost.</blockquote>

190

191

This occurrence is often referred to as over-quoting.

191

192

Over-quoting is sometimes hard to detect because things seem to

192

193

work fine in most cases. To notice the problem in the example above

195

196

<kbd>&</kbd>. If it does, they will appear quoted to the user

196

197

instead of appearing as-is.

197

198

Over-quoting is resolved by adding <kbd>;noquote</kbd> to one of

198

the variables. We strongly recommend that you add <kbd>;literal</kbd>

199

inside the <kbd>property</kbd> tag rather than in the master. The

200

reason is that, first, it makes sense to do so because conceptually

201

the master is the one that "shows" the variable, so it makes sense

202

that it gets to quote it. Secondly, a <kbd>property</kbd> tag is

203

supposed to merely transfer a piece of text to the master;

204

it is much cleaner and more maintainable if this transfer is

205

defined to be non-lossy. This becomes important in practice when

206

there is a hierarchy of <kbd>master</kbd> templates -- e.g. one for

207

the package and one for the whole site.

199

the variables. We strongly recommend that you add

200

<kbd>;literal</kbd> inside the <kbd>property</kbd> tag rather than

201

in the master. The reason is that, first, it makes sense to do so

202

because conceptually the master is the one that "shows"

203

the variable, so it makes sense that it gets to quote it. Secondly,

204

a <kbd>property</kbd> tag is supposed to merely transfer a

205

piece of text to the master; it is much cleaner and more

206

maintainable if this transfer is defined to be non-lossy. This

207

becomes important in practice when there is a hierarchy of

208

<kbd>master</kbd> templates -- e.g. one for the package and one for

209

the whole site.

208

210

To reiterate, a bug-free version of the slave template looks

209

211

like this:

210

212

265

267

<kbd>property</kbd> tag.</li><li>Add <kbd>;noquote</kbd> to textual variables whose values are

266

268

attributes to the <kbd>include</kbd> tag.</li><li>Audit the template for occurrences of

267

269

<kbd><%= [ns_quotehtml \@<var>variable</var>\@] =></kbd>

268

and replace them with <kbd>\@<var>variable</var>\@</kbd>.</li><li>Audit the Tcl code for occurrences of <kbd>ns_quotehtml</kbd>. If

269

it is used to build an HTML component, leave it, but take note of

270

the variable the result gets saved to. Otherwise, remove the

271

quoting.</li><li>Add <kbd>;noquote</kbd> to the "HTML component" variables noted

272

in the previous step.</li>

270

and replace them with <kbd>\@<var>variable</var>\@</kbd>.</li><li>Audit the Tcl code for occurrences of <kbd>ns_quotehtml</kbd>.

271

If it is used to build an HTML component, leave it, but take note

272

of the variable the result gets saved to. Otherwise, remove the

273

quoting.</li><li>Add <kbd>;noquote</kbd> to the "HTML component"

274

variables noted in the previous step.</li>

273

275

</ol>

274

276

275

After that, test that the template behaves as it should, and you're

276

done.

277

After that, test that the template behaves as it should, and

278

you're done.

277

279

<h3>Testing.</h3>

278

280

279

281

Fortunately, most of the problems with automatic quoting are very

287

289

<li>

288

290

HTML junk appearing in the page.

289

291

Literal HTML visible to the user typically comes from an

290

"<kbd>export_form_vars</kbd>" or a widget variable that lacks

291

<kbd>;noquote</kbd>. To fix the problem, simply add <kbd>;noquote</kbd>

292

to the variable.</li><li>

292

"<kbd>export_form_vars</kbd>" or a widget variable that

293

lacks <kbd>;noquote</kbd>. To fix the problem, simply add

294

<kbd>;noquote</kbd> to the variable.</li><li>

293

295

Over-quoting and under-quoting.

294

296

To detect quoting defects, you need to assume an active role in

295

297

naming your objects. The best way to do it is to create objects

296

298

(bboard forums, messages, news items, etc.) with names that contain

297

298

looks like the copyright SGML entity, and intentionally so. The

299

testing consists of checking that the browser prints exactly what

300

you typed in as the name. Thus if your forum/message/etc. is listed

301

302

"<kbd>&amp;copy;</kbd>", it means that the string was quoted

303

twice, i.e. over-quoted. Finally, if the entity is interpreted

304

305

is under-quoted.

306

To get rid of over-quoting, make sure that the variables don't

307

get quoted in transport, such as in the <kbd>property</kbd>

308

tag or as an attribute of the <kbd>include</kbd> tag. Also, make sure

309

that your Tcl code is not quoting the variable name.To get rid of under-quoting, make sure that your variable gets

299

the representation of an entity, e.g.

300

301

SGML entity, and intentionally so. The testing consists of checking

302

that the browser prints exactly what you typed in as the name. Thus

303

if your forum/message/etc. is listed as

304

305

listed as "<kbd>&amp;copy;</kbd>", it means that the

306

string was quoted twice, i.e. over-quoted. Finally, if the entity

307

308

quoting, i.e. it is under-quoted.

309

To get rid of over-quoting, make sure that the variables

310

don't get quoted in transport, such as in the

311

<kbd>property</kbd> tag or as an attribute of the

312

<kbd>include</kbd> tag. Also, make sure that your Tcl code is not

313

quoting the variable name.To get rid of under-quoting, make sure that your variable gets

310

314

quoted exactly once. This can be achieved either by removing a

311

(presumably overzealous) <kbd>;noquote</kbd> or by quoting the string

312

from Tcl. The latter is necessary when building HTML components,

313

such as a context bar, from strings that come from the database or

314

from the user.

315

(presumably overzealous) <kbd>;noquote</kbd> or by quoting the

316

string from Tcl. The latter is necessary when building HTML

317

components, such as a context bar, from strings that come from the

318

database or from the user.

315

319

</li>

316

320

</ul>

317

321

<hr>