TEMPLATE LANGUAGE
WebSite Director (WSD) supports a template language that allows template developers to generate content, and to customize data entry processes. The WSD Template Language includes commands, variables, and conditionals using a modified form of the HTML tag with the format <$...>. All WSD Template Language tags, except for layout fields, start with "<$" and end with ">".

Template language tags may be used inside any HTML tag.

">" characters can only be used inside a template language tag when contained within quoted strings.

Template Language tags may be used within the body of the HTML document itself by checking the "Document contains template commands" option on the Properties screen for the document. Any of the Template Language tags may be used within the body of the document.

This tutorial consists of the following sections:

Template Variables

Template Property Variables

Computed Strings

Reference Variables

Template Commands

Template Debugging

Template Conditionals

Layout Template Fields

Layout Template Command Values

Template Variables (^to Index)

WSD supports two types of template variables: property values and field values. Properties include document properties, directory properties, and local properties. Field values consist of the content entered into a layout template field.

Property Values - Property values are retrieved using the syntax "$prop:property$", where "property" is the name of the document, directory, or local property. If no property with that name is found, the returned value will be empty. Older templates may still use the deprecated syntax of "$property", which is still supported for backward-compatibility.

Field Values - Field values are retrieved using the syntax "$field:fieldname$", where "fieldname" is the name of a layout template field in the current document. If no field with that name is found, the returned value will be empty. Older templates may still use the deprecated syntax of "$field$", which is still supported for backward-compatibility.

Note: When you use a template variable within the body of a document, the Document contains template commands option must be selected on the document's Properties screen.

Template property variables can refer to a "substring" of a property value using the syntax "$prop:property:<start>:<end>$" (or "$property:<start>:<end>"), where:

<start> is the character position (beginning at 0) of the first character to extract and

<end> is the character position of the last character to extract from the property value.

Note: Because these are 0-relative values, the start/end values of a field are always normal position-1 (i.e. the 20th position in a field has a <start>/<end> value of 19).

If the start position is omitted, the first character (0) is used. If the end position is omitted, the last character is used. The property substring syntax can be used in any template tags that retrieve the value of a property, including $if constructs, for the current document (property substrings are not supported in $reference variables). Examples:

<$prop:myprop:2:8$> (extract characters 3-9)

<$prop:myprop::5$> (extract the first six characters)

<$prop:myprop:9:$> (extract from character 10 to the end)

For Directory Index Templates, the WSD property or field value is retrieved from any of:

The current document being processed in a $foreach document loop

The current directory being processed in a $foreach or $for directory loop

The current directory when NOT in a $for directory loop

When using a template type other than Directory Index Templates and E-Mail Templates, the WSD property or field value is retrieved from the current request, current document, or current directory. Note: E-mail Templates use only a limited subset of the template functionality. See the E-mail Templates tutorial for more information.

Template Property Variables (^to Index)

VARIABLE DESCRIPTION ORIGINATES FROM:

filename Document Filename Properties screen

fileurl Document Filename in URL format Properties screen

fname Document Filename without path Properties screen

origfilename Original Document Filename in a COPY, MOVE, or RENAME request Properties screen

requesttype Request Type (ADD, etc.) Properties screen

requestid Request ID Database information

revision Revision Number Database information

author Author Assigned on Properties screen from list of authorized users

 authorname Author's First and Last Name Assigned on Properties screen from list of authorized users

 authoremail Author's Display E-mail Address Author's e-mail address as maintained on the Edit User Info screen

 authorurl Author's URL Author's URL as maintained on the Edit User Info screen

maintainer Maintainer's User ID Selected on Properties screen from list of authorized users

 maintainername Maintainer's First and Last Name Selected on Properties screen from list of authorized users

 maintainerurl Maintainer's URL Maintainer's URL as maintained on the User Administration screens

title Document Title Properties screen

description Document Description Properties screen

keywords Keywords Properties screen

creationdate Creation Date Database information

