The final stage in the process of building a Tag Editor is the definition of how a tag gets generated from the data entered into the tag editor controls. The tag generation logic is stored in one or more TAGLAYOUT sections. Such a section contains a template used to generate the final tag string. The markup language used within the TAGLAYOUT sections was originally designed for Wizards; this is where the name of this "sub-language" comes from: WIZard Markup Language (WIZML). All WIZML tags begin with the WIZ prefix.
A good way to get started with the logic defined with WIZML tags is to have a look at the TAGLAYOUT sections of existing Tag Definitions located in several subfolders of the Extensions\TagDefs folder below the main installation folder.
The following subjects are covered in this document:
Related information about VTML and WIZML:
|
TAGLAYOUT plays a role in the following VTML-driven tools:
This tag can occur only within a TAG tag in a Tag Definition file.
If a Tag Editor is to write anything, it must have at least one TAGLAYOUT section. The default section is StartTag. Each TAGLAYOUT is a container which can contain only WIZML statements. The StartTag section can be used for initialization of variables, calculations, etc. Its main function is to write out code using variables either initialized here or given a value in the visual editor. For an empty tag, generally only the StartTag section is necessary; for a container tag, the EndTag section can be used to create the end tag, while there can be an optional TagBody section before that to write out the data from the $$TagBody special variable.
The function of the three possible sections determines their behavior; for special cases this behavior can be used for other purposes, like for instance code generation rather than editing markup tags.
Defaults indicated in bold.
<TAGLAYOUT .../> | |
---|---|
SECTION |
Optional. The section that will be written. Possible values are:
|
TRIMWHITESPACE![]() |
YES/NO. If not specified, or "Yes", all white space defined at the end of on section or the start of the next will be suppressed.
Specify the attribute with a value of "No" to prevent this "White Space Gobbler" effect; this wil lmake a more precise control of code layout possible.
The default is "No" to ensure compatibility with older versions of VTML. Note: There is still a problem with BODYEDITING - see the description in Tag.html. |
WIZML is described in separate files though a few things should be noticed. WIZML supports variables as well as expressions. The value of each control of the tag editor is passed to the TAGLAYOUT sections using a variable with the same name. Therefore a ColorPicker named colorBGColor will pass its value in the colorBGColor variable. The WIZML in the TAGLAYOUT section can then use this data to generate the tag string.
<TAGLAYOUT> <MYTAG COLOR="$$colorBGColor"/> </TAGLAYOUT>
The above example shows a simple layout template for a hypothetical tag with a single attribute COLOR.
To output the value of a variable within a template, a double dollar sign escape sequence ($$VariableName) is utilized. For example, to output the value of a variable named Color you would use the following syntax: $$Color. It may be necessary to delimit the variable name from literal text following it (the $$ sequence itself serves as a delimiter for whatever comes before it); in such a case the variable name can be enclosed in braces ( { } ) serving as delimiters (effectively turning it into an expression).
If the user chose White in the colorBGColor ColorPicker the above template would generate the following tag:
<MYTAG COLOR="White">
In addition to the CONTROL variables a few other special variables are exposed sent to the TAGLAYOUT sections.
This variable can be used to generate a tag in lower or upper case based on user preferences: the value of this attribute is dependent on the user's setting for "Lowercase all inserted tags" checkbox on the HTML pane of the Setup dialog. Here is a version of the MYTAG layout template responding to case preferences:
<TAGLAYOUT> <WIZIF OPTIONLowerCaseTags EQ 'true'> <mytag color="$$colorBGColor"> <WIZELSE> <MYTAG COLOR="$$colorBGColor"> </WIZIF> </TAGLAYOUT>
Note that the same effect (responding to user preferences for tag case) can be accomplished by using the DefaultCase() function. Use of this function instead of OPTIONLowerCaseTags will lead to more compact and maintainable code. More about this in Expressions and Functions.
Some people like their tag attributes in a single line while other like them indented. This variable can be used to generate a complete (start) tag all on a single line or with each attribute on a new line, based on user preferences: the value of this attribute is dependent on the user's setting for "When editing tags, return the output on a single line" checkbox on the HTML pane of the Setup dialog. Below is a version of the MYTAG layout template responding to such preferences. Note that here the variable Spacer is concatenated with some literal text FACE and SIZE), so it needs to be enclosed in braces serving as delimiters.
Note that this variable refers only to the layout of a start tag (of a container) or of an empty tag; it has no influence on the layout of the tag body or on the placement of the end tag.
<TAGLAYOUT> <WIZIF OPTIONLinearLayout EQ 'true'> <WIZSET Spacer = ' ' > <WIZELSE> <WIZSET Spacer = Chr(13) & Chr(10) & ' ' > </WIZIF> <MYTAG COLOR="$$clrBGColor"$${Spacer}FACE="$$fontFace"$${Spacer}SIZE=$$txtSize> </TAGLAYOUT>
The above code would generate the tag in the following forms based on the layout preference:
Linear:
<MYTAG COLOR="White" FACE="Arial" SIZE=10>
Nonlinear:
<MYTAG COLOR="White"
FACE="Arial"
SIZE=10>
This is useful for maintaining indentation in a document when editing tags. The variable contains an indentation string for the currently selected (edited) tag. If the start tag starts on a new line and is indented using tabs and/or space characters the string in this variable contains the corresponding combination of tabs and spaces. This variable can be used to correctly indent tag attributes (if OPTIONLinearLayout is false) or tag body contents for tags which are already indented.
This variable is available only if the TAG tag has the BODYEDITING flag defined and the user is editing a container tag. In that case, this variable will contain the original content of the tag body: this can be useful for comparison with the edited result in $$TagBody or just to test its contents with a function like Find() and take action depending on the results.
<WIZIF checkHtmlComments EQ 'true' AND NOT Find(TAGDATATagBodyString,'<!--')>$$HtmlStartComment</WIZIF>
Contains the list of attributes which were contained in the original tag string but are not supported by the editor. For example the Tag Editors released with the latest version of the program (HomeSite 4.01 / ColdFusion Studio 4.01) only cover event "attributes" (e.g. onCLick= ... etc.) that are defined in HTML 4.0. Any non-standard scripting content already defined in a tag that is not covered by a corresponding control in the Tag Editor would be lost upon editing were it not for TAGDATAUnknownAttributes.
In order not to loose "unknown" attributes during the editing process the editor engine creates the TAGDATAUnknownAttributes variable containing a list of unknown attributes together with their original values. You can use this variable to "stamp" all the unsupported attributes at the end of the tag you are generating.
<TAGLAYOUT> <MYTAG COLOR="$$colorBGColor"<WIZIF TAGDATAUnknownAttributes NEQ ''> $$TAGDATAUnknownAttributes</WIZIF>> </TAGLAYOUT>
If we edited a tag <MYTAG COLOR="Blue" Max=3 onClick="CallThis">
the above template should preserve the Max and onClick attributes despite the fact that it is not supported in the editor.
The editor is also intelligent enough to list the unknown attributes in a linear or indented format based on users' layout preferences described
in the previous section.
Note: TAGDATAUnknownAttributes does not exactly preserve the original tag elements:
Currently the case of attribute names in TAGDATAUnknownAttributes is not preserved (though case of the attribute
values is). Also double quotes are put around all attribute values, even ones that were originally unquoted or singly-quoted.
With the case preference for tags set to uppercase, the example above would actually be rewritten as:
<MYTAG COLOR="Blue" MAX="3" ONCLICK="CallThis">
This behavior may invalidate any language elements (scripting or pre-processor) for which such keywords are case-sensitive or where quoting determines
the difference between a number (numerical value) and a string!