VTML Tag Definitions

Introduction

This page contains some documentation about layout and behavior of the VTML Tag Definitions (that is: tag definitions for VTML - all tag definitions are written in VTML!): how to use them and what (not) to expect from them. It will also explain why certain decisions were taken (like omitting input fields for LFWIDTH and LFHEIGHT). The current version number and date are mentioned with each description.

What this page does not do is explain is the techniques that were used to accomplish what they do: That sort of information is to be found in the Tips and Techniques section (on-line); where appropriate examples from these tag editors will be used.

One general user interface aspect of the VTML Tag Editors should be mentioned here rather than repeated everywhere: While it is not (yet) possible to mark an attribute as required in the VTML for the tag that uses that attribute, and pop up an error message when a required attribute is omitted, There is a half-way solution. Every attribute that is required is simply marked with an asterisk: . The same technique is used in all HTML and VTML tag editors; for the VTML tag editors the asterisk used is green, other colors are used in the HTML tag editors (while taking care that color difference never is the only signal). As with the HTML Tag Editors, required attributes are always written even if no value has been entered: this will serve as another visual reminder that a value really is needed for the attribute and should trigger an error message when validating the code.

All tag definitions are written in VTML 2 syntax and the Tag Editors also produce tags conforming to VTML 2 syntax (except those for WIZML statements as these do not use the new "XML" form). This new syntax was introduced with HomeSite and ColdFusion Studio 4.0 but is completely compatible with the older 3.x versions of these programs.

All tag definitions also contain full support for Tag Inspector and Tag Insight.
But all these tag definitions have also been kept completely compatible with HomeSite 3.01 / ColdFusion Studio 3.11: the tag editors that calculate LFWIDTH and LFHEIGHT still use the old method instead of the newly introduced numeric functions. Of course some of the new features like support for Tag Inspector will be active only when used with HomeSite 4.0 or ColdFusion Studio 4.0.

TagChooser

MarkUpTags.vtm

The updated version of MarkUpTags.vtm (the file that controls the TagChooser) that comes with this set of visual tag editors now completely exploits the techniques that were introduced for the VTML section only with the first release of this set of VTML tag editors on HomeSite Help. Some important properties of this version of TagChooser:

The HELPFILE attributes for all VTML and WIZML tags now refer to the new, more extensive VTML documentation files. The best way to take advantage of this is to use the "Show help in separate window." button : when this browser window is used, links to other pages work; if you use the "Toggle Embedded Help" button to show the help information, only links within a page will work. (The same is true for help for the visual tag editors.)
Better classification of tags; visually recognizable by specially-designed bitmaps.
MarkUpTags.vtm is now designed so that in the right-hand listbox you can see the difference between a tag that is inserted into your document directly and a tag that has a visual editor: tags that are inserted directly are shown as tag with angle brackets (<>), and if an end tag is written, that is shown as well. Tags for which there is a visual editor are shown only by name.

The last two points illustrate an important user interface design consideration: recognition is easier than recall. For instance, if you use the same tags over and over from the tag chooser, eventually you'll probably know (recall) which ones have an editor and which ones are inserted directly. But if the user interface can simply remind you of that fact (recognition) it'll be easier on your memory: you can use your brains to concentrate on the content rather than trying to remember which tag has an editor and which one doesn't. (Read more about this and other techniques for the MarkUpTags.vtm file in the Tips and Techniques: Tag Chooser page on-line.)

This technique for showing which tags have an editor and which ones don't is now used throughout this MarkUpTags.vtm file.

Tag Definitions

<TAG>

This is one of the simplest tag editors. BODYEDITING is now treated as a flag; code which uses "Yes" or "No" attribute values is recognized by the Tag Editor but Tag Inspector does not handle this correctly. Edit old code with the Tag Editor before using Tag Inspector.

<EDITORLAYOUT>

The EDITORLAYOUT tag accepts four attributes: WIDTH, HEIGHT, LFWIDTH and LFHEIGHT. The same is true for CONTAINER (TabDialog and Panel) and CONTROL. WIDTH and HEIGHT for EDITORLAYOUT are self-evident and accept only pixel values (if omitted some default will be used). LFWIDTH and LFHEIGHT are the equivalents that should come into play when the user has set Windows to use Large Fonts; alas, with HomeSite 3.01 and ColdFusion Studio 3.1 these attributes didn't work. Now, with the release of HomeSite 4.0 and ColdFusion Studio 4.0 this important feature is supported.

Now, how do you keep LF attributes in sync when changing a size? It's possible, but tedious. When you make a lot of those changes, it becomes easy to forget - and how much larger should the values be anyway?