creationtime Creation Time Database information

publishdate Publication Date Database information

publishtime Publication Time Database information

currdate Current Date Database information

currtime Current Time Database information

docnum Document Number Database information; may be changed on Properties screen

stage Request Stage ID Database information

hostname Web Server Hostname Web Server information

dir (see Note*) Directory Path in URL format Properties screen

 dirurl Directory Path in URL format Properties screen

 dirpath Directory Path in filesystem format Properties screen

 dirname Directory Name without full path Properties screen

 dirdesc Directory Description Maintained on Directory Maintenance screens

 dirsection Directory Section Name Maintained on Directory Maintenance screens

dirparent (see Note*) Parent Directory Path Properties screen

 dirparenturl Parent Directory Path in URL format Properties screen

 dirparentname Parent Directory Name without full path Properties screen

 dirparentdesc Parent Directory Description Maintained on Directory Maintenance screens

 dirparentsection Parent Directory Section Name Maintained on Directory Maintenance screens

dirtop (see Note*) Top-level Directory Path Properties screen

 dirtopurl Top-level Directory Path in URL format Properties screen

 dirtopname Top-level Directory Name without full path Properties screen

 dirtopdesc Top-level Directory Description Maintained on Directory Maintenance screens

 dirtopsection Top-level Directory Section Name Maintained on Directory Maintenance screens

dirlevel (see Note*) Number of directories above the current document Database information

Note*: When WSD is running on a Windows server and using a MySQL or MiniSQL database, additional backslash characters are needed in directory names to "escape" the original backslash characters in the database query interpreter. To provide "escaped" versions of the WSD directory properties when creating custom SQL queries, prepend the word "escape" to directory template variables (e.g. "escapedir" is an escaped version of "dir", "escapedirpath" is an escaped version of "dirpath", and "escapedirparent" is an escaped version of "dirparent").

Computed Strings (^to Index)

Some WSD template tags support "computed strings", where one or more properties or field values are concatenated together with additional text to form a new value. The computed strings are specified by a beginning '{' character and a trailing '}' character. You may place any combination of text, property tags (in the form "$prop:property$"), and field tags (in the form "$field:fieldname$") between the braces. When using computed strings to construct filenames, the computed strings can begin with any of the following directory variables:

$docroot - Document Root Directory

$templatedir - Top-level Template Directory

$installdir - WSD Installation Directory

$requestdir - WSD Request File Directory

$versiondir - WSD Version File Directory

Computed strings are currently supported as the filename portion of the $include template tag, the URL portion of the $href template tag, the first part of the $reference template tag, in the right side of the $if template tag, or in the value portion of the $setproperty tag. Some examples are:

<$include {$templatedir/header/$prop:header$}>

<$href {/scripts/myscript.asp?Filename=$prop:filename$}>

<$setproperty authorfullname="{$prop:authorname$ ($prop:author$)}">

The result of a computed string should not exceed 1024 characters in length. When building a filename for a WSD template, the filename must include the template directory name under the top-level template directory, in the form "$templatedir/<template-type>". So the first part of the filename for each of the template types would be as follows:

$templatedir/header - first part of filename of a header template

$templatedir/footer - first part of filename of a footer template

$templatedir/layout - first part of filename of a page-layout template

$templatedir/editlayout - first part of filename of an edit-layout template

$templatedir/index - first part of filename of an index template

$templatedir/email - first part of filename of an e-mail template

The following examples show 3 different methods for constructing a filename pointing to the header template associated with the current document:

{c:\inetpub\scripts\wsd\templates\header\$prop:header$} - constructs a filename referencing the header template associated with the current file on a Windows NT or Windows 2000 system running IIS

{/apache/cgi-bin/wsd/templates/header/$prop:header$} - constructs a filename referencing the header template associated with the current file on a Unix-based server

{$templatedir/header/$prop:header$} - constructs a platform independent filename referencing the header template associated with the current document.

