Using the Template Tool
(tick_24Pro, tick_24Std, tick_24Lite)

The template tool is one of several tools that help you perform certain tasks quickly and easily. The template tool is capable of saving a web developer from spending a tremendous amount of time making the same changes to many documents. For example, using the template tool, a header or footer can be changed on hundreds of documents in just minutes (or seconds) without the need for any scripting like ASP or PHP. This tool is even included in the lite edition.

One of the best ways to learn how to use the template tool is by example. This page contains some examples on using the template tool that is included with CSE HTML Validator.

Example One

A simple HTML document that can be processed by this tool:

<!-- TEMPLATESTART
TEMPLATE=c:\htmlval\htmltemplates\template1.txt
GRAPHIC=/images/logo.gif
AUTHOR=Albert Wiersch
EMAIL=al@htmlvalidator.com
-->

(The template file is inserted here (the file defined by the symbol TEMPLATE) with symbols replaced by values defined above. Any previous text that is located here is completely removed and replaced by the template file.)

<!-- TEMPLATEEND -->

By running the template tool on an HTML document containing the above, HTML Validator uses the file specified by TEMPLATE to insert text from that file into the space between the two comments (after the line --> and before the line <!-- TEMPLATEEND -->). The template file can include symbols (examples of symbols: TEMPLATE, GRAPHIC, AUTHOR, etc.) so that portions of the template file are replaced with the symbol values (examples of symbol values: /images/logo.gif, Albert Wiersch, etc.) when the template is inserted into the HTML document.

To indicate that a symbol should be replaced with its value when inserting into the document from a template, specify the symbol in the following format in the template: $"SYMBOL". NOTE: The symbol must appear within double quotes (exclude the dollar sign in the double quotes) and must follow immediately after the dollar sign. Examples from the above include $"GRAPHIC", $"AUTHOR", etc. To actually include one dollar sign, escape the dollar sign by including $$ (two dollar signs) in the template file. Note that you do not have to escape the dollar sign unless it is followed by a double quote character.

Example Two

Assume the following document is c:\html\hobbies.html:

<html>
<head>
<title>My Hobbies</title>
</head>
<body>

(The body of the HTML document can go here. This text is not changed by the template tool because it is not within the body of the following comment section.)

<!-- TEMPLATESTART
TEMPLATE=c:\html\footer1.txt
NAME=John Doe
-->

(Any text here is replaced by the template file c:\html\footer1.txt.)

<!-- TEMPLATEEND -->

Assume the following document is the template footer.txt:

<p><hr>
Content by $"NAME".
</body>
</html>

Now, when you process hobbies.html with the template tool, it will be changed to the following:

<html>
<head>
<title>My Hobbies</title>
</head>
<body>

(The body of the HTML document can go here. This text is not changed by the template tool because it is not within the body of the following comment section.)

<!-- TEMPLATESTART
TEMPLATE=c:\html\footer1.txt
NAME=John Doe
-->
<p><hr>
Content by John Doe.
</body>
</html>
<!-- TEMPLATEEND -->

Notice the comments in hobbies.html. By using the template tool on this document, the text file specified by TEMPLATE (which is c:\html\footer1.txt) is inserted between the lines --> and <!--TEMPLATEEND -->. In addition, anywhere in this document where $"NAME" appears, John Doe is inserted instead. You are not limited to just NAME, however; you can define up to 50 symbols (NAME and TEMPLATE are symbols in the above example).

Anytime you want this HTML document to have a different footer, just change the template file (c:\html\footer1.txt) and use the template tool on all the documents that need updating. You can use the tool many times on the same document; each time it's used, the old template file is removed from the HTML document and replaced with a new one so you don't have to do anything to your HTML document before using the template tool on it again. You can even set it up so that you just need to right-click on your HTML document from Windows Explorer and then choose one of the menu items from the context menu in order to use the tool on the selected files. Or even better, just drag all the files to be processed onto HTML Validator. This makes it easy to quickly process one or more HTML documents with a few mouse clicks.

The advantage of using this tool is that by changing the template file, and then using the template tool on all the HTML documents using that template, you can easily change ALL of your HTML documents in far less time than it would take you to individually go through them and change each one manually! Furthermore, it is not just a simple text file insertion, as you can assign symbols in each HTML document so that the text inserted into each HTML document will be specific for that document. It also does not require any extra server processing or parsing each time a document is viewed because your pages remain static.