The EDITORLAYOUT tag definition has a solution to this: LFWIDTH and LFHEIGHT no longer have input fields in the Tag Editor; instead there is a check box (on by default) that allows you to choose whether to have them generated: A fixed proportion is used that was determined experimentally to keep layout consistent and readable when Large Fonts are used. The calculation built into the Tag Editor rounds to a whole number of pixels, taking the possibility of a decimal comma into account. If your regional settings are set to use a comma as decimal separator (Number tab) the rounding in the calculations will still work. The editors for CONTAINER and CONTROL use the same technique.

Note that such calculations are not possible using Tag Inspector which allows you to edit each attribute separately (and allows you to make a mess of the layout for Large Fonts). Use Tag Editor with these tags to maintain proper layout!
Just like HTML, VTML does not need numerical attribute values to be quoted. So for reasons of consistency and efficiency, any numerical values (including negative numerical values that are possible for RIGHT and DOWN) are written without double quotes; if those same attributes have a non-numerical value, they are quoted. There is no need to think about this when filling in values in the text boxes: the TAGLAYOUT section takes care of this automatically. The same is true for sizes in CONTAINER and CONTROL.

<CONTAINER> (Tag Editors and Wizards)

As already mentioned for EDITORLAYOUT, the CONTAINER Tag Editor no longer has input fields for LFWIDTH and LFHEIGHT; for TabDialog and Panel the default is to generate these attributes automatically. Note that only numerical WIDTH and HEIGHT attribute values are considered for generating these attributes: they are simply not necessary for references to other fields or for "MAXIMUM".
The other controls have been re-grouped for clarity; everything to do with width is now in one column and everything to do with height in another.
The TabDialog tab also has an extra checkbox for enabling tabs on multiple lines.

<CONTROL> (Tag Editors and Wizards)

Everything already mentioned for LFWIDTH and LFHEIGHT with CONTAINER also holds here. The same is true for not quoting numerical values.

There are a few special aspects to mention about the CONTROL editor though:

Several editor controls were added for (originally) undocumented attributes that were found to be actually in use in some editors.
The control types DropDown, ListBox and RadioGroup are containers (unlike the other controls) and need an end tag; this end tag is now automatically written when the tag is created.
The content for DropDown, ListBox and RadioGroup is a set of ITEM tags; initial tags for these can optionally be generated by specifying the number of ITEM tags required. If you also specify the current indent level of the CONTROL tag, the whole tag will be properly indented as well, using TAB characters. All you need to do after this is edit the ITEM tags: the VALUE and CAPTION attributes are initially filled with the sequence number of the ITEM tag.
If you don't have ITEM tags generated for DropDown or RadioGroup controls, the cursor will end up between start and end tag; if you do, the cursor will end up after the end tag (this is currently unavoidable).
The default setting for SCROLLBAR is vertical; if you specify this, the attribute is not written.
For a Textarea when you specify a SCROLLBAR setting which includes a horizontal scrollbar ("horizontal" or "both") and you specify WRAP as well, the editor assumes you do indeed mean the Textarea to wrap text automatically, and it will "remove" any horizontal scrollbar from the SCROLLBAR setting: "horizontal" will be converted to "none" and "both" will be logically converted to "vertical" (the default: not written).
A FileBrowser control allows a complicated set of attributes that interact. The Tag Editor uses layout and notes to explain their relationship and takes this into account when writing or editing such a tag. (Tag Inspector, of course, has no way to support this.)
Several attributes now treated as a Flag. See the remark for TAG about how to treat this with Tag Inspector.
When writing the tag, the difference in syntax between empty tags and container tags (for control types DropDown, ListBox and RadioGroup) is taken into account.
For a StyleTextArea you can now specify the new INLINESTYLE attribute.
Support for the new ImgMapTextArea was added.

<ITEM> (Tag Editors and Wizards)

There is no vertical layout for the ITEM tag. All attributes are written on a single line, with VALUE and CAPTION (and the flag SELECTED, if defined) separated by a TAB character (you may have to add one or more tabs manually to get the CAPTION attributes to line up).
SELECTED treated as a Flag. See the remark for TAG about how to treat this with Tag Inspector.
The Tag Editor generates VTML 2 syntax.

<ATTRIB>