Other Examples:

{$docroot/products/$field:product-type$/prices/$prop:fname$} - constructs a filename pointing to a file with the same name as the current file, located in a prices directory, under a directory with the same name as the value of the "product-type" template field, which in turn is under a directory named "products" under the document root.

Reference Variables (^to Index)

WSD templates can also include property and field values from other documents by using $reference template tags. The $reference tags are composed of two parts: the "source" part that specifies from which document WSD will retrieve the property or field, and the "element" part that specifies from which property or field the value will be retrieved. There are two types of $reference tags: Indirect reference, and Direct reference.

Indirect References - In an indirect reference, the $reference tag specifies a "source" property or field in the current document that contains the filename to use in looking up the property or field value. Only absolute filenames are supported in indirect references.

A source field could be a hyperlink or image field that contains the results of a selection from a list of files. For example, if an image is selected in a Layout template image field, a $reference tag could be used to retrieve the document title associated with that image for use in an "Alt=" tag. Or the source could be a property that is assigned to the document or generated as a local variable. The syntax of an indirect reference is any of the following:

<$reference $field:sourcefieldname$:$prop:destproperty$>

<$reference $field:sourcefieldname$:$field:destfieldname$>

<$reference $prop:sourceproperty$:$prop:destproperty$>

<$reference $prop:sourceproperty$:$field:destfieldname$>

where the sourcefieldname or sourceproperty contains the filename to retrieve the property or field value from, and destproperty or destfieldname is the property or field in the source document.

Direct References - In a direct reference, the $reference tag specifies the actual filename in the first part of the $reference tag, followed by the property or field to retrieve from that file. The filename must be in the form of a computed string (e.g. {filename}) even when the filename does not contain replacement tags.
When retrieving a property from the source document, the filename must be relative to the Document Root directory. When retrieving a field value from the source document, the filename must be a fully qualified path and filename on the web server. The syntax of a direct reference is one of:

<$reference {sourcefilename}:$prop:destproperty$>

<$reference {sourcefilename}:$field:destfieldname$>

where the sourcefilename is the name of the file from which to retrieve the property or field value and destproperty or destfieldname is the property or field in the source document. For example:

<$reference {$docroot/mydir/myinfo.html}:$field:summary$>

<$reference {/mydir/mypicture.gif}:$prop:title$>

Template Commands (^to Index)

The following commands are available in the WSD Template Language:

<$include {filename}>

<$href {url}>

<$setproperty property-name="property-value">

<$include {filename}>
The $include command copies the contents of another file into the document at the location of the $include command. The filename of the file to include must be specified as a computed string. The filename can be either a full path and filename or the name of a file in the current directory (i.e., no path included). If the filename is a full path and filename and the file is not found, an error will be written to the WSD Activity Log file. If the filename does not include a path, the presence of the file is optional, and no error will be written to the WSD Activity log file if the file does not exist.
Include files can contain any WSD Template Language tags, including template field definitions, and any included template language tags are processed as if they were present in the original template. (^to Index)
<$href {url}>
The $href command is used in a similar fashion to the $include command, but instead of loading content from a local file on the web server, it instead retrieves content from a URL on either the local web server or a remote web server. That content can be a static web page or a web page generated by a dynamic content server. Because the content will be included within the WSD template, the retrieved content should not include HTML head, body, or html tags. The $href command can specify a full URL, as follows:

