iWisdom

PSRenamer

PSTextMerge

Two Due

Surfer Survey

Press Room

Products | Tdfczar | Tutorials

TDF Czar Tutorial on Templates

What's a Template File?

A TDF Czar Template file is a text file with special commands and variables embedded in it. The commands control how one or more output files are created. The variables are replaced with real data taken from an input data source — normally a tab-delimited file, possibly saved from a spreadsheet or database table. The remaining text, other than commands and variables, is written verbatim to the output file(s). In this sense, TDF Czar works like a traditional mail-merge program, except you are merging your data into Web pages rather than letters.

What's a Template Good For?

Sometime you have rows and columns of data already defined, and you want to publish some or all of this data to the Web. Using a spreadsheet, database, or address book to store and maintain your data is a good strategy — after all, that's what these sorts of programs were designed for. And leaving them in this sort of format lets you use the data in other ways. You could even publish the data into multiple Web pages, each sorted differently, or with different selections of rows or columns.

Couldn't I Use Some Other Program?

Yes. The spreadsheet or database program you are using may be capable of saving its data into a Web format. But typically these programs are rather rigid about formatting their Web pages, whereas TDF Czar gives you total control over the design of your output. If you have your own Web server, with ASP, JSP or PHP, plus a relational database, then you can generate Web pages dynamically, merging the data from your database into your Web pages as your users request them. But not everyone has the resources for this kind of dynamic database publishing. Since TDF Czar creates static HTML, the resulting Web pages can easily be published on any Web server or corporate intranet. And once these Web pages are posted to your server, you don't have to worry about them breaking because someone changed the format of your database, or updated your database software, or any one of numerous other things that can go wrong in a dynamic environment.

Basic Template Commands

A template command begins with two less than signs, and ends with two greater than signs, looking like an HTML tag on steroids. Template commands must always be on a line by themselves, with no leading spaces.

Every valid template file must contain a minimum of three commands. Let's look at the following, simple example. The three commands are in blue lettering.

<<output "index.html">>

<html>

<head>

<title>Sample 1</title>

</head>

<body>

<<nextrec>>

<<loop>>

</body>

</html>

The output command assigns a name to the output file that is to be created. In this case the file is in the same directory as the template, but a drive identifier and/or path can be supplied as well, in order to place the output file in a different location.

The nextrec command needs no parameters, and simply indicates that the following lines should be repeated once for every row in the input data file.

The loop command is the ending counterpart to the nextrec command, indicating the end of the repeating block. Lines following the loop command will be written out only once, after the end of the input data file has been encountered.

Variables

Variables are shown in red lettering in the above example. Notice that all of the variables appear within the nextrec and loop commands. This way the variables will assume different variables for each row in the input data. In this case, the input source contains one column called artist and another called cdtitle. Variable names are basically column headings from the input source — data taken from the first row of the table. Case, spacing and punctuation are insignificant, so the column heading in your table could be "CD Title", and the corresponding variable identifier in your template file could be "cdtitle", "CD-Title" or "cd_title" — all will work equally well.

There's a lot you can do with templates using nothing more than the information given above. But TDF Czar offers you lots of other options, so read on.

Creating One Page per Row

If you have a lot of information in each row of your table, then you may want to create one entire Web page per row. This can be easily done, using nothing more than the features already described above. Simply put the nextrec command on the first line of your template file, and move the loop command to the last line. Now place the output command on the second line of your template, and use a variable as part of your file name. Now each new data row will cause a separate output file to be written.

Grouping Your Data

Many times your data will fall into natural groupings. For example, you may have multiple CDs for the same artist. You might also have a genre or category defined for each CD. So let's say that you sort your data, first by category, and then by artist (you can do this within TDF Czar, if you like). And since you will have many CDs for the same category, and often multiple CDs for the same artist, you may want to present this information in a heading, rather than repeating it for each CD. This can be easily done with TDF Czar's group commands. Let's look at the following example.

<<output "index.html">>

<html>

<head>

<title>Sample 2</title>

</head>

<body>

<<nextrec>>

<<definegroup 1 "<<category>>">>

<<definegroup 2 "<<artist>>">>

<<ifnewgroup 1>>

<<ifnewgroup 2>>

<<endif>>

<<cdtitle>></p>

<<loop>>

</body>

</html>

We have two definegroup commands. Category is defined as group 1, since it is the first field we sorted by. The variables that define the group follow the group numbers on each definegroup command line, and are enclosed in double quotation marks (as well as the double less than/greater than signs that indicate variables).

