| 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>{{>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>{{! comment lives 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>{{=< >=}} <! Now markers are |
| 118 |
delimited by braces > <=| |=> |! 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, &output, &dict, |
| 304 |
&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>{{>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><space></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><newline></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", ..., &dict); |
| 529 |
ctemplate::ExpandTemplate("C.tpl", ..., &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, &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><html><body>{{NAME:html_escape}}</body></html></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 & Bob</code>, what will actually be |
| 971 |
emitted in the template is <code>Jim &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 |
<html><body>{{NAME:html_escape:javascript_escape}}</body></html> |
| 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 |
<html><body>{{NAME:h:j}}</body></html> |
| 984 |
</pre> |
| 985 |
|
| 986 |
<p>Some modifiers take an argument, specified after an equals |
| 987 |
sign:</p> |
| 988 |
<pre> |
| 989 |
<html><body>{{NAME:html_escape_with_arg=pre}}</body></html> |
| 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>&</code> -> <code>&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>"</code> -> <code>\x27</code> and |
| 1027 |
<code>&</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>&</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 <pre>...</pre>)</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><a href="http://google.com/search?q={{QUERY:u}}">{{QUERY:h}}</a></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><>&"'</code> become |
| 1073 |
<code>&lt&gt;&amp;&quot;&#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><br></code>, <code><wbr></code>, <code><b></code>, |
| 1094 |
and <code></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><img src=#></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()'"<>*\] 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><template_modifiers.h></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& 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>{{>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(&dict, &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><script></code> tag, its context is |
| 1538 |
<code>HTML</code> and not <code>JAVASCRIPT</code>. Auto-Escape |
| 1539 |
will recognize the <code><script></code> tag and hence |
| 1540 |
properly Javascript-escape the variables within it. Similarly, |
| 1541 |
if the template starts with a <code><style></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 |
<body> |
| 1560 |
<p>Hello {{USER}}</p> |
| 1561 |
<p><a href="{{URL}}">Your Account</a></p> |
| 1562 |
<p>Your identifier: {{ID:none}}{{! This is dangerous! }}</p> |
| 1563 |
</body> |
| 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 <template filename></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 |
|