For more examples you can view the source of many of CSE HTML Validator's pages to see how the template tool has been used to greatly reduce the maintenance time of this site.

Example Three

This is an example about how to use the template tool to insert the current date into your document. Every time you want to update the date, you will have to process the document with the template tool. To change the default date format, please see the information about CURRENTDATE.

Insert the following into your document where you want the date inserted:

<!-- TEMPLATESTART
TEMPLATE=c:\html\date.txt
-->
<!-- TEMPLATEEND -->

The file c:\html\date.txt should contain something like:

<p>Document last modified on $"CURRENTDATE".</p>

That's it! Process the document with the template tool and the template file with the current date will be inserted.

Special Notes

1.<!-- TEMPLATESTART must appear by itself on a single line with no leading space and in all uppercase characters. Similarly, <!-- TEMPLATEEND --> must do the same. You can have multiple template files specified in a document, one for each <!-- TEMPLATESTART and <!-- TEMPLATEEND -->, but attempting to call a template file from another template file will be ignored (not be processed) unless the actual template file is the file being processed by the tool. That is, you cannot nest template files within template files and process the nested template files at the same time as its parent is processed.

2.The symbol names are case-sensitive and consist of alphabetic characters (uppercase or lowercase) or numerical digits and must appear one per line with their values. The exception to this is a blank line. For readability, you can insert blank lines between the lines that define symbols. There is no limit on the number of symbols that you can define.

3.There is a 'hidden' option to make the symbol names case-insensitive. Please note that It is not recommended that this option be used. If this option is enabled, then all symbol names are converted to uppercase before processing. To enable this hidden option 1) exit any running instance of CSE HTML Validator, 2) use the registry editor to OR the value 0x10000 with the value of Flags40 in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator v4\Validator DLL\Tools, and 3) restart CSE HTML Validator. (New v12.0029)

4.The mandatory TEMPLATE symbol must be all uppercase and must specify the location of the template file.

5.The symbol values begin immediately after the equals sign and end at the end of the line.

6.When a file is processed, all text between --> and <!-- TEMPLATEEND --> is thrown away and replaced with text from the template file. This is so that when you process a document with the template tool, the results of the last template tool processing is thrown away automatically and replaced with new results.

7.The original file is renamed with a .bak extension. If this tool fails, the original file is completely unaltered from the failed processing, and an error message should appear indicating the error.

8.By using the command line option for this tool (-t), you can process many documents quickly. For example, if you make the tool accessibly from a pull-down menu when you right-click on an HTML document, then you can select many HTML documents in Windows Explorer and process all of them at one time. However, if you have the professional edition, then it is probably best to use the Batch Wizard.

Built-In Symbols

The template tool now has built-in symbols.

CURRENTTIME for the current time

CURRENTDATE for the current date

CURRENTDATE2 for the current date but with all non-ASCII characters converted to character references (New v16.0301)

CURRENTFILE for the current HTML document filename (not the template filename)

CURRENTYEAR for the current 4-digit year (New v10.0101)

VALIDATORVERSION for the current version of CSE HTML Validator (such as "6.00", without the quotes)

To change the format of the time string, specify a symbol named TIMEFORMAT that contains a format picture string.

To change the format of the date string, specify a symbol named DATEFORMAT that contains a format picture string.

If format picture strings are not given, then defaults are used. The default time and date formats can be changed in the 'Tools' page of the Validator Engine Options.

Functions

You can define a symbol in the following format:

SYMBOLNAME:=FunctionName(Arguments)

Currently, the only supported function is FileContents(). By using this function, you can assign the contents of a file to a symbol name. For example:

DATAFILE:=FileContents("c:\\data\\january.txt")

This will cause $"DATAFILE" to be replaced by the contents of the file c:\data\january.txt when it appears in a template file.

You can also use the + operator to combine the contents of one or more files. For example:

DATAFILE:=FileContents("c:\\data\\january.txt") + FileContents("c:\\data\\february.txt")

Strings can also be used. For example:

DATAFILE:="The january file is:\n"+FileContents("c:\\data\\january.txt") + "\nEnd of file."

Please note that the above examples should be on one line. If any of them are on more than one line, then it has been wrapped.

NOTE: The '\' character is an escape character, so two of these characters are needed to specify a '\' character in a string (such as in the filenames above). '\n' is the escape sequence for a new line.