Debian Codegraph @

doc/reference.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2
3 <html>
4 <head>
5 <title>Ctemplate System Reference Guide</title>
6
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
8 <link href="designstyle.css" type="text/css" rel="stylesheet">
9 <style type="text/css">
10 ol.bluelist li {
11 color: #3366ff;
12 font-family: sans-serif;
13 }
14 ol.bluelist li p {
15 color: #000;
16 font-family: "Times Roman", times, serif;
17 }
18 ul.blacklist li {
19 color: #000;
20 font-family: "Times Roman", times, serif;
21 }
22 </style>
23 </head>
24
25 <body>
26
27 <h1>Ctemplate System Reference Guide</h1>
28 <small>(as of
29 <script type=text/javascript>
30 var lm = new Date(document.lastModified);
31 document.write(lm.toDateString());
32 </script>)
33 </small>
34 <br>
35
36
37 <h2> Overview </h2>
38
39 <p>The main class used by the template system is
40 <code>TemplateDictionary</code>, which is used to expand a template
41 file. It is used by the main functions for expanding a template,
42 found in <code>template.h</code>.</p>
43
44 <p><code>TemplateCache</code> is used to hold a collection of
45 <code>Template</code> objects. <code>TemplateNamelist</code> provides
46 various introspection routines on collections of <code>Template</code>
47 objects.</p>
48
49 <p><code>TemplateModifier</code> and <code>PerExpandData</code> are
50 used to modify the values of a <code>TemplateDictionary</code> at
51 expand time. <code>TemplateAnnotator</code> does too, but is intended
52 for debugging purposes. <code>TemplateDictionaryPeer</code> is used
53 for testing template code.</p>
54
55 <p><code>ExpandEmitter</code> provides the ability to emit an expanded
56 template to an arbitrary output store.</p>
57
58 <p><code>TemplateString</code> is a string-like class that is built to
59 be very efficient when used with the template system. For instance,
60 tools are available to hash constant <code>TemplateString</code>
61 objects at compile-time, speeding up their use at run-time.</p>
62
63 <p>The rest of this document describes these classes and functions in
64 more detail, as well as build tools and other mechanisms for handling
65 templates.</p>
66
67 <p>(Note: the code snippets below all assume the default configuration
68 option is set, which puts template code in namespace
69 <code>ctemplate</code>.)</p>
70
71 <h2> <A NAME="template">Expanding Templates</A> </h2>
72
73
74 <h3> The Template Language </h3>
75
76 <p>Templates are strings that contain special formatting code called
77 <em>template markers</em>. In the Ctemplate System, template
78 strings are usually read from a file.</p>
79
80 <p>Anything found in a template of the form {{...}} is
81 interpreted as a template marker. All other text is considered
82 formatting text and is output verbatim at template expansion time.
83 Outside of the template markers, templates may contain any text
84 whatsoever, including (single) curly braces and NUL characters.</p>
85
86 <p>The template language has six types of markers:</p>
87 <ol>
88 <li> <b>Variable</b> markers, which are replaced by text based on
89 dictionary values. Variable markers look like this:
90 {{FOO}}</li>
91
92 <li> <b>Start section</b> and <b>end section</b> markers, which
93 delimit sections which may appear zero, one, or N times in
94 the output. Section markers look like this:
95 <code>{{#FOO}}...{{/FOO}}</code></li>
96
97 <li> <b>Template-include</b> markers, which designate other
98 templates to be expanded and inserted at the location where the
99 marker appears. These are treated much like sections -- one
100 may think of them as sections whose content is specified in a
101 different file instead of inline -- and just like sections, can
102 be expanded zero, one or N times in the output, each with a
103 different dictionary. Template-include markers look like this:
104 <code>{{&gt;FOO}}</code></li>
105
106 <li> <b>Comment</b> markers, which may annotate the template
107 structure but drop completely out of the expanded
108 output. Comment markers look like this:
109 <code>{{!&nbsp;comment&nbsp;lives&nbsp;here -- cool, no?}}</code></li>
110
111 <li> <b>Set-delimiter</b> markers, which change the marker
112 delimiters from <code>{{</code> and <code>}}</code> to custom
113 strings. (The only requirement is that these strings not
114 contain whitespace or the equals sign.) This is useful for
115 languages like TeX, where double-braces may occur in the text
116 and are awkward to use for markup. Set-delimiter markers look
117 like this: <code>{{=&lt; &gt;=}} &lt;! Now markers are
118 delimited by braces &gt; &lt;=| |=&gt; |! And now markers are
119 delimited by bars! | </code></li>
120
121 <li> <b>Pragma</b> markers, which invoke additional built-in template
122 features when processing the template. Pragma markers look like
123 this: <code>{{%PRAGMA [name="value"...]}}</code>. Currently,
124 AUTOESCAPE is the only pragma defined.</li>
125 </ol>
126
127 <p>These marker types each have their own namespace. For readability,
128 however, it is best to not overuse a single name.</p>
129
130
131 <h3> Modifiers </h3>
132
133 <p>A variable and include-template can have one or more <A
134 HREF="#template_modifier">modifiers</A> attached to them, like so:</p>
135 <pre>
136 {{MYVAR:mod1:mod2:mod3=value:mod4=value with spaces:mod5}}
137 </pre>
138
139 <p>A modifier is a filter that's
140 applied at template-expand time, that munges the value of the variable
141 before it's output. See the <A
142 HREF="#template_modifier"><code>TemplateModifier</code></A> class for
143 more details.</p>
144
145 <p>When expanding a variable (or template-include) with a modifier,
146 the modifiers are applied in order, left to right. For a
147 template-include, first the entire sub-template is expanded, as a
148 single string, and then the modifiers are applied to that string.</p>
149
150 <p>In general, using explicit modifiers does not turn off <A
151 HREF="#auto_escape">auto-escaping</A> on a variable. The explicit
152 modifier <code>:none</code> does suppress auto-escaping.</p>
153
154
155 <h3> <A NAME="special_markers">Special Markers</A> </h3>
156
157 <p>Some marker names may have a special meaning in the template
158 system. Right now, there's one such name.</p>
159
160 <h4><A NAME="separator">Separator Sections</A></h4>
161
162 <p>If you have a section named FOO, you can define inside
163 of it a section named FOO_separator, and the template
164 system will automatically expand that section every time
165 <code>FOO</code> is expanded, <i>except for the last</i>. Thus, the
166 contents of <code>FOO_separator</code> can be used to separate
167 repeated values of a section.</p>
168
169 <p>Here's an example:</p>
170 <pre>
171 Here are the meeting attendees:
172 {{#ATTENDEES}}
173 {{NAME}}
174 {{#ATTENDEES_separator}}, {{/ATTENDEES_separator}}
175 {{/ATTENDEES}}
176 .
177 </pre>
178
179 <p>Here is a more convoluted example, to show the date:</p>
180 <pre>
181 {{#DATE}}{{DATE_COMPONENT}}{{#DATE_separator}}{{DATE_SEP}}{{/DATE_separator}}{{/DATE}}
182 </pre>
183
184 <p>You'd set up a template dictionary to repeat <code>DATE</code>
185 three times, with <code>DATE_COMPONENT</code> set to the month, day,
186 and year (or day, month, and year, depending on your locale...), and
187 <code>DATE_SEP</code> set to <code>/</code> or <code>-</code> or
188 whatever date-separator is called for.</p>
189
190 <p><code>SEP_separator</code> is always evaluated with the current
191 dictionary. Thus, in the date example, if you wanted a different
192 separator each time, you could do so by setting <code>DATE_SEP</code>
193 to a different value for each repetition of <code>DATE</code>.</p>
194
195 <p>While <code>SEP_separator</code> is automatically expanded by the
196 template system, it is otherwise a perfectly normal section. You can
197 even instantiate it yourself by calling
198 <code>AddSectionDictionary("SEP_separator")</code>. In that case, the
199 section will be expanded both via the automatic expansion as a
200 separator, and as a normal section via the section dictionary you
201 added. This is more confusing than helpful, and you should probably
202 never do it.</p>
203
204 <p>There can be at most one "separator" sub-section per section. If
205 there are more, only the last is automatically expanded.</p>
206
207
208 <h3> <A NAME="strip">Specifying a template</A> </h3>
209
210 <p>In the template system -- in functions like
211 <code>ExpandTemplate()</code> -- a template is specified by a pair:
212 filename + strip-mode. The filename specifies the name of the
213 template file on disk (but see below for string templates). The strip
214 mode specifies how this file should be parsed as it's read from disk,
215 in particular, how whitespace should be handled. It can take the
216 following values:</p>
217
218 <ul>
219 <li> <code>ctemplate::DO_NOT_STRIP</code>: do nothing. This expands
220 the template file verbatim.
221
222 <li> <code>ctemplate::STRIP_BLANK_LINES</code>: remove all blank
223 lines. This ignores any blank lines found in the template file
224 when parsing it. When the template is html, this reduces the
225 size of the output text without requiring a sacrifice of
226 readability for the input file.
227
228 <li> <code>ctemplate::STRIP_WHITESPACE</code>: remove not only blank
229 lines when parsing, but also whitespace at the beginning and
230 end of each line. It also removes any linefeed (possibly
231 following whitespace) that follows a closing <code>}}</code> of
232 any kind of template marker <i>except</i> a template variable.
233 (This means a linefeed may be removed anywhere by simply
234 placing a comment marker as the last element on the line.)
235 When the template is html, this reduces the size of the output
236 html without changing the way it renders (except in a few
237 special cases.) When using this flag, the built-in template
238 variables <code>BI_NEWLINE</code> and <code>BI_SPACE</code> can
239 be useful to force a space or newline in a particular
240 situation.
241 </ul>
242
243 <p>The filename is where the template file lives on disk. It can be
244 either an absolute filename, or relative to a directory in the
245 <A HREF="#search_path">template search path</A>.</p>
246
247 <p>In addition to reading a template from disk, it is possible to read
248 a template from a string, using <code>StringToTemplateCache()</code>.
249 The first argument of <code>StringToTemplateCache()</code> is a "key"
250 to use to refer to this string-based template. This key takes the
251 place of the filename, for any routine that asks for a
252 filename + strip.</p>
253
254
255 <h3> <A NAME="expand_template">ExpandTemplate()</A> </h3>
256
257 <p>This is the main workhorse function of the template system. It
258 takes the filename of a template, a <A
259 HREF="#template_dictionary">template dictionary</A>, and a string to
260 emit to, and emits an "expanded" version of the template using the
261 given template dictionary to fill in the template markers.</p>
262
263 <p>If the template specified by the given filename is already found in
264 an internal cache, the cached version of the template is used,
265 otherwise the template is loaded from disk, parsed, and stored in the
266 cache before expansion is performed. As always, the "filename" can
267 also be a <A HREF="#strip">key</A> to a string-based template,
268 inserted directly into the cache via
269 <code>StringToTemplateCache()</code>.</p>
270
271 <p>There is an overloaded version of <code>Expand()</code> that takes
272 an <A HREF="#expand_emitter"><code>ExpandEmitter</code></A> rather
273 than a string, as the source to expand the template into.</p>
274
275 <p>This function returns true if the template was successfully
276 expanded into the output parameter. It returns false if expansion
277 failed or was only partially successful. It might fail because the
278 template file cannot be found on disk, or because the template has
279 syntax errors and cannot be parsed, or because the template
280 sub-includes another template, and that sub-template has errors. To
281 minimize the risk of errors at expand-time, you can call
282 <code>LoadTemplate()</code> (below) first to load and parse the
283 template into the cache. This will catch all errors except for errors
284 involving sub-templates.</p>
285
286 <p>In the case of partial failures -- typically, failures resulting in
287 an error in a sub-inclued template -- there may be partial data
288 emitted to the output before the error was detected. If
289 <code>ExpandTemplate()</code> returns false, you should be careful to
290 check for and remove this partial data, if desired.</p>
291
292
293 <h3> <A NAME="expand_with_data">ExpandWithData()</A> </h3>
294
295 <p><code>ExpandWithData()</code> is like
296 <code>ExpandTemplate()</code>, with the addition that it allows you to
297 pass in <A HREF="#per_expand_data">per-expand data</A>. It's called
298 like this:</p>
299 <pre>
300 ctemplate::TemplateDictionary dict(...);
301 ctemplate::PerExpandData per_expand_data;
302 string output;
303 ctemplate::ExpandWithData(filename, strip_mode, &amp;output, &amp;dict,
304 &amp;per_expand_data);
305 </pre>
306
307 <p>Per-expand data is applied to all templates that are seen while
308 expanding: not only the template you called <code>Expand()</code> on,
309 but also sub-templates that are brought in via template-includes
310 (<code>{{&gt;INCLUDE}}</code>). See the description of the <A
311 HREF="#per_expand_data"><code>PerExpandData</code></A> class for more
312 details about how expansion can be modified by per-expand data.</p>
313
314 <p>The return value has the same meaning as for
315 <code>ExpandTemplate()</code> In fact, if you pass in
316 <code>NULL</code> as the <code>per_expand_data</code> argument, this
317 function is exactly equivalent to <code>ExpandTemplate()</code>.</p>
318
319
320 <h3> <A NAME="load_template">LoadTemplate()</A> </h3>
321
322 <p>This function takes a filename and a strip-mode, and loads the file
323 into the default template cache. Future calls to
324 <code>ExpandTemplate()</code> or <code>ExpandWithData()</code> will
325 get the parsed template from the cache, without needing to go to
326 disk.</p>
327
328 <p>This function returns true if the template was successfully read
329 from disk, parsed, and inserted into the cache. It will also return
330 true if the template is already in the cache (even if the file has
331 changed on disk since the template was inserted into the cache). It
332 will return false if the file cannot be found on disk, or cannot be
333 successfully parsed. (Note that <code>LoadTemplate()</code> cannot
334 detect errors in sub-included templates, since the identity of
335 sub-included templates is specified in a
336 <code>TemplateDictionary</code>, not in the template itself.)</p>
337
338
339 <h3> <A NAME="string_to_template_cache">StringToTemplateCache()</A> </h3>
340
341 <p>In addition to reading a template file from disk, it is also
342 possible to read a template file from a string, using
343 <code>StringToTemplateCache()</code>. It takes the content
344 as a string. It also takes in a key and a <A HREF="#strip">strip</A>
345 mode. The given key and strip mode can be used as the filename/strip
346 pair in calls to <code>ExpandTemplate()</code> and similar
347 functions. The key can also be used as the "filename" in calls to
348 <code>ctemplate::TemplateDictionary::SetFilename()</code>, allowing
349 this template to be included inside other templates.</p>
350
351 <p><code>StringToTemplateCache()</code> returns true if the string is
352 successfully inserted into the cache. It returns false otherwise,
353 probably because there is already a string or filename in the cache
354 with the same key.</p>
355
356
357 <h3> default_template_cache() and mutable_default_template_cache() </h3>
358
359 <p>All the above routines -- <code>ExpandTemplate()</code>,
360 <code>LoadTemplate()</code>, and the like -- read and write parsed
361 templates to the default template cache. This is just a static
362 instance of the <A
363 HREF="#template_cache"><code>TemplateCache</code></A> class. It can
364 be accessed via these two functions:
365 <code>default_template_cache()</code> and, if you need a non-const
366 version of the cache, <code>mutable_default_template_cache()</code>.
367 These can be useful if you need the advanced features of template
368 caches, such as <code>ReloadAllIfChanged()</code> or
369 <code>ClearCache()</code>.</p>
370
371
372 <h2> <A NAME="template_dictionary">The <code>TemplateDictionary</code>
373 Class</A> </h2>
374
375 <p>The class <code>TemplateDictionary</code> is used for all template
376 dictionary operations. In general, an application will need to call a
377 <code>TemplateDictionary</code> method for every marker in the
378 associated template (the major exception: markers that evaluate to the
379 empty string can be ignored).</p>
380
381 <p>The appropriate function to call for a given template marker
382 depends on its type.</p>
383
384
385 <h3> Data Dictionaries </h3>
386
387 <p>A data dictionary is a map from keys to values. The keys are
388 always strings, corresponding to the name of the associated template
389 marker, so a section <code>{{#FOO}}</code> in the template text is
390 matched to the key <code>FOO</code> in the dictionary, if it exists.
391 Note the case must match as well.</p>
392
393 <p>The value associated with a key differs according to key type. The
394 value associated with a <i>variable</i> is simple: it's the value for
395 that variable. Both keys and values can be any 8-bit
396 character-string, and may include internal NULs (<code>\0</code>).</p>
397
398 <p>The value associated with a <i>section</i> is a list of data
399 dictionaries. At template-expansion time, the section is expanded
400 once for each dictionary in the list. The first time, all
401 variables/etc. in the section will be evaluated taking into account
402 the first dictionary. The second time, all variables/etc. will be
403 evaluated taking into account the second dictionary. (See <A
404 HREF="#inheritance">below</A> for a definition of "taking into
405 account.")</p>
406
407 <p>The value associated with a <i>template-include</i> is also a list
408 of data dictionaries. Each data dictionary in this list must also
409 have one other, mandatory associated piece of associated information:
410 the filename of the template to include. At expand-time, that
411 filename is passed as-is to <code>ctemplate::ExpandTemplate()</code>
412 (or, more exactly, the equivalent of <code>ExpandTemplate()</code> in
413 the same <code>TemplateCache</code> that the parent template comes
414 from).</p>
415
416
417 <h3> <A NAME="inheritance">Details on Dictionary Lookup</A> </h3>
418
419 <p>The dictionary structure is a tree: there's a 'main' dictionary,
420 and then a list of sub-dictionaries for each section or
421 include-template. When looking up a marker -- be it a variable,
422 section, or include-template marker -- the system looks in the
423 currently applicable dictionary. If it's found there, that value is
424 used. If not, and the parent dictionary is not an include-template,
425 it continues the look in the parent dictionary, and possibly the
426 grandparent, etc. That is, lookup has <i>static scoping</i>: you look
427 in your dictionary and any parent dictionary that is associated with
428 the same template-file. As soon as continuing the lookup would
429 require you to jump to a new template-file (which is what
430 include-template would do), we stop the lookup.</p>
431
432 <p>If lookup fails in all dictionaries, the template system does a
433 final lookup in the <b>global variable dictionary</b>.</p>
434
435 <p>The system initializes the global dictionary with a few useful
436 values for your convenience (the user can add more). All system
437 variables are prefixed with <code>BI</code>, to emphasize they are
438 "built in" variables.</p>
439 <ul>
440 <li> <code>BI_SPACE</code>, which has the value
441 <code>&lt;space&gt;</code>. It is used to force a space
442 at the beginning or end of a line in the template,
443 where it would normally be suppressed. (See below.) </li>
444
445 <li><code>BI_NEWLINE</code>, which has the value
446 <code>&lt;newline&gt;</code> It is used to force a
447 newline at the end of a line, where it would normally
448 be suppressed. (See below.) </li>
449 </ul>
450
451 <p>Variable inheritance happens at expand time, not at
452 dictionary-create time. So if you create a section dictionary, and
453 then afterwards set a variable in its parent dictionary (or in the
454 global dictionary), the section <i>will</i> inherit that variable
455 value, if it doesn't define the value itself.</p>
456
457
458 <h3> SetValue() and variants </h3>
459
460 <p>SetValue() is used to set the value for a variable
461 marker in a dictionary. It takes a string as input -- nominally a <A
462 HREF="#template_string"><code>TemplateString</code></A>, though a C++
463 string or C char* will be auto-converted -- for the variable name and
464 its value. The name is the same string as is used for the variable's
465 template-marker inside the template this dictionary will be expanded
466 with: if the template reads <code>Hello {{NAME}}</code> then the
467 first argument to <code>SetValue()</code> must be <code>NAME</code>.
468 Case matters.</p>
469
470 <p><code>SetIntValue()</code> takes an integer as the value, rather
471 than a string. On all platforms, the integer may be up to 64
472 bits.</p>
473
474 <p><code>SetFormattedValue()</code> is a convenience routine.
475 <code>SetFormattedValue(key, arg1, arg2, ...)</code> is logically
476 equivalent to</p>
477 <pre>
478 char buffer[A_BIG_ENOUGH_NUMBER];
479 sprintf(buffer, arg1, arg2, ...);
480 SetValue(key, buffer);
481 </pre>
482 <p>without having to worry about the size of <code>buffer</code>, or
483 about stack overflow.</p>
484
485 <p><code>SetValueWithoutCopy()</code> is provided to give an extra bit
486 of efficiency when needed. <code>SetValue()</code> will copy the key
487 and value into an internal data structure used by the
488 <code>TemplateDictionary</code>; this avoids dangling pointers if the
489 arguments to <code>SetValue()</code> are temporaries, or otherwise
490 have shorter lifetime than the <code>TemplateDictionary</code>. But
491 if you know that both the key and value strings have lifetime longer
492 than the <code>TemplateDictionary</code> -- perhaps because they are
493 global (static duration) <code>char*</code>'s -- you can call
494 <code>SetValueWIthoutCopy()</code> to avoid the copy. This yields a
495 small time savings at the cost of significant code fragility, so
496 should only be used when absolutely necessary.</p>
497
498
499 <h3> SetGlobalValue() and SetTemplateGlobalValue() </h3>
500
501 <p><code>SetGlobalValue()</code> is like <code>SetValue()</code> but
502 works on the global dictionary. Since the global dictionary is shared
503 across all template dictionaries, this is a static method on
504 <code>TemplateDictionary</code>. It is thread-safe. It is also
505 relatively slow.</p>
506
507 <p><code>SetTemplateGlobalValue()</code> is like
508 <code>SetValue()</code>, but the values are preserved across
509 template-includes.</p>
510
511 <p>This example shows all three forms:</p>
512 <pre>
513 A.tpl:
514 {{NAME}} has won {{>PRIZE}}. It is worth {{AMOUNT}}.
515 B.tpl:
516 {{AMOUNT}} dollars! And it's all yours, {{NAME}}
517 C.tpl:
518 To: {{NAME}}. Amount: {{AMOUNT}}.
519 code:
520 ctemplate::TemplateDictionary dict("set_value_demo");
521 ctemplate::TemplateDictionary* subdict = dict.AddIncludeDictionary("PRIZE");
522 subdict->SetFilename("B.tpl");
523 dict->SetValue("NAME", "Jane McJane");
524 dict->SetTemplateGlobalValue("AMOUNT", "One Million");
525 ctemplate::TemplateDictionary::SetGlobalValue("NAME", "John Doe");
526 ctemplate::TemplateDictionary dict_c("set_value_demo, part 2");
527
528 ctemplate::ExpandTemplate("A.tpl", ..., &amp;dict);
529 ctemplate::ExpandTemplate("C.tpl", ..., &amp;dict_c);
530 </pre>
531
532 <p>The first expand yields this:</p>
533 <pre>
534 Jane McJane has won One Million dollars! And it's all yours, John Doe. It is worth One Million.
535 </pre>
536
537 <p>The second expand yields this:</p>
538 <pre>
539 To: John Doe. Amount: .
540 </pre>
541
542 <p><code>NAME</code> was set via <code>SetValue()</code>, so its
543 value was not propagated across the include-dict boundary; instead,
544 the subdict (B.tpl) got its value for <code>NAME</code> from the
545 global dictionary. <code>AMOUNT</code>, on the other hand, was set
546 via <code>SetTemplateGlobalValue()</code>, so its value was propagated
547 across the boundary, and the subdict saw it. However, the totally
548 unrelated template, C.tpl, did not see either value, and only sees the
549 values in the global dictionary. (Of course, had we filled
550 <code>dict_c</code> with some values, C.tpl would have had access to
551 those.)</p>
552
553
554 <h3> AddSectionDictionary(), ShowSection(),
555 and SetValueAndShowSection() </h3>
556
557 <p><code>AddSectionDictionary(section_name)</code> returns a
558 sub-dictionary associated with the given section_name (for instance,
559 <code>dict.AddSectionDictionary("MYSECT")</code> for a template like
560 <code>{{#MYSECT}}...{{/MYSECT}}</code>). If called multiple times, it
561 will return a new dictionary each time. During <code>Expand()</code>,
562 the section will be expanded once for each time
563 <code>AddSectionDictionary()</code> was called; that is, the text
564 inside the section delimiters will be repeated once for each
565 <code>AddSectionDictionary()</code> call, and within a single
566 repetition, the dictionary returned by
567 <code>AddSectionDictionary()</code> will be used to populate the text
568 inside the section delimiters. (With the current dictionary as that
569 dictionary's parent, for inheritance purposes.)</p>
570
571 <p>This suggests that if <code>AddSectionDictionary()</code> is never
572 called on a section, the text inside the section will be omitted
573 entirely by <code>Expand()</code>.</p>
574
575 <p><code>ShowSection()</code> is a convenience method used to show the
576 text inside the section exactly once. It is equivalent to calling
577 <code>AddSectionDictionary()</code> once, and ignoring the returned
578 sub-dictionary. All variables in the section will depend on
579 dictionary inheritence to get their values.</p>
580
581 <p><code>SetValueAndShowSection()</code> is another convenience
582 method,, used to show a section if and only if a related variable is
583 set to a non-empty value. <code>SetValueAndShowSection(name, value,
584 section_name)</code> is equivalent to this: if value is empty do
585 nothing, otherwise add a single dictionary to
586 <code>section_name</code> and call <code>section_dict->AddValue(name,
587 value)</code>.</p>
588
589 <p>Example:</p>
590 <pre>
591 ctemplate::TemplateDictionary* dict = new ctemplate::TemplateDictionary("section example");
592 const char* username = GetUsername(); // returns "" for no user
593 if (username[0] != '\0') {
594 ctemplate::TemplateDictionary* sub_dict = dict->AddSectionDictionary("CHANGE_USER");
595 sub_dict->SetValue("USERNAME", username);
596 } else {
597 // don't need to do anything; we want a hidden section, which is the default
598 }
599
600 // Instead of the above 'if' statement, we could have done this:
601 if (username[0] != '\0') {
602 dict->ShowSection("CHANGE_USER"); // adds a single, empty dictionary
603 dict->SetValue("USERNAME", username); // take advantage of inheritance
604 } else {
605 // don't need to do anything; we want a hidden section, which is the default
606 }
607
608 // Or we could have done this:
609 dict->SetValueAndShowSection("USERNAME", username, "CHANGE_USER");
610
611 // Moving on...
612 GetPrevSearches(prev_searches, &amp;num_prev_searches);
613 if (num_prev_searches > 0) {
614 for (int i = 0; i < num_prev_searches; ++i) {
615 TemplateDictionary* sub_dict = dict->AddSectionDictionary("PREV_SEARCHES");
616 sub_dict->SetValue("PREV_SEARCH", prev_searches[i]);
617 }
618 }
619 </pre>
620
621
622 <h3> AddIncludeDictionary() and SetFilename() </h3>
623
624 <p><code>AddIncludeDictionary(section_name)</code> returns a
625 sub-dictionary associated with the given include_name (for instance,
626 <code>dict.AddIncludeDictionary("MYTPL")</code> for a template like
627 <code>{{>MYTPL}}</code>). If called multiple times, it
628 will return a new dictionary each time. It is the responsibility of
629 the caller to then call <code>SetFilename()</code> on the
630 sub-dictionary returned.</p>
631
632 <p>During <code>Expand()</code>,
633 each dictionary returned by <code>AddIncludeDictionary</code> will be
634 examined in turn. For each dictionary for which
635 <code>SetFilename()</code> is called, that filename will be read as a
636 template (via <code>LoadTemplate()</code>, with the same
637 "strip" value as the current template), and expanded using the
638 dictionary. (Note that the dictionary will not inherit
639 <code>SetValue()</code> values from the parent dictionary, though it
640 will inherit <code>SetTemplateGlobalValue()</code> values.) This
641 expanded template will then be emitted to the output.</p>
642
643 <p>Note that if <code>AddIncludeDictionary()</code> is never called,
644 the template-include will be a no-op during <code>Expand()</code>.
645 Likewise, if it is called but <code>SetFilename()</code> is never
646 called on the resulting sub-dictionary, the template-include will be a
647 no-op. On the other hand, if it is called multiple times, multiple
648 templates -- possibly all from the same file, possibly not -- will be
649 inserted at the point of the template-include.</p>
650
651 <p>If a user has called <code>StringToTemplateCache(key, ...)</code>,
652 then the user can call <code>SetFilename(key)</code> to include the
653 contents of the string as the sub-template.</p>
654
655
656 <h3> Dump() and DumpToString() </h3>
657
658 <p>These routines dump the contents of a dictionary and its
659 sub-dictionaries. <code>Dump()</code> dumps to stdout,
660 <code>DumpToString()</code> to a string. They are intended for
661 debugging.</p>
662
663
664 <h2> <A NAME="template_cache">The <code>TemplateCache</code> Class</A> </h2>
665
666 <p>This class holds a collection of templates. It can be used to give
667 you a coherent view of the template system: you load all the templates
668 you are going to use into the cache, and then reload them from disk in
669 one atomic operation. You can have multiple
670 <code>TemplateCache</code> objects in your executable, perhaps one for
671 each service you provide, or perhaps one per thread (so as to avoid
672 thread contention when loading templates).</p>
673
674 <p>One intended use of the template cache is to make it safe to reload
675 template files while serving user requests from a webserver. The idea
676 is that every user request, as it's created, is associated with the
677 current template cache. When you wish to reload, you
678 <code>Clone()</code> the current cache, and then reload inside the
679 cloned copy. New requests will get the cloned cache, while old
680 requests will continue to render using the old cache.
681 <code>TemplateCache</code> is written to make this use-case efficient:
682 templates are shared between caches when appropriate, with
683 reference-counting to keep memory management easy.</p>
684
685
686 <h3> The default template cache </h3>
687
688 <p>The template system creates a default template cache, which is
689 available via the functions <code>default_template_cache()</code> and
690 <code>mutable_default_template_cache()</code>.</p>
691
692 <p>For simple uses of the template system, using the default cache,
693 via <code>ExpandTemplate()</code> and the like, may be perfectly
694 adequate. If you want more sophisticated features, such as the
695 ability to have different versions of the same template file active at
696 one time, or to change the template root-directory, you will have to
697 use an explicit <code>TemplateCache</code>.</p>
698
699
700 <h3> LoadTemplate() and StringToTemplateCache() </h3>
701
702 <p>These two routines are how you explicitly insert data into the
703 cache. <code>LoadTemplate()</code> reads a template from disk, while
704 <code>StringToTemplateCache()</code> takes the data from a
705 user-specified string. These work exactly the same as the global <A
706 HREF="#load_template"><code>LoadTemplate()</code></A> and <A
707 HREF="#string_to_template_cache"><code>StringToTemplateCache()</code></A>,
708 except they insert into the given <code>TemplateCache</code>, rather
709 than the global cache.</p>
710
711 <p><code>LoadTemplate()</code> is not strictly necessary: if the cache
712 cannot find a template it needs at <code>Expand*()</code> time, it will
713 automatically try to fetch it from disk. It is intended mostly for
714 use with <A HREF="#freeze"><code>Freeze()</code></A>, which disables
715 this auto-fetch behavior.</p>
716
717 <p>Both of these routines take a <A HREF="#strip">strip</A> mode
718 specifying how the template system should treat whitespace while
719 parsing.</p>
720
721 <p>If the template-cache is <A HREF="#freeze">frozen</A>,
722 <code>LoadTemplate()</code> will only return true if the template is
723 already stored in the cache, and will return false in every other
724 case. For a frozen cache, <code>StringToTemplateCache()</code> will
725 always return false.</p>
726
727
728 <h3> ExpandWithData() and ExpandFrozen() </h3>
729
730 <p>These routines takes a string that represents either a template
731 filename (for disk-based templates), or a key used in
732 <code>StringToTemplateCache()</code> (for string-based templates), a <A
733 HREF="#strip">strip</A> mode saying how to parse the template's
734 whitespace, and <A HREF="#per_expand_data">per-expand data</A> (which
735 can be NULL). Overloads are provided to output the expanded template
736 to either a string or to an arbitrary <A
737 HREF="#expand_emitter"><code>ExpandEmitter</code></A>.</p>
738
739 <p>Expand uses the filename + strip pair to fetch the template from
740 the cache, if it's there. If not, <code>ExpandWithData()</code> will
741 fetch the template from disk and insert it into the cache.
742 <code>ExpandFrozen()</code>, on the other hand, will just fail to
743 expand, and return false. This is the only difference in behavior
744 between the two routines. To reinforce this behavior,
745 <code>ExpandFrozen()</code> will return false immediately if <A
746 HREF="#freeze"><code>Freeze()</code></A> has not been called on the
747 cache.
748
749 <p>While expanding, the template system may come across template
750 sub-includes (<code>{{>SUB_TEMPLATE}}</code>). It will attempt to
751 fetch these templates from the cache as well; failing that, it will
752 try to load the template from disk (for <code>ExpandWithData()</code>)
753 or else fail the expand and return false (for
754 <code>ExpandFrozen()</code>).</p>
755
756 <p>Because <code>ExpandFrozen()</code> never updates the cache, it is
757 a const method, unlike <code>ExpandWithData()</code>.</p>
758
759 <p>Note that <code>TemplateCache</code> does not provide the
760 convenience <code>ExpandTemplate()</code> routine, as the analogue of
761 the global <A
762 HREF="#expand_template"><code>ExpandTemplate()</code></A>. If you are
763 not interested in the per-expand data, just call
764 <code>ExpandWithData()</code> with the per-expand data set to NULL.</p>
765
766
767 <h3> ReloadAllIfChanged() </h3>
768
769 <p>For every file-based template in the cache (this method ignores
770 string-based templates), <code>ReloadAllIfChanged()</code> checks the
771 filesystem to see if the file has changed since it was loaded into the
772 cache. If so, the cache loads a new version of the file into the
773 cache. Note that at this point both the old and new versions of the
774 file exist in the cache! Only the new version is accessible via new
775 calls to <code>Expand()</code>, but any expansions currently in flight
776 during the <code>ReloadAllIfChanged()</code> call will continue to use
777 the old version.</p>
778
779 <p>NOTE: <code>ReloadAllIfChanged()</code> never modifies existing
780 items in the cache in any way. It only loads new entries into the
781 cache.</p>
782
783 <p><code>ReloadAllIfChanged()</code> comes in two flavors, controlled
784 by the passed-in enum. In "immediate" mode, it synchronously iterates
785 through the cache and reloads all files that need it. In "lazy" mode,
786 it waits to reload a given template file until the next time it's
787 actually used (in a call to <code>Expand*()</code>). "Immediate" mode
788 is safer in the case where templates depend on each other and the
789 files change a lot, since all files are reloaded at about the same
790 time. "Lazy" mode avoids the latency spike of "immediate" mode, and
791 is preferable in the (common) case that files on disk change only
792 rarely.</p>
793
794
795 <h3> <A NAME="search_path"> SetTemplateRootDirectory(),
796 AddAlternateTemplateRootDirectory(), and
797 template_root_directory() </A> </h3>
798
799 <p>By default, filenames passed in to <code>Expand*()</code> are taken
800 to be relative to the current working directory. These functions
801 change that behavior. <code>SetTemplateRootDirectory()</code> resets
802 the search path to be the single path passed in to this function.
803 Every time <code>AddAlternateTemplateRootDirectory()</code> is called,
804 it adds another directory to the end of the search path. The template
805 system will follow the search path, in order, when looking for a
806 filename.</p>
807
808 <p>Note that the template search path is only meaningful when the
809 filename passed to <code>Expand*()</code> (or specified for a
810 sub-include) is a relative filename. If the filename is an absolute
811 filename, starting with <code>/</code>, the search path is
812 ignored.</p>
813
814 <p><code>template_root_directory()</code> returns the first entry in
815 the search path. There is currently no way to access other entries in
816 the search path.</p>
817
818
819 <h3> FindTemplateFilename() </h3>
820
821 <p><code>FindTemplateFilename()</code> does the work of finding a
822 template file in the filesystem, using the current template search
823 path. It takes a relative pathname as input, and returns an absolute
824 pathname as output, indicating where the template file lives on the
825 filesystem. If the template file is not found, this method returns
826 the empty string.</p>
827
828
829 <h3> <A NAME="freeze">Freeze()</A> </h3>
830
831 <p><code>Freeze()</code> marks the template cache as immutable. After
832 this method is called, the cache can no longer be modified by loading
833 new templates or reloading existing templates. During expansion only
834 cached included templates will be used; they won't be loaded
835 on-demand.</p>
836
837 <p>Before calling <code>Freeze()</code>, you should make sure your
838 cache has all the templates it might need, using
839 <code>LoadTemplate()</code> and <code>StringToTemplateCache()</code>.
840 Otherwise, <code>ExpandWithData()</code> and
841 <code>ExpandFrozen()</code> may fail.</p>
842
843 <p>Once the cache is frozen, calls to
844 <code>SetTemplateRootDirectory()</code>,
845 <code>AddAlternateTemplateRootDirectory()</code>,
846 <code>Delete()</code>, and <code>ReloadAllIfChanged()</code> will
847 fail.</p>
848
849 <p>After the cache is frozen, the <code>TemplateCache</code> object is
850 effectively const.</p>
851
852
853 <h3> Delete() </h3>
854
855 <p>This method deletes an entry from the cache. If the entry is in
856 the cache multiple times (each with a different "strip" mode), this
857 method deletes all of them.</p>
858
859
860 <h3> ClearCache() </h3>
861
862 <p>This method deletes all entries from the cache. It can be called
863 even on a frozen cache.</p>
864
865 <p>Note: this method is not typically necessary unless you are testing
866 for memory leaks. It is intended to be called just before exiting the
867 program, and after all template expansions are completed. Using it in
868 that way may prevent unnecessary reporting by the leak checker.</p>
869
870
871 <h3> Clone() </h3>
872
873 <p><code>Clone()</code> makes a shallow copy of the given
874 <code>TemplateCache</code> object, and returns the copy. The new copy
875 and the old share the same template objects; since it's a shallow
876 copy, they actually share pointers to the exact same object. (Since
877 the template cache never changes a template object once it's loaded
878 into the cache, sharing the pointer isn't a risk.)</p>
879
880 <p>The intended use of <code>Clone()</code>, as described above, is to
881 allow fine control over "epochal" changes in templates. One
882 <code>TemplateCache</code> can hold all versions of the template files
883 before the big update; after the update is done, you can clone the old
884 cache and then call <code>ReloadAllIfChanged()</code> on the clone.
885 This is a low-cost operation, since the two copies share most
886 resources. Smart pointers take care of most memory management
887 issues.</p>
888
889 <p>The caller is responsible for calling <code>delete</code> on the
890 returned <code>TemplateCache</code> object.</p>
891
892
893
894 <h2> <A NAME="template_namelist">The <code>TemplateNamelist</code> Class</A> </h2>
895
896 <p>This class provides information about <A
897 HREF="guide.html#register">registered</A> templates. Or more
898 precisely, all templates corresponding to registered filenames.</p>
899
900 <p>All methods in this class are static.</p>
901
902
903 <h3> RegisterTemplate() and
904 RegisterTemplateFilename() </h3>
905
906 <p><code>TemplateNamelist::RegisterTemplate()</code> takes a filename
907 and adds it to the static namelist used by
908 <code>TemplateNamelist</code>. All other methods of
909 <code>TemplateNamelist</code> work only on registered filenames.</p>
910
911 <p>It's fairly rare to call this method directly. Instead, the more
912 common use is to use the macro <code>RegisterTemplateFilename</code>
913 somewhere in the global scope, like so:</p>
914 <pre>
915 RegisterTemplateFilename(EXAMPLE_FN, "example.tpl");
916 </pre>
917
918 <p>The reason to prefer the macro is it defines a global variable that
919 you can use instead of the hard-coded template name. This helps catch
920 typos. The <code>RegisterTemplateFilename()</code> example is
921 functionally equivalent to:</p>
922 <pre>
923 #define EXAMPLE_FN "example.tpl"
924 </pre>
925
926 <p>It can be used like this:</p>
927 <pre>
928 ctemplate::ExpandTemplate(EXAMPLE_FN, ctemplate::DO_NOT_STRIP, ...);
929 </pre>
930
931
932 <h3> GetMissingList() </h3>
933
934 <p><code>TemplateNamelist::GetMissingList()</code> returns a list of
935 all registered templates (or rather, all filenames) where the file
936 could not be found on disk.</p>
937
938
939 <h3> AllDoExist() </h3>
940
941 <p>Returns true if and only if the missing-list is empty.</p>
942
943
944 <h3> GetBadSyntax() </h3>
945
946 <p>Returns a list of all registered templates where the template
947 contains a syntax error, and thus cannot be used.</p>
948
949
950 <h3> IsAllSyntaxOkay() </h3>
951
952 <p>True if and only if the bad-syntax list is empty.</p>
953
954
955 <h3> GetLastmodTime() </h3>
956
957 <p>Returns the latest last-modified time for any registered
958 template-file.</p>
959
960
961 <h2> <A NAME="template_modifier">The TemplateModifier Class</A>
962 and Associated Functions</h2>
963
964 <p>A modifier is a filter that's applied at template-expand time, that
965 munges the value of the variable before it's output. For instance,
966 <code>&lt;html&gt;&lt;body&gt;{{NAME:html_escape}}&lt;/body&gt;&lt;/html&gt;</code>
967 asks the template system to apply the built-in
968 <code>html_escape</code> modifier when expanding
969 <code>{{NAME}}</code>. If you set <code>NAME</code> in your
970 dictionary to be <code>Jim &amp; Bob</code>, what will actually be
971 emitted in the template is <code>Jim &amp;amp; Bob</code>.</p>
972
973 <p>You can chain modifiers together. This template first html-escapes
974 <code>NAME</code>, and then javascript-escapes that result:</p>
975 <pre>
976 &lt;html&gt;&lt;body&gt;{{NAME:html_escape:javascript_escape}}&lt;/body&gt;&lt;/html&gt;
977 </pre>
978
979 <p>Modifiers typically have a long, descriptive name and also a
980 one-letter abbreviation. So this example is equivalent to the
981 previous one:</p>
982 <pre>
983 &lt;html&gt;&lt;body&gt;{{NAME:h:j}}&lt;/body&gt;&lt;/html&gt;
984 </pre>
985
986 <p>Some modifiers take an argument, specified after an equals
987 sign:</p>
988 <pre>
989 &lt;html&gt;&lt;body&gt;{{NAME:html_escape_with_arg=pre}}&lt;/body&gt;&lt;/html&gt;
990 </pre>
991
992
993 <h3> Built-in Modifiers </h3>
994
995 <p>Here are the modifiers that are built in to the template system.
996 They are all defined in template_modifiers.cc:</p>
997
998 <table border="1" cellpadding="3" summary="List of built-in modifiers">
999 <tr><th>long name</th><th>short name</th><th>description</th></tr>
1000
1001 <tr><td><code>:cleanse_css</code></td><td><code>:c</code></td>
1002 <td>Removes characters not safe for a CSS value. Safe characters
1003 are alphanumeric, space, underscore, period, coma, exclamation
1004 mark, pound, percent, and dash.</td>
1005 </tr>
1006
1007 <tr><td><code>:html_escape</code></td><td><code>:h</code></td>
1008 <td>html-escapes the variable before output
1009 (eg <code>&amp;</code> -> <code>&amp;amp;</code>)</td>
1010 </tr>
1011
1012 <tr><td><code>:html_escape_with_arg</code></td><td><code>:H</code></td>
1013 <td>special purpose html escaping. See
1014 <a href="#html_escape_args">:H Arguments</a>
1015 below for details.</td>
1016 </tr>
1017
1018 <tr><td><code>:img_src_url_escape_with_arg</code></td><td><code>:I</code></td>
1019 <td>special purpose image url escaping. See
1020 <a href="#url_escape_args">:I and :U Arguments</a>
1021 below for details.</td>
1022 </tr>
1023
1024 <tr><td><code>:javascript_escape</code></td><td><code>:j</code></td>
1025 <td>javascript-escapes the variable before output (eg
1026 <code>&quot;</code> -> <code>\x27</code> and
1027 <code>&amp;</code> -> <code>\x26</code>)</td>
1028 </tr>
1029
1030 <tr><td><code>:javascript_escape_with_arg</code></td><td><code>:J</code>
1031 </td>
1032 <td>special purpose javascript escaping. See
1033 <a href="#javascript_escape_args">:J Arguments</a>
1034 below for details.</td>
1035 </tr>
1036
1037 <tr><td><code>:json_escape</code></td><td><code>:o</code></td>
1038 <td>json-escapes a variable before output as a string in json;
1039 HTML characters are escaped using Unicode escape sequences
1040 (e.g <code>&amp;</code> -> <code>\u0026</code>) to comply with
1041 <a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
1042 </td>
1043 </tr>
1044
1045 <tr><td><code>:none</code></td><td></td>
1046 <td>leaves the variable as is (used to disable <A
1047 HREF="#auto_escape">auto-escaping</A>)</td>
1048 </tr>
1049
1050 <tr><td><code>:pre_escape</code></td><td><code>:p</code></td>
1051 <td>pre-escapes the variable before output (same as html_escape but
1052 whitespace is preserved; useful for &lt;pre&gt;...&lt;/pre&gt;)</td>
1053 </tr>
1054
1055 <tr><td><code>:url_escape_with_arg</code></td><td><code>:U</code></td>
1056 <td>special purpose url escaping. See
1057 <a href="#url_escape_args">:I and :U Arguments</a>
1058 below for details.</td>
1059 </tr>
1060
1061 <tr><td><code>:url_query_escape</code></td><td><code>:u</code></td>
1062 <td>performs URL escaping on the variable before output.
1063 space is turned into +, and everything other than [0-9a-zA-Z.,_:*/~!()-], is
1064 transformed into %-style escapes. Use this when you are building
1065 URLs with variables as parameters:
1066 <pre>&lt;a href="http://google.com/search?q={{QUERY:u}}"&gt;{{QUERY:h}}&lt;/a&gt;</pre>
1067 </td>
1068 </tr>
1069
1070 <tr><td><code>:xml_escape</code></td><td></td>
1071 <td>xml-escapes the variable before output
1072 (the five characters <code>&lt;&gt;&amp;&quot;&#39;</code> become
1073 <code>&amp;lt&amp;gt;&amp;amp;&amp;quot;&amp;#39;</code>)
1074 suitable for content returned in raw XML. It is not intended
1075 for escaping content within CDATA blocks.</td>
1076 </tr>
1077
1078 </table>
1079
1080 <p>The <code>*_with_arg</code> modifiers require an argument to
1081 specify the type of escaping to use. The following sections list
1082 the supported arguments for each of these modifiers.
1083
1084 <h4 id="html_escape_args">:H Arguments</h4>
1085 <p>Here are the values that are supported by
1086 the <code>html_escape_with_arg</code> modifier:</p>
1087 <table border="1" cellpadding="3" summary="Arguments for :H modifier">
1088 <tr><th>value</th><th>description</th></tr>
1089
1090 <tr><td><code>=snippet</code></td>
1091 <td>like <code>html_escape</code>, but allows HTML entities and
1092 some tags to pass through unchanged. The allowed tags
1093 are <code>&lt;br></code>, <code>&lt;wbr></code>, <code>&lt;b></code>,
1094 and <code>&lt;/b></code>.</td>
1095 </tr>
1096
1097 <tr><td><code>=pre</code></td>
1098 <td>same as <code>pre_escape</code></td>
1099 </tr>
1100
1101 <tr><td><code>=url</code></td>
1102 <td>same as <code>:U=html</code> below. For backwards compatibility.</td>
1103 </tr>
1104
1105 <tr><td><code>=attribute</code></td>
1106 <td>replaces characters not safe for an use in an unquoted
1107 attribute with underscore. Safe characters are alphanumeric,
1108 underscore, dash, period, and colon.</td>
1109 </tr>
1110
1111 </table>
1112
1113 <h4 id="url_escape_args">:I and :U Arguments</h4>
1114 <p>Here are the values that are supported by
1115 the <code>img_src_url_escape_with_arg</code> and
1116 <code>url_escape_with_arg</code> modifiers:</p>
1117 <table border="1" cellpadding="3" summary="Arguments for :I and :U modifiers">
1118 <tr><th>value</th><th>description</th></tr>
1119
1120 <tr><td><code>=html</code></td>
1121 <td>Ensures that a variable contains a safe URL. Safe means that
1122 it is either a http or https URL, or else it has no protocol
1123 specified.
1124 <ul>
1125 <li>If the URL is safe, the modifier HTML-escapes the URL.
1126 <li>Otherwise, the modifier replaces the unsafe URL with one of the
1127 following values:
1128 <ul>
1129 <li><code>/images/cleardot.gif</code> (the <code>:I</code>
1130 modifier)
1131 <li><code>#</code> (the <code>:U</code> modifier)
1132 </ul>
1133 </li>
1134 </ul>
1135 <b>Do not use <code>:U</code> for image URLs.</b> Use <code>:I</code>
1136 instead. <code>#</code> is not a safe replacement for an image URL.
1137 <code>&lt;img src=#&gt;</code> can cause each browser to request the
1138 entire page again.
1139 </td>
1140 </tr>
1141
1142 <tr><td><code>=javascript</code></td>
1143 <td>Same as <code>=html</code>, but using javascript escaping
1144 instead of html escaping.</td>
1145 </tr>
1146
1147 <tr><td><code>=css</code></td>
1148 <td>Same as <code>=html</code> but using CSS escaping instead
1149 of html escaping so that the variable can be safely inserted
1150 within a CSS <code>@import</code> statement or a CSS property.
1151 The characters in [\r\n()&#39;&quot;&lt;&gt;*\] are transformed
1152 into %-style escapes.</td>
1153 </tr>
1154
1155 <tr><td><code>=query</code></td>
1156 <td>(Supported for <code>:U</code> only) Same as
1157 <code>url_query_escape</code>.</td>
1158 </tr>
1159
1160 </table>
1161
1162 <h4 id="javascript_escape_args">:J Arguments</h4>
1163 <p>Here are the values that are supported by
1164 the <code>javascript_escape_with_arg</code> modifier:</p>
1165 <table border="1" cellpadding="3" summary="Arguments for :J modifier">
1166 <tr><th>value</th><th>description</th></tr>
1167
1168 <tr><td><code>=number</code></td>
1169 <td>Ensures that the variable is a valid number or boolean
1170 javascript literal. This includes booleans
1171 <code>true</code> and <code>false</code>, decimal
1172 numbers (e.g. <code>4.10</code> or <code>-5.01e+10</code>)
1173 as well as hex numbers (e.g. <code>0x5FF</code>). This modifier
1174 is intended to ensure the variable not enclosed in
1175 quotes cannot contain javascript code that may execute. It does
1176 not guarantee that the variable is syntactically well-formed.
1177 If the variable is safe, it is returned
1178 as-is, otherwise it is replaced with <code>null</code>.
1179 In the future we may add more logic to support objects and
1180 arrays.</td>
1181 </tr>
1182 </table>
1183
1184 <h3> Custom Modifiers </h3>
1185
1186 <p>In addition to the built-in modifiers, you can write your own
1187 modifier. Custom modifiers must have a name starting with "x-", and
1188 the name can contain alphanumeric characters plus dashes and
1189 underscores. Custom modifiers can also accept values with any
1190 character except for : and <code>}</code>. For example
1191 this template could be a valid use of a custom modifier:</p>
1192
1193 <pre>
1194 {{VAR:x-my_modifier:value1,value2,value3 has spaces,etc}}
1195 </pre>
1196
1197 <p>See <code>&lt;template_modifiers.h&gt;</code> for details on how to
1198 write a modifier and how to register it. In short, you write a
1199 modifier by subclassing <code>ctemplate::TemplateModifier</code> and
1200 overriding the <code>Modify</code> method, and you register it by
1201 calling <code>ctemplate::AddModifier()</code> Here is an example of
1202 the code for a custom modifier:</p>
1203 <pre>
1204 class StarEscape : public ctemplate::TemplateModifier {
1205 void Modify(const char* in, size_t inlen,
1206 const ctemplate::PerExpandData* per_expand_data,
1207 ctemplate::ExpandEmitter* outbuf, const string&amp; arg) const {
1208 outbuf->Emit(string("*") + string(in, inlen) + string("*"));
1209 }
1210 };
1211 </pre>
1212
1213
1214 <h3> Subclassing TemplateModifier </h3>
1215
1216 <p>The minimum work to create a custom modifier is to subclass
1217 <code>TemplateModifier</code> and override the <code>Modify()</code>
1218 method. <code>Modify()</code> takes as input the value of the text to
1219 be modified, as well as the <A HREF="#per_expand_data">per expand
1220 data</A> associated with this <code>Expand()</code> call. The method
1221 may use this input, plus any other data it may have, to generate
1222 output, which it should write into the given
1223 <code>ExpandEmitter</code>.</p>
1224
1225 <p>The subclass can also override <code>MightModify()</code>. This is
1226 useful for modifiers that are typically a no-op (in which case the
1227 modifier is just doing busy-work, copying its input to the output
1228 <code>ExpandEmitter</code>). If <code>MightModify()</code> returns
1229 false, the template system will avoid calling <code>Modify()</code> at
1230 all on that variable, avoiding the busy-work copy.</p>
1231
1232
1233 <h3> AddModifier() </h3>
1234
1235 <p> AddModifier() is used to register a custom modifier,
1236 so the modifier can be used in templates. The name of the modifier
1237 must start with <code>x-</code>. </p>
1238
1239
1240 <h3> AddXssSafeModifier() </h3>
1241
1242 <p> <code>AddXssSafeModifier()</code> is used to register a custom
1243 modifier that can work well with the <A
1244 HREF="auto_escape.html">auto-escape system</A>. It is used when the
1245 modifier produces output that is "safe" from cross-site scripting
1246 attacks in all contexts in which it might be used. For instance, a
1247 modifier that only emits numbers is xss-safe if it's only used in html
1248 or javascript contexts.</p>
1249
1250
1251 <h3> <A NAME="auto_escape">Auto-escaping and Manual Escaping</A> </h3>
1252
1253 <p>If the <A HREF="auto_escape.html">auto-escape pragma</A> is used
1254 in a document, then all variables will be auto-escaped, even if
1255 explicit modifiers are used on the variable. The rules are a little
1256 complicated:</p>
1257
1258 <ul>
1259 <li> If the explicit modifier is a built-in modifier, and that
1260 modifier is "compatible" with the modifier that auto-escape
1261 would perform ("compatible" means it safely escapes in at least
1262 as many contexts as the auto-escape modifier), then only the
1263 explicit modifier is applied, and no further auto-escaping is
1264 done. </li>
1265
1266 <li> If the explicit modifier is a custom modifier registered using
1267 AddXssSafeModifier(), no further auto-escaping is
1268 done. </li>
1269
1270 <li> If the explicit modifier is the :none modifier, no
1271 further auto-escaping is done. This is the mechanism for
1272 manually turning off auto-escaping. </li>
1273
1274 <li> In all other situations, auto-escaping will be performed after
1275 the explicit modifiers have all run. </li>
1276 </ul>
1277
1278
1279 <h2> <A NAME="per_expand_data">The <code>PerExpandData</code> Class</A> </h2>
1280
1281 <p><code>ExpandWithData()</code> and
1282 <code>TemplateModifier::Modify()</code> both take a
1283 <code>PerExpandData</code> object. Per-expand data is applied to all
1284 templates that are seen while expanding: not only the template you
1285 called <code>ExpandWithData()</code> on, but also sub-templates that
1286 are brought in via template-includes (<code>{{&gt;INCLUDE}}</code>).
1287
1288 <p>There are several types of per-expand data you can set, by calling
1289 the appropriate method on a <code>PerExpandData</code> object.</p>
1290
1291
1292 <h3> SetAnnotateOutput() </h3>
1293
1294 <p>This is a debugging function. When expanding this template, it adds
1295 marker-strings to the output to indicate what template-substitutions
1296 the system made. This takes a string argument which can be used to
1297 shorten the filenames printed in the annotations: if the filename
1298 contains the string you give, everything before that string is elided
1299 from the filename before printing. (It's safe to just always pass in
1300 the empty string.)</p>
1301
1302
1303 <h3> SetAnnotator() </h3>
1304
1305 <p>This overrides the default text-based annotation used by
1306 <code>SetAnnotateOutput()</code>. If this is set and
1307 <code>SetAnnotateOutput()</code> is called, the per-expand data will
1308 use this <A
1309 HREF="#template_annotator"><code>TemplateAnnotator</code></A> instance
1310 to do the annotation, rather than the default instance.</p>
1311
1312
1313 <h3> InsertForModifiers() and LookupForModifiers() </h3>
1314
1315 <p><code>InsertForModifiers()</code> stores an arbitrary key/value
1316 pair in the <code>PerExpandData</code> structure. This is used with
1317 <A HREF="#template_modifier">template modifiers</A>: the
1318 <code>PerExpandData</code> object passed to
1319 <code>ExpandWithData()</code> is made available to every template
1320 modifier that is called during expand time (including any custom
1321 modifiers). The intended use of this functionality is to allow a
1322 modifier to work one way when expanding a template with dictionary A,
1323 and another way when expanding a template with dictionary B. For
1324 instance, a modifier might encrypt part of a webpage using a user's
1325 secret-key, which is of course different for every expansion of the
1326 webpage.</p>
1327
1328 <p><code>LookupForModifiers()</code> can be used by a
1329 template-modifier to read the key/value pair inserted by
1330 <code>InsertForModifiers()</code>.
1331 <code>LookupForModifiersAsString()</code> is the same, but returns the
1332 value as a char* rather than a void*, for convenience.</p>
1333
1334
1335 <h3> SetTemplateExpansionModifier() </h3>
1336
1337 <p>This is an advanced feature for those who need a custom hook into
1338 template expansion. It will not be used by most programmers. It
1339 takes a template-modifier as its argument, but this template modifier
1340 is treated specially: instead of applying when an appropriate magic
1341 string appears in the text of a template, it applies every time a
1342 template is expanded during a call to <code>ExpandWithData()</code>.
1343 Note this means that it's called not only after the top-level
1344 template, that <code>ExpandWithData()</code> is called on, is
1345 expanded, but also on every sub-template that is expanded due to a
1346 template-include.</p>
1347
1348 <p>This unusual functionality has a few unusual properties. Since the
1349 template expansion modifier is not called in normal fashion, the
1350 normal <code>arg</code> argument to the template modifier does not
1351 make sense. Instead, the <code>arg</code> is set to the path of the
1352 template which is being expanded. Also, template expansion modifiers
1353 can be expensive, since they are applied pretty indiscriminately, so
1354 it can be worth implementing the <code>MightModifiy()</code> predicate
1355 for the passed-in <code>TemplateModifier</code> to avoid unnecessary
1356 work.</p>
1357
1358
1359 <h2> <A NAME="template_annotator">The <code>TemplateAnnotator</code>
1360 Class</A> </h2>
1361
1362 <p>The <code>TemplateAnnotator</code> class is used to pass in to <A
1363 HREF="#per_expand_data"><code>PerExpandData::SetAnnotator()</code></A>,
1364 to control how expand-time annotation is done. This is meant to be
1365 used as a debugging routine.</p>
1366
1367 <p>This class is an abstract base class; <code>SetAnnotator()</code>
1368 takes a subclass that implements the various methods of the base
1369 class. These methods control the action taken when various template
1370 markers are seen during template expansion.</p>
1371
1372 <p><code>template_annotator.h</code> defines the abstract base class,
1373 and also a concrete subclass that is used by default for annotation if
1374 <code>SetAnnotator()</code> is not called.</p>
1375
1376
1377 <h2> <A NAME="template_dictionary_peer">The
1378 <code>TemplateDictionaryPeer</code> Class</A> </h2>
1379
1380 <p>By design, it is not possible to view the contents of a
1381 <code>TemplateDictionary</code>; we want to make sure the interface
1382 between the logic layer of the application and the presentation layer
1383 of the template goes in only one direction. While generally this
1384 keeps programs as clean as possible, it presents problems in testing
1385 code, which may want to verify that a given
1386 <code>TemplateDictionary</code> has been filled properly. The
1387 <code>TemplateDictionaryPeer</code> addresses this need. It lives in
1388 <code>template_test_util.h</code>.</p>
1389
1390 <p>Some of the methods of <code>TemplateDictionaryPeer</code> are
1391 useful for internal tests only. Below are some of the methods that
1392 are most useful for user-level tests.</p>
1393
1394
1395 <h3> STS_INIT_FOR_TEST </h3>
1396
1397 <p>This macro allows use of <code>STS_INIT</code> for testing, even
1398 when the input pointer is not guaranteed to be allocated for the
1399 entire length of the test (it must, of course, be allocated for the
1400 entire lifetime of the template being tested). Since normally
1401 <code>STS_INIT</code> requires inputs to have static duration, this
1402 allows for more flexibility in tests, at the cost of worse memory
1403 management and decreased code safety (in that it's possible to
1404 accidentally violate the lifetime requirements).</p>
1405
1406
1407 <h3> GetSectionValue() </h3>
1408
1409 <p>This returns the value for the named variable. It uses normal
1410 template scoping rules to resolve the name.</p>
1411
1412
1413 <h3> IsHiddenSection() and IsHiddenTemplate() </h3>
1414
1415 <p>Checks if a section or sub-template is "hidden" (that is, won't be
1416 displayed at all).</p>
1417
1418
1419 <h3> GetSectionDictionaries() and GetIncludeDictionaries() </h3>
1420
1421 <p>Returns all the sub-dictionaries for a given section or
1422 template-include, in a vector.</>
1423
1424
1425 <h3> Other Testing Functions </h3>
1426
1427 <p>template_test_util.h has other useful routines for
1428 testing, such as ExpandIs(), which tests whether a
1429 template + dictionary pair expands into an expected string. See the
1430 header file for details.</p>
1431
1432
1433 <h2> <A NAME="expand_emitter">The <code>ExpandEmitter</code> Class</A> </h2>
1434
1435 <p>There are two overloads of <A
1436 HREF="#expand_template"><code>ExpandTemplate()</code></A>: the first
1437 emits the expanded template to a C++ string, and the second emits to
1438 an <code>ExpandEmitter</code>: an abstract base class that serves as a
1439 data source. It supports just one overloaded method,
1440 <code>Emit()</code>, that can take a char, a char*, or a C++ string as
1441 input.</p>
1442
1443 <p>Using this class requires subclassing <code>ExpandEmitter</code>
1444 and providing the various definitions for <code>Emit()</code>. For
1445 instance, a subclass might provide definitions of <code>Emit()</code>
1446 that send the input bytes out to a network socket.</p>
1447
1448 <p>In addition to defining the abstract base class,
1449 <code>template_emitter.h</code> provides a sample concrete subclass
1450 implementation, for emitting to a string.</p>
1451
1452
1453 <h2> <A NAME="template_string">The <code>TemplateString</code> and
1454 <code>StaticTemplateString</code> Classes</A> </h2>
1455
1456 <p><code>TemplateString</code> is a string-like implementation.
1457 Ctemplate uses <code>TemplateString</code> almost exclusively,
1458 internally. Many of the public API methods, such as
1459 <code>TemplateDictionary::SetValue()</code>, also take
1460 <code>TemplateString</code> as input. <code>TemplateString</code>
1461 has implicit constructors for both C++ strings and char*'s, so every
1462 method that takes a <code>TemplateString</code> will also work if
1463 given a C++ string or a char*. If you have a char* and know its
1464 length, you can save a bit of work by explicitly constructing a
1465 <code>TemplateString</code> with a char* + length, for instance:</p>
1466 <pre>
1467 dict->SetValue(ctemplate::TemplateString("MYVAR", 5), value);
1468 </pre>
1469
1470 <p>Some compile-time tools work with <code>TemplateString</code> to
1471 offload computation from runtime to compile-time. This is possible
1472 because the Ctemplate code often stores a hash of a string
1473 rather than a string directly. For static, immutable strings,
1474 <code>TemplateString</code> can store a pre-computed hash value. This
1475 functionality is used by <A
1476 HREF="#make_tpl_varnames_h"><code>make_tpl_varnames_h</code></A>. Thus,
1477 using this tool to create constants to use for <code>SetValue()</code>
1478 keys provides not only protection against typos, but a speed
1479 improvement as well.</p>
1480
1481 <p>For immutable strings in your code, you can create efficient
1482 compile-time template-string objects of your own -- in this case of
1483 type <code>StaticTemplateString</code> -- by using the
1484 <code>STS_INIT</code> macro, like so:</p>
1485 <pre>
1486 static const StaticTemplateString kSectName =
1487 STS_INIT(kSectName, "test_SetAddSectionDictionary");
1488 </pre>
1489
1490 <p>The string variable's name, <code>kSectName</code> is repeated
1491 twice. The variable's value is specified inside the macro. Note that
1492 this macro should be used at the top level of a file, not inside
1493 functions (even when the variables are made static), and you should
1494 define the <code>StaticTemplateString</code> exactly as above:
1495 <code>static const StaticTemplateString</code>. Otherwise, the
1496 undefined constructor/destructor order of C++ may result in surprising
1497 behavior, wherein the <code>StaticTemplateString</code> is not
1498 initialized when it ought to be.</p>
1499
1500
1501 <h2> The <code>Template</code> Class </h2>
1502
1503 <p>In older version of ctemplate, the <code>Template</code> class,
1504 which holds parsed templates, was a major part of the template
1505 workflow: the common template use-case would be:</p>
1506 <pre>
1507 Template* tpl = Template::GetTemplate(filename, strip_mode);
1508 TemplateDictionary dict(name);
1509 tpl->Expand(&amp;dict, &amp;outstring);
1510 </pre>
1511
1512 <p>In current use, this model is deprecated in favor of the single
1513 <code>ExpandTemplate()</code> call; support for <code>Template</code>
1514 methods may be removed entirely in future versions of ctemplate.
1515 However, you may still find older code using this old formulation.</p>
1516
1517
1518 <h2> <A NAME="auto_escaping">Auto-Escaping</A> </h2>
1519
1520 <p>The <a href="auto_escape.html">Guide to using Auto Escape</a> has
1521 an overview of Auto Escape as well as discussion of its limitations.
1522 <!-- TODO(csilvers): move that information here? -->
1523 To use it, put the following text at the top of the template:</p>
1524 <pre>
1525 {{%AUTOESCAPE context="CONTEXT" [state="STATE"]}}
1526 </pre>
1527
1528 <p>Description of the arguments:</p>
1529 <ul>
1530 <li> The context attribute is one of <code>HTML</code>,
1531 <code>JAVASCRIPT</code>, <code>CSS</code>,
1532 <code>JSON</code> or <code>XML</code>. It must correspond
1533 to the context in which the browser will interpret this
1534 template. <b>Warning:</b> Setting the wrong context will
1535 result in wrong escaping applied to all variables in
1536 the given template. In particular, if the template starts with
1537 a <code>&lt;script&gt;</code> tag, its context is
1538 <code>HTML</code> and not <code>JAVASCRIPT</code>. Auto-Escape
1539 will recognize the <code>&lt;script&gt;</code> tag and hence
1540 properly Javascript-escape the variables within it. Similarly,
1541 if the template starts with a <code>&lt;style&gt;</code> tag,
1542 its context is <code>HTML</code> and not <code>CSS</code>.
1543 </li>
1544 <li> The state attribute is commonly omitted. It accepts the
1545 value <code>IN_TAG</code> in the <code>HTML</code> context
1546 to indicate that the template only contains (one or more)
1547 HTML attribute name and value pairs that are part of an
1548 HTML tag formed in a parent template.
1549 </ul>
1550
1551 <p>This will auto-escape every variable in the template. To turn off
1552 auto-escaping for a particular variable, you can apply the
1553 <code>none</code> modifier, like so: <code>{{MYVAR:none}}</code>.
1554 Here is an example of an autoescaped document:</p>
1555
1556 <pre>
1557 {{%AUTOESCAPE context="HTML"}}
1558
1559 &lt;body&gt;
1560 &lt;p&gt;Hello {{USER}}&lt;/p&gt;
1561 &lt;p&gt;&lt;a href="{{URL}}"&gt;Your Account&lt;/a&gt;&lt;/p&gt;
1562 &lt;p&gt;Your identifier: {{ID:none}}{{! This is dangerous! }}&lt;/p&gt;
1563 &lt;/body&gt;
1564 </pre>
1565
1566
1567 <h2> Development Tools </h2>
1568
1569 <p>This package includes several tools to make it easier to use write
1570 and use templates.</p>
1571
1572
1573 <h3> <A name="make_tpl_varnames_h">make_tpl_varnames_h:
1574 Template Syntax Checker and Header File Generator</A> </h3>
1575
1576 <p><code>make_tpl_varnames_h</code> is a "lint" style syntax checker
1577 and header file generator. It takes the names of template files as
1578 command line arguments and loads each file into a Template object by
1579 retrieving the file via the Template factory method. The loading of
1580 the file does pure syntax checking and reports such errors as
1581 mis-matched section start/end markers, mis-matched open/close
1582 double-curly braces, such as <code>"{{VAR}"</code>, or invalid
1583 characters in template variables/names/comments.</p>
1584
1585 <p>If the template passes the syntax check, by default the utility
1586 then creates a header file for use in the executable code that fills
1587 the dictionary for the template. If the developer includes this
1588 header file, then constants in the header file may be referenced in
1589 the dictionary building function, rather than hard-coding strings as
1590 variable and section names. By using these constants, the compiler
1591 can notify the developer of spelling errors and mismatched names.
1592 Here's an example of how this is used, and how it helps prevent
1593 errors:</p>
1594
1595 <pre>
1596 const char * const kosr_RESULT_NUMBER = "RESULT_NUMBER"; // script output
1597 dict.SetValue("RESSULT_NUMBER", "4"); // typo is silently missed
1598 dict.SetValue(kosr_RESSULT_NUMBER, "4"); // compiler catches typo
1599 </pre>
1600
1601 <p>Each constant is named as follows:</p>
1602
1603 <ul>
1604 <li> The initial letter 'k', indicating a defined constant. </li>
1605
1606 <li> One or more prefix letters which are derived from the
1607 template file name. These prefix letters consist of the first
1608 letter of the file name, followed by the first letter following
1609 each underscore in the name, with the exception of the letter
1610 'p' when it is followed by the letters "ost", as is a <A
1611 HREF="tips.html#versioning">recommended convention</A> for
1612 template versioning. For example, the prefix letters for the
1613 file <code>one_search_result_post20020815.tpl</code> are
1614 <code>osr</code>. </li>
1615
1616 <li> An underscore. </li>
1617
1618 <li> The variable or section name itself, same casing. </li>
1619 </ul>
1620
1621 <p>As an example, the section name "RESULT_NUMBER" in the file
1622 one_search_result_post20020815.tpl would be given the constant name
1623 <code>kosr_RESULT_NUMBER</code> and would appear in the header file as
1624 <code>const char * const kosr_RESULT_NUMBER = "RESULT_NUMBER";</code>
1625 -- as in the example above. (The variable is actually a
1626 <code>StaticTemplateString</code>, not a char*, but the basic idea
1627 holds.)</p>
1628
1629 <p>
1630 An alternate output directory may be specified by the command line
1631 flag <code>--header_dir</code>.
1632 </p>
1633
1634 <p>The name of the generated header file is the same as the name of
1635 the template file with an extension added to the name. By default,
1636 that extension is <code>.varnames.h</code>. In the above example, the
1637 header file containing the constant declarations would be named
1638 <code>one_search_result_post20020815.tpl.varnames.h</code>. An
1639 alternate extension may be provided via the command line flag
1640 <code>--outputfile_suffix</code>.</p>
1641
1642 <p>Important command line flags:</p>
1643
1644 <ul>
1645 <li> <code>--noheader</code> -- Indicates that a header file
1646 should not be generated; only syntax checking should be done. </li>
1647
1648 <li> <code>--header_dir</code> -- sets the directory where the header
1649 is written. Default: "./" </li>
1650
1651 <li> <code>--template_dir</code> -- sets the template root
1652 directory. Default: <code>./</code> which is the correct
1653 specification when it is run from the directory where the templates
1654 are located. This is only used if the input template filenames
1655 are specified as relative paths rather than absolute
1656 paths. </li>
1657
1658 <li> <code>--outputfile_suffix</code> -- the extension added to the
1659 name of the template file to create the name of the generated
1660 header file. Default: <code>.varnames.h</code>.
1661 </ul>
1662
1663 <p>For a full list of command line flags, run
1664 <code>make_tpl_varnames_h --help</code>.</p>
1665
1666
1667 <h3> <A name="template_converter">template-converter: convert a
1668 template to a C++ string</A> </h3>
1669
1670 <p><code>StringToTemplateCache()</code> lets you load a template
1671 from a string instead of a file. Applications may prefer this option
1672 to reduce the dependencies of the executable, or use it in
1673 environments where data files are not practical. In such cases,
1674 <code>template-converter</code> can be used as a template "compiler",
1675 letting the developer write a template file as a data file in the
1676 normal way, and then "compiling" it to a C++ string to be included in
1677 the executable.</p>
1678
1679 <p>Usage is <code>template-converter &lt;template filename&gt;</code>.
1680 C++ code is output is to stdout; it can be stored in a .h file or
1681 included directly into a C++ file. Perl must be installed to use this
1682 script.</p>
1683
1684
1685 <hr>
1686 <ul>
1687 <li> <A HREF="guide.html">User's Guide</A> </li>
1688 <!--
1689 <li> <A HREF="reference.html">Reference Manual</A> </li>
1690 -->
1691 <li> <A HREF="auto_escape.html">Auto Escape</A> </li>
1692 <li> <A HREF="tips.html">Tips</A> </li>
1693 <li> <A HREF="example.html">Example</A> </li>
1694 </ul>
1695
1696 <hr>
1697 <address>
1698 Craig Silverstein<br>
1699 <script type=text/javascript>
1700 var lm = new Date(document.lastModified);
1701 document.write(lm.toDateString());
1702 </script>
1703 </address>
1704
1705 </body>
1706 </html>
1707