Then we have two ifnewgroup commands. Whenever the group variable changes, it will trigger the ifnewgroup commands to be true, and will cause the following lines to be included in the output for that data row. In addition, higher-level breaks will automatically trigger lower-level breaks. In this case, that means that a change in category will always force a change in artist as well. The overall result in this case is that a level 1 heading will be displayed each time a new category is begun, and a level 2 heading will be displayed each time a new artist is encountered. The lines to be included following an ifnewgroup command must be terminated by another group command, or by an explicit endif command.

Although we don't use it in this example, there is also an ifendgroup command that allows you to generate output at the end of a group break. This could be used to close a list, or end a table row, as two examples.

By the way, the ifchange command was an earlier attempt to provide similar functionality. It combines the definegroup and ifnewgroup functions into a single command, but only allows one key field to be defined. It can be used as well if you have only one group, but the group commands generally provide more flexibility and control.

Other Conditional Processing

For other conditional processing, TDF Czar provides a more general if command. The simplest form the command takes is to simply include one variable after the command, as in the following example.

<<if "<<rating>>">>

<p>Rating: <<rating>></p>

<<endif>>

In this form, the command simply tests to see if the variable has a non-blank value. This is a convenient way to skip displaying some surrounding text if the variable itself is blank, as in the example above. Again, the conditional text must be terminated with an endif command.

The expanded form of the if command allows you to specify two values and a comparison operator. Either or both of the values can be variables. Let's look at the following example.

<<if "<<rating>>" >= 3>>

<p>Rating: <<rating>> -- Preferred</p>

<<endif>>

In this example, we check to see if our rating of the CD is greater than or equal to 3. If it is, then you might want to print a special comment or image.

Counters

From time to time it is handy to have some sort of counter available. For example, if laying out text in a table, you might use a counter to start a new table cell after a certain number of lines. Let's look at the following example.

<table>

<tr>

<td>

<<set linect = 0>>

<<nextrec>>

<<if <<linect>> > 10>>

</td>

<td>

<<set linect = 0>>

<<endif>>

<<cdtitle>> <br>

<<set linect + 1>>

<<loop>>

</td>

</tr>

</table>

So what have we done here? The set command can define a global variable, and increment or reset its value. Here we define a global variable called "linect" to maintain the number of lines we have included in a table cell. We set the value to zero at the beginning of our processing, and increment it by one each time we add a line to the current table cell. When we have included more than ten lines, we end the current table cell, start a new one and reset our counter. Very handy!

Variable Modifiers

TDF Czar provides a few different ways to control the way variables appear in the output. By placing an ampersand after a variable, following characters will be treated as variable modifiers. The letters "u" or "l" will convert the variable to all upper- or lower-case, respectively. One or more digits will be interpreted as the maximum number of characters to display, truncating the variable if it is longer. And a punctuation character will be interpreted as a list separator. By using the same list separator on consecutive variables within a list, the separators will be used to separate non-blank occurrences of the variables. For example, if you have three variables, keyword1, keyword2 and keyword3, with the first set to "warm", the second blank and the third set to "vibrant", then formatting your line like this:

<<keyword1>>, <<keyword2>>, <<keyword3>>;

would result in output like this:

warm, , vibrant

On the other hand, formatting your template line as follows:

<<keyword1&,>> <<keyword2&,>> <<keyword3&,>>

would result in the desired output:

warm, vibrant

Note that you must include the list separator on all elements of the list, including the last.

Using Other Delimiters

There is one last command that we haven't talked about yet. This is the delims command. You can use it to change the normal TDF Czar delimiters to any other character combinations you want. The following line would change the default delimiters.

<<delims <$ $> <@ @> %>>;

<$output "index.html"$>

The delims command would normally be the first line in a file. This first line would use the default delimiters, but following lines would use whatever delimiters were set by the first line. The delims command can set from one to five delimiters, in the following sequence: command start, command end, variable start, variable end, and variable modifiers start.

Normally, overriding the default delimiters would be optional and merely a matter of personal taste. However there is one case where new delimiters would be required. TDF Czar can optionally create a data dictionary file. This is itself a tab-delimited file, with one row for each column in the primary data source. It is possible to create a meta-template file, in which the output to be written without change would include normal template commands and variables. In this case, the meta-template file would need to use a delims command to override the normal delimiters, so that they would be written out unchanged. The meta-template file would then read the data dictionary, and use it to format a template file. This can be useful if each row of your data source contains many columns, and you�want to format their display all similarly, since the meta-template can save you the hand-coding of the template.

http://www.powersurgepub.com/ | template.html | Revised: 6/15/08