The TABLE tag editor which comes with HomeSite 3.01 / ColdFusion 3.11 has (empty) DEFAULT attributes in the ATTRIB tags. This attribute is obsolete; the Tag Editor takes care of this by throwing it out when editing such a tag (and input is not possible). However, this also means Tag Inspector will display this attribute since there is as yet no way to suppress attributes from showing up in Tag Inspector. There is an ATTRIBGROUP "Default", however.
The new attributes for VTML 2 (TYPE and CACHEFAMILY) are supported.
The content for type Enumerated is a set of ATTRIBOPTION tags; initial tags for these can optionally be generated by specifying the number of ATTRIBOPTION tags required. If you also specify the current indent level of the ATTRIB tag, the whole tag will be properly indented as well, using TAB characters. All you need to do after this is edit the ATTRIBOPTION tags: the VALUE and CAPTION attributes are initially filled with the sequence number of the ATTRIBOPTION tag.
Like the ITEM tag editor, there is no vertical layout for the ATTRIB tag; attributes are separated by a TAB character.
When writing the tag, the difference in syntax between empty tags and container tags (for TYPE Enumerated) is taken into account.

<ATTRIBOPTION>

A very simple tag definition with just two attributes: VALUE and CAPTION (similar to the ITEM tag).

<EVENT>

This tag definition supports only a single attribute: the event name. But it is not as simple as it seems: For both a Tag Editor and Tag Inspector the difference between HTML 4.0 standard events and other events supported as extensions by some browsers and scripting languages is made obvious. In the Tag Editor, choosing a standard event overrules the choice of a browser/language-specific event.

<ATTRIBCATEGORIES>

The tag ATTRIBCATEGORIES itself does not take any attributes. The only function of this tag definition is to allow a Tag Editor to generate initial ATTRIBGROUP tags. This generation works the same way as generation of ITEM tags for a CONTROL or generation of ATTRIBOPTION tags for an ATTRIB. ATTRIBGROUP tags are written with the value of NAME and ELEMENTS attributes initially filled with the sequence number of the ATTRIBGROUP tag.

<ATTRIBGROUP>

A very simple tag definition with just two attributes: NAME and ELEMENTS.

<TAGLAYOUT>

The TAGLAYOUT editor is quite simple. There are now only two attributes: SECTION and TRIMWHITESPACE. For both attributes the rule is that it will not be written if the chosen value is default.

Support for the new TRIMWHITESPACE attribute was added in version 2.04.

<TAGDESCRIPTION>

Not much to report here except it tries a little harder than the original in HomeSite and ColdFusion Studio 3.0 to get the layout correct when you don't enter a helpfile but enter a tag body instead.

Note: The Tag Editor supports BodyEditing for embedded help text. HTML markup can be included (though HomeSite and ColdFusion Studio 3.x do not support editing markup in an exiting tag body).

When writing the tag, the difference in syntax between an empty tag (reference to a help file) and a container tag (help information included as a tag body) into account.

Wizards

<WIZARD>

A simple tag editor with three optional attributes. The only thing of note is that in the Tag Editor the IMAGE attribute is supported with a file browser while the TAGLAYOUT section takes care of converting the relative URI syntax into the special syntax needed by a Wizard. To avoid problems with this syntax, the data type for this attribute in Tag Inspector is kept as "Text" (default) instead of "Relativepath" since Tag Inspector cannot do such processing when writing an attribute value.

<PARAM>

Writing this tag definitions presented an interesting problem: HTML has a PARAM tag, used with the APPLET tag and in HTML 4.0 with the OBJECT tag. In VTML 2, PARAM can be used in combination with the WIZARD tag and with the PAGE tag. In all four cases, the set of possible attributes is somewhat different although there is an overlap; and for Wizards the VALUE attribute is required while it isn't for Applets and Objects.

The original idea was to simply make a different tag definition for HTML and Wizard VTML. But both must be PARAM.VTM. With HomeSite 3.01 and ColdFusion 3.11 the problem was immediately obvious: all tag definitions must be in the same directory and you can't have two of the same name; a different name for one would allow inserting a new attribute using a different definition - but not editing an existing tag. For HomeSite 4.0 and ColdFusion 4.0 there seemed to be a solution: tag definitions are sorted into different subfolders; but no, these programs use a searching algorithm to find a tag definition: while different ones of the same name are possible, only one will ever be used: the one the searching algorithm finds first.

What you'll find here is the workaround for this name-space ambiguity problem: a single tag definition that includes the functionality both for use with HTML (for APPLET and OBJECT) as well as for use with Wizard VTML (for WIZARD and PAGE). Here's how it works:

