Templating System Usage

To use a template, start by adding ",new" after almost any URL on our site to see the templates available at that point of the site. ",new" is one of the comma-tools.

The text below explains how to create templates.

A few things to know to create a template

The templating system helps you create uniform documents for W3C pages, or helps you to prepare documents for particular circumstances (Last Call, etc).

New templates must be created in a directory which is called Templates.

General usage

The description and the title

It is recommended to add a very short description of the template in a meta tag at the top of the document, e.g.:

<meta name="description" content="Press release">

The ,new tool will otherwise display the title of the document, but often the title is just "%%title%%".

%%variable-name%%

When the template is called, a form will be created and displayed with the value of variable-name to input. We suggest that you choose a variable name which has a meaning. Spaces are allowed, but no colons (:) or equals signs (=). For example:

%%Your email address%%

The form will contain an entry with "Your email address" and an input field.

%%variable-name=default-value%%

Same as above, but the form will show an input field pre-filled with the given default value.

%%url-escape: variable-name%%

This is for the rare case of variables that are inserted into a URL. E.g., if the template contains:

... <a href="http://example.org/process?name=%%name%%">process it...

and the variable "name" happens to contain certain characters such as "&", "=" or "/", the link will be incorrect. Instead, write it like this:

... <a href="http://example.org/process?name=%%url-escape:name">process it...

Don't use it where the variable constitutes the whole of the URL, such as in <a href="%%url%%">

Technically, the prefix "url-escape" instructs the templating system to use so-called "%-escapes".

%%variable-name:option,option,option%%

Instead of an input field for text, the form will contain a menu with the given options.

Do not put spaces after the colon (:) or after the commas (,), unless you want an actual space in the value.

%%variable-name:option,option,option=default%%

Same as above, but the option that is equal to the default is already selected (instead of the first option). E.g.,

... %%color:red,green,blue,purple=blue%%...

will show a menu that looks like this:

URL-escaping, menus and defaults can be combined. E.g., here is a variable that has a menu of options, with a default option, and that will be URL-escaped in the generated document:

... %%url-escape: fraction:1/2,1/3,1/4,1/5=1/3%%...

%%yyyy%%

When the variable is exactly yyyy, the form will show an input field prefilled with the current year. For example, "1969"

%%mm%%

The form will show an input field prefilled with the month as two digits. For example, "02" for February

%%mmm%%

The form wil show an input field prefilled with the month in a 3-letter format. For example, "Feb" for February

%%dd%%

The form will show an input field prefilled with the date. For example, "16"

%%if: variable-name%% … %%else%% … %%endif: variable-name%%

%%if: variable-name%% … %%endif: variable-name%%

It is possible to make conditional sections in a template. The part after %%if:variable-name%% will only be copied to the output if variable-name is defined (has a non-empty value). Otherwise, if there is an %%else%%, the part after %%else%% will be copied.

%%switch: variable-name%% %%case: pattern%% … %%case: pattern%% … %%endswitch: variable-name%%%%

A different form of a conditional section. Between the %%switch:variable-name%% and the %%endswitch:variable-name%% there may be multiple occurrences of %%case:pattern%%. The templating system looks for the first one whose pattern matches the value of the variable and then outputs the text after it, up to the next %%case:pattern%%. Only the first match is used, any subsequent %%case:patterns%% are skipped, even if their pattern matches.

The pattern may include wildcards, similar to those for matching file names on the command line:

?: Matches any single character. E.g., the pattern "a?c" matches if the variable has value "abc" or "axc".
*: Matches zero or more characters. E.g., the pattern "a*c" matches "abc" and "axc", but also "ac" (zero characters between the "a" and the "c") and "axxxc" (three characters between the "a" and the "c").
[...]: Matches any of the characters between the brackets. E.g., "a[bdpq]c" matches "abc" and "apc", but not "axc".
[^...]: Matches any character except those between the brackets. E.g. "a[^bdpq]c" matches "axc", but not "abc" nor "apc".
{string,string,…}: Matches any of the comma-separated strings. E.g., "a{10,20,30}c" matches "a10c", "a20c", and "a30c"

To match a literal "?", "*", "[", "]", "{", or "}", precede it with a backslash: "\?", "\*", etc. (To match a backslash, double it: "\\".) Use "\," to match a literal comma inside braces: "{aa,\,}" matches "aa" or a single comma.

The pattern cannot start with a space. If you want to match a value that starts with a space, use "[ ]". E.g., %%case: [ ]x%% matches a value consisting of a space and an "x".

The following example defines a menu with three values, red, green and blue, and then uses a switch to select which text to include in the output. Note the last pattern, "*", which matches any value that hasn't been matched yet.

... %%My color:red,green,blue%%
%%switch: My color%%
%%case: red%% a red tomato
%%case: green%% a green salad
%%case: *%% a blue curaçao
%%endswitch:My color%% ...

Optional & required variables

If the value of a variable is optional, i.e., the value is allowed to be empty, start the variable name with "?". Otherwise the value is required. (If a user then leaves the value empty in the form, the output will contain "@@variable@@" to indicate that a value was missing.) E.g.:

... %%?middle name%%...

Somes examples of templates.