<$href {http://www.mycompany.com/path/to/web/page.html}>

or a URL to a web page or script on the current web server:

<$href {/path/to/my/script.asp}>

Just like the {filename} component in the $include command, the URL in the $href command is specified as a computed string, and can contain replacement variables referencing WSD property and field values. Multiple property and field values can be referenced, although the resulting URL should not exceed 1024 characters in length. For example:

<$href {/scripts/myscript.asp?Filename=$prop:filename$}>

The content retrieved by a $href command can contain any WSD Template Language tags except for template field definitions. Any template language tags embedded in the results of a $href tag will be processed as if they were present in the original template.

Any property and field values retrieved for use in <$href> tags are encoded for use in URLs (such as replacing space characters with '+' characters). Any scripts called by a $href command should use the standard URL decoding algorithm for any data fields passed in the URL. (^ToIndex)

<$setproperty property-name="property-value">
The $setproperty template command creates temporary local properties that can be used during template processing. Properties set using this template command are available as standard properties to any other template language tag following the $setproperty command in the current template. The syntax of the command is "<$setproperty property=value>" and the property name specified should be a unique name that does not conflict with an existing WSD property.

The assigned property value can be a text string, the results of a $reference lookup, or a computed string. Quotes are optional for the property value, unless the property value contains a ">" character. Examples:

<$setproperty myprop="Hello World!">

<$setproperty myprop=$reference $Icon$:$prop:author$>

<$setproperty authorfullname="{$prop:authorname$ ($prop:author$)}">

<$setproperty my_property="Fred"> -- a simple value string

<$setproperty my_property="$reference {$docroot/index.html}:author"> -- sets my_property to the value of the author name associated with the home page (index.html) located in the Document Root

<$setproperty my_property="$reference {$docroot/index.html}:$LeadStory$"> -- sets my_property to the value assigned to the field named "LeadStory" as published on the home page (index.html) located in the Document Root

<$setproperty my_property="{$docroot/French/help/$prop:fname$}"> -- sets my_property to a value constructed from the expression (a filename) contained between the {} characters

<$setproperty my_property="{$fname}"> - sets my_property to the filename (fname property value) of the current document

<$setproperty my_property="{$LeadStory$}"> - sets my_property to the data content of the filed named "LeadStory" in the current document

<$setproperty my_property="{The story titled $LeadStory$ is located at $fname}"> -- sets my_property to a string containing a combination of fixed text and both a property and fieldname content

Template Debugging (^to Index)

Template Debugging can be enabled by setting a local property called "DebugTemplate" in the template. This is done by including a "<$setproperty DebugTemplate=On>" command prior to the place in the template you want template debugging to begin. When template debugging is turned on, entries are written to the WSD Activity Log file (wsd.log) with details about each template language tag ($include, $reference, $if, etc.) encountered during the processing of the template. The log entries will include details such as the results of computed strings and $reference filename lookups. After you solve your problem, turn OFF template debugging using the "<$setproperty DebugTemplate="">" command This will minimize log activity records to those you want to see to isolate your problem(s). Warning: Always remove template debugging commands before placing your templates into normal service for use by content contributors!

Template Conditionals (^to Index)

Content can be selectively generated inside a WSD template through the use of template conditional tags. These template language tags support all of the standard variants of the traditional "if" conditional tests available in any programming or scripting language. Template conditional tags can test for:

the presence of a property or field value,

test for a specific value,

provide a comparison of a property or field value,

test for the presence of a file,

test certain aspects of the environment in which the template is being processed.

The basic syntax for the template conditional tags are as follows:

<$if [condition]>

<$ifnot [condition]>

<$elseif [condition]>

<$elseifnot [condition]>

<$else>

<$endif>

Multiple template conditional tags can be used on a single line, or on any number of lines. Sets of template conditional tags must consist of at least a $if or $ifnot tag and a closing $endif tag. Any number of $else, $elseif, or $elseifnot tags can be used between the initial $if or $ifnot tag and the closing $endif tag to support any branching logic. Sets of template conditional tags can be included within other template conditional tags. WSD allows nesting of up to 32 levels of template conditional tests.

Valid [conditions] are:

[template variable] - Test the presence of a property or field value

[template variable] eq [value] - Test if a property or field value matches a specific string or number

[template variable] ne [value] - Test if a property or field value does not match a specific string or number

[template variable] lt [value] - Test if a property or field value is less than a specific number

[template variable] gt [value] - Test if a property or field value is greater than a specific number

exists {filename} - True if the file specified in the computed filename string exists on the web server

viewsample - True if the template is being displayed with the "View Sample" option

preview - True if the template is being processed to preview a document

editing - True if the template is being used to edit request content associated with a document during CREATEONLNE and EDITONLINE sessions.

index - True if the template commands enclosed between the $if and $endif statements are being used within a WSD Index Template. Note: This is useful when the same code is included in both regular templates and Index Templates.

groupmember [groupid] - True if the content contributor using this template belongs to the specified [groupid]

The [template variable] used in a condition can be a property value ($prop:property$), or a field value ($field:fieldname$), or a reference variable ($reference $field:fieldname$:$prop:property$). When used without a comparison operator (eq, NE, lt, or gt), the condition tests for the *presence* of a variable, i.e. to see if there is actually a value assigned to that variable. The [value] used with a comparison operator in a condition can be either a text string or a computed string. Quotes are optional for value strings unless the value string contains a ">" character.

Some examples (fragments only, not necessarily complete conditional sets):

<$if $prop:maintainer$> Maintained by: <$prop:maintainername$><$endif>

<$if $prop:author$ eq joe>

<$elseif $field:Headline$ NE"My Headline">

<$if $prop:position$ lt 4>

<$elseifnot $prop:position$ gt 10>

<$if exists {$docroot/mydir/myinfo.html}>

<$if $reference $field:Icon$:$prop:author$ eq "johndoe">

Layout Template Fields (^to Index)
A Layout Template Field consists of the following:

Beginning-Tag enclosed between "", and consisting of three required attributes -- type=, name=, and prompt= plus any additional attributes needed for formatting. The beginning tag can span multiple lines. For example,



Optional-Text that will display to the user within the template edit field defined by
the beginning tag.

Note : if you are using the "View Source" option when browsing
pages created with Page Layout Templates, this will be the text entered/updated by
the content contributor.

End-Tag that must be in the format "" and cannot span multiple lines.

Layout Template Command Values (^to Index)

This section defines the possible command values for the "type=<command>" attribute which defines the actual <command> functionality, and determines the type of editing control WSD will present to your contributor during "Create Online" and "Edit Online" sessions.

For a listing of additional template field attributes for Layout Templates Fields, see Other Page Layout Template Command Attributes.

Each of the examples shown in this section include ALL possible attributes available for that command structure and syntax. Required attributes are shown in bold-text. For easy reading, each attribute in the examples is placed on a separate line.


Warning: Any HTML commands (e.g. ) entered by the content contributor will be applied when the entered data is inserted into the template!
Note: When the property= attribute is set, only the first 255 characters entered by the contributor will be stored-in/available-from the property database for this property in this document.


Note: The WYSIWYG editors only operate under Microsoft Internet Explorer 4.0 or later, or Netscape 4.0 or later, when JavaScript is enabled. If these conditions are not met, an HTMLEDIT field operates exactly like a TEXTAREA field.


<body background="" ...>

Note: If the first occurrence of the value declared for prefix= (or value assigned to src= in the first <img tag) already contains a file system location reference, that location reference will be marked as the default in the choice list of images shown. This default reference will be shown to the contributor as the default value of an EDIT field if an image dir= attribute was not specified.


<a href="" alt="Associated product" target=new>Associated Product!</a>

Example-2 (including other previously published content):


<$include $docroot>

Note: In this example, the <!-- $docroot -- entry MUST BE PRESENT! WSD uses this occurrence of the prefix=$docroot attribute to provide a place-holder for setting the default value. Because of the functionality inherent to the <$include request, the line <$include $docroot> used to actually place the selected content within the body of this page, is no longer available after content insertion has been completed.

Copyright 2000-2005 CyberTeams, Inc., http://www.cyberteams.com All rights reserved.
CyberTeams and WebSite Director are registered trademarks of CyberTeams, Inc. All other marks are the property of their respective owners.