The Tag Editor has an extra VTML (Wizards) tab next to the HTML tabs. Choosing a tab determines the Tag Editor's behavior.
When inserting a PARAM tag from the Tag Chooser, either the main HTML tab or the VTML tab will be preselected. (The technique for doing this is explained on the Tips and Techniques: Tag Chooser page on-line.)
The VTML tab contains another TabDialog with two pages: one for use with a WIZARD, and one for use with a PAGE. Again, choice of one tab page determines behavior of the editor. Preselection of one of these (embedded) tabs is also possible when inserting a new tag from the Tag Chooser.
When editing an existing tag, such preselection is not possible since the control for this is not an attribute of the tag itself: you'll have to choose the appropriate tab page for what you are editing.

You should always make sure you're using the correct tabs when writing a tag with this Tag Editor; differences in behavior include writing VTML 2 syntax for VTML and treatment of required and optional attributes.

In Tag Inspector, the control attributes used for tab preselection will show up in the normal view as long as there is no mechanism to prevent this; in the Categorized view they won't be visible and HTML and VTML have separate categories.

<TEMPLATE>

A simple tag definition which supports all four possible attributes. For now, controls are all simple textboxes and data types all default (Text).

<PAGE>

A tag definition with support for all documented attributes. Same handling of the IMAGE attribute as with the WIZARD tag definition.

For a Tag Editor, the attribute TYPE="Dynamic" which is required for user-defined Wizards, is treated as un uneditable required attribute. For Tag Inspector this is documented by using an enumerated type with just one value and an appropriate caption.

<INPUT>

Similar to the PARAM Tag Definition, the INPUT tag definition includes the functionality both for use with HTML (for FORMs) as well as for use with Wizard VTML (for WIZARD). Here's how it works:

The Tag Editor has an extra VTML (Wizards) tab next to the HTML tabs. Choosing a tab determines the Tag Editor's behavior.
When inserting an INPUT tag from the Tag Chooser, either the main HTML tab or the VTML tab will be preselected. (The technique for doing this is explained on the Tips and Techniques: Tag Chooser page on-line.)
When editing an existing tag, such preselection is not possible since the control for this is not an attribute of the tag itself: you'll have to choose the appropriate tab page for what you are editing.

You should always make sure you're using the correct tabs when writing a tag with the Tag Editor; differences in behavior include writing VTML 2 syntax for VTML and treatment of required and optional attributes.

In Tag Inspector, the control attribute used for tab preselection will show up in the normal view as long as there is no mechanism to prevent this; in the Categorized view they won't be visible and HTML and VTML have separate categories.

<NEXTPAGE>

A simple tag definition with just two required attributes. Although the second attribute is a condition, no condition builder as in WIZIF has been included for now.

WIZML logic

<WIZIF>

WIZIF takes only one argument: a condition. Alas, an argument is not the same thing as an attribute which can always be recognized by a keyword. This implies that it is (currently) impossible for a tag editor to read and display the condition in a WIZIF (or WIZELSEIF) statement.

But when starting out with VTML (WIZML in this case) many people have trouble remembering how to write the comparison operators (always depending on what other programming languages you've used before). So again on the principle that recognition is better than recall, a write-only tag editor was created with a simple condition builder. At least that will remember the comparison operators for you, and it makes a reasonable stab at creating syntactically correct conditions with brackets where appropriate. If you edit a WIZIF tag with it, you will have to re-build the expression (which may actually turn out to be better than editing one).

<WIZELSEIF>

Essentially the same as the WIZIF editor; it only writes a different tag.

<WIZLOOP>

WIZLOOP is a little easier than WIZIF/WIZELSEIF since it does have real attributes that can be recognized and displayed in the editor. One problem remains: there are three types of WIZLOOP (at least I'm supporting three types) but the type is not indicated by an attribute.

I've chosen to have a tab page for each type, but when editing a WIZLOOP tag, the tab page will not (cannot) be selected automatically.

The tab for a conditional loop contains a condition builder like the one for WIZIF and WIZELSEIF. But there's a difference: in WIZLOOP the condition is indicated by a keyword so while editing the tag the current expression can be displayed as a string. (Of course it cannot be parsed into the separate pieces in the condition builder.) Now you have the choice: either you edit the current condition as a string, or you use the condition builder to create a new one. If you do both, the editor remembers the condition string as it was before you edited it, and uses the fact it was changed to give precedence to the edited condition rather than the input in the condition builder. It's a straight string comparison, so if you edit and end end up with the same string, the tag editor should not notice any change.

<WIZINCLUDE>

In HomeSite 3.01 and ColdFusion Studio 3.11 the statement WIZINCLUDE worked only in Wizard templates which could be customized (though Wizard user interfaces could not). For HomeSite / ColdFusion Studio 4.0 and later we can now define our own Wizards so WIZINCLUDE has a more important function. However, WIZINCLUDE still does not work inside the context of a Tag Editor.