Use DTD tags in CML

CML supports Document Type Definition (DTD) tags that can be used to pre-define attributes for a CML tag. Using a DTD tag in CML allows you to change some aspects of how the template is displayed in the SA Client. The DTD definition generally goes in the beginning of a file and the tag gets shortened to just a name and a tag type.

The main advantage of using DTD tags in CML is the ability to define 'printable' and 'description' values, which are reflected in the SA Client, improving usability. DTD definitions can be used to define any tag that has a name; for example loop tags, loop target tags, replace tags, and so on, but not tags like instruction tags or block tags. DTD tags in CML are also inherently multi-line tags.

Example of DTD tags

Here we will take a tag and create a DTD version of that tag. A DTD tag in CML is not that different than a regular CML tag; it contains all the elements of a tag minus the “tag type.”

For example, in the CML tag below:

@*deny_header;unordered-string-set;;sequence-delimiter=":";optional@

this is an instance representing the following format in CML:

@<tag type><name>;<data type>;;<option1>;<option2>@

The DTD version of this takes the existing elements and reorders them as follows:

<start code block>
@~<name>
type = <data type>
description = <description>
printable = <printable>
<option1>
<option2>
...
@
@<tag type><name>@
<end code block>

As you can see, this usage also allows for the addition of two new elements: “description” and “printable”. Defining “printable” will define the main text for this tag in the SA Client. Defining “description” will create a description for this value in the SA Client that is viewable when you move your mouse pointer over the field in the value set editor in the SA Client.

Here is the same tag in full DTD format:

<start code block>
@~deny_header
type = unordered-string-set
printable = Headers to Deny
description = This is a list of headers that IIS should deny
sequence-delimiter = ":"
optional
@
@*deny_header@
<end code block>

There are a couple things to notice in the example above. In defining a value for “description,” the value can span multiple lines, as long as the lines following the first line have whitespace as the first character.

Options go on a line by themselves, where you have <option>=<value> you need to insert spaces before and after the "=" sign.

Now, where ever you use the tag @*deny_header@, the parser will use the predefined DTD for all that tags' information.

Redefining a DTD defined tag, @*deny_header@, by using a line like @*deny_header;unordered-string-set@ will cause the CML template to become invalid.