TAGLAYOUT Sections

The final stage in the process of building a Tag Editor is the definition of how a tag gets generated from the data entered in the tag editor controls. The tag generation logic is stored in one or more TAGLAYOUT sections. This section contains a template used to generate the final tag string. The WIZard Markup Language (WIZML) elements used within the TAGLAYOUT sections were originally designed for Wizards. 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.

Location

This tag can occur only within a TAG tag in a Tag Definition file.

Function

A Tag Editor 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, such as generating code.

Syntax and Attributes

<TAGLAYOUT .../>
SECTION Optional. The section that will be written. Possible values are:
  • StartTag (default)
  • TagBody
  • EndTag
TRIMWHITESPACEVTML 3 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: For a description of a problem with BODYEDITING - see Tag.html.

Variables passed to the TagLayout sections

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 passes its value in the colorBGColor variable. The WIZML code 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 sample tag with the single attribute COLOR.

To output the value of a variable within a template, a double dollar sign escape sequence ($$VariableName) is used. 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 selects White in the colorBGColor  ColorPicker the above template would generate the following tag:

<MYTAG COLOR="White">

Special Variables

In addition to the CONTROL variables a few other special variables are exposed sent to the TAGLAYOUT sections.

Using OPTIONLowerCaseTags

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 in Options > Settings > Markup Languages > Lowercase all inserted tags. 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.

Using OPTIONLinearLayout

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 in Options > Settings > Markup Languages > When editing tags, return the output on a single line. 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>

Using EDITORTagIndentStringVTML 3

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.

Using TAGDATATagBodyStringVTML 2

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>

Using TAGDATAUnknownAttributes

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 in this release only cover event "attributes", such as, onCLick, 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 lose "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!

top