VTML Tag Definitions: Documentation

On this page:

Introduction MarkUpTags

Tag Editorlayout Container Control Item Attrib Attriboption Event Attribcategories Attribgroup Taglayout Tagdescription

Wizard Param Template Page Input Nextpage

Wizif Wizelseif Wizloop Wizinclude

This page contains some documentation about layout and behavior of my VTML Tag Definitions: 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. There is now also a separate page with a release history of these tag editors.

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; 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, I found a half-way solution. Every attribute that is required is simply marked with an asterisk: . The same technique is used in all my tag editors; for the VTML tag editors the asterisk used is green, other colors are used in the HTML tag editors (but I took care that color difference never is the only signal). 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.

The set has now been completely revised and extended for VTML 2: all new tags, tag attributes and controls introduced with VTML 2 are fully supported - including the tags for writing Wizards. Since I don't have much experience with the latter yet, they are designed simply to support the tags and attributes as documented in VTML for Wizards (Wizards.html) in the Extensions\Docs\VTMLTags folder of HomeSite 4.01 and ColdFusion 4.01. (If you don't have the maintenance release or even version 4.0: this same file comes with the VTML documentation included in the tag definition sets you can download from here. But building your own Wizards is possible only with as of version 4.0 or HomeSite and ColdFusion Studio.)

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). 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: these programs understand tag definitions in the new syntax but not the new controls; for that reason, Control.vtm can write all of the new controls but does not itself use them so HS3.01/CFS3.11 can still be used as a development platform for creating Tag definitions and even Wizards in VTML 2. For the same reason, 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.

The updated version of MarkUpTags.vtm: the file that controls the tag chooser) that comes with this set of visual tag editors now completely exploits the techniques I had introduced for the VTML section only with the first release of my VTML tag editors. Some important differences with the previous version released by Allaire:

1. 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.)
2. The file is now also written in VTML 2 syntax which is understood by HomeSite 3.01 and ColdFusion Studio 3.11 without any problem.
3. Better classification of tags; visually recognizable by specially-designed bitmaps.
4. 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.)

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

A section for SMIL tags has been included to ensure compatibility with HomeSite 4.0 and ColdFusion Studio 4.0; visual support for the difference between directly inserted tags and those that are supported by a tag editor has been added here as well to keep this consistent with the other sections. (Note that HS3.01/CFS3.11 do not include the tag editors for SMIL.)

Version 2.03 - 1999-04-02

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.

Version 2.03 - 1999-02-07

Some important differences with the original Allaire release:

• 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?

  My 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 I 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.

Version 2.03 - 1999-02-07

Important differences with the original Allaire release:

• 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.

Version 2.03 - 1999-02-07

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 Radio Group 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 Radio Group 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 Radio Group 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.
• The Tag Editor generates VTML 2 syntax, taking the difference between empty tags and container tags (for control types DropDown, ListBox and RadioGroup) into account.

Version 2.03 - 1999-02-28

Important differences with the original Allaire release:

• 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.

Version 2.03 - 1999-02-07

Important differences with the original Allaire release:

• 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.
• The Tag Editor generates VTML 2 syntax, taking the difference between empty tags and container tags (for TYPE Enumerated) into account.

Version 2.03 - 1999-02-07

A very simple tag definition with just two attributes.

The Tag Editor generates VTML 2 syntax.

Version 2.03 - 1999-02-07

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.

Version 2.03 - 1999-02-07

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.

The Tag Editor generates VTML 2 syntax.

Version 2.03 - 1999-02-07

A very simple tag definition with just two attributes.

The Tag Editor generates VTML 2 syntax.

Version 2.03 - 1999-02-07

The TAGLAYOUT editor is quite simple. There is only one attribute: SECTION. This attribute will not be written if the chosen value is "StartTag" since this is the default. This value is also selected by default.

Version 2.03 - 1999-02-07

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

Note: You can write the tag body using markup tags, and they will be written. However, these get lost (at least in HomeSite 3.01 / ColdFusion Studio 3.11) when reading the tag for editing due to how the WIZML parser works.

The Tag Editor generates VTML 2 syntax, taking the difference between and empty tag (reference to a help file) and a container tag (help information included as a tag body) into account.

Version 2.03 - 1999-02-07

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.

Version 2.03 - 1999-02-22

With this tag I ran into 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.

Originally I set out 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. And (for now) tag definitions are cached, so you cannot dynamically change what would be found by renaming a folder or tag definition.

What you'll find here is the workaround I came up with: 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.)
• 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 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 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 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.

Version 2.03 - 1999-02-28

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

The Tag Editor generates VTML 2 syntax which should be supported in HomeSite / ColdFusion Studio 4.0 although the Wizards released with these products do not (yet) use it.

Version 2.03 - 1999-02-07

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.

Version 2.03 - 1999-02-07

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.)
• 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.

Version 2.03 - 1999-02-28

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.

Version 2.03 - 1999-02-07

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. (Believe me, I tried - hard!)

But when I started out with VTML (WIZML in this case) I had trouble remembering how to write the comparison operators. So again on the principle that recognition is better than recall, I created a write-only tag editor 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).

Version 2.03 - 1999-02-07

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

Version 2.03 - 1999-02-07

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.

Version 2.03 - 1999-02-07

In HomeSite 3.01 and ColdFusion Studio 3.11 the statement WIZINCLUDE worked only in Wizards (which were not user-definable anyway), not in Visual Tag Editors (alas). For HomeSite / ColdFusion Studio 4.0 we can now define our own Wizards so WIZINCLUDE now has a real function. However, this still does not work inside the context of a Tag Editor.

Version 2.03 - 1999-02-07