Building Tag Editors

Defining a Tag Editor requires three tasks:

Layout of the dialog which forms the user interface
Definition of how to populate controls with tag attributes
Definition of the tag generation template

Open the file \Extensions\TagDefs\mytag.vtm to see how these tasks are coded. The following section will explain how to create the editor file.

Defining the user interface

The user interface is defined in the EDITORLAYOUT section. This section can contain only two kinds of tags: CONTROL and CONTAINER tags. CONTROL and CONTAINER tags represent graphical controls. The tags are similar in definition, with the exception that only CONTAINER tags have the capability to contain other CONTROL tags. They share a number of common attributes.

A Panel is a good example of a container with controls, such as Labels or TextBoxes.

Look at the following example:

<TAG>
    <EDITORLAYOUT HEIGHT=50 WIDTH=200>
        <CONTAINER  NAME="Panel1" TYPE="Panel" WIDTH=150 HEIGHT=50>
            <CONTROL NAME="lblCode" TYPE="label" CAPTION="Code" DOWN=20
                RIGHT=20 WIDTH=70/>
            <CONTROL NAME="txtCode" TYPE="TextBox" ANCHOR="lblCode"
            <CORNER="NE" WIDTH="30"/>
        </CONTAINER>
    </EDITORLAYOUT>
</TAG>

This code generates a Panel Container with Label and TextBox Controls. Notice how the attributes define the container and its contents:

The controls are specified by the value of the TYPE attribute.
The WIDTH and HEIGHT attributes determine the size of controls.
The ANCHOR attribute names an existing control from which the relative position of additional controls can be calculated.
The CORNER attribute specifies the corner of the anchor control to be used for positioning. The values are NE, NW, SE, and SW. The DOWN and RIGHT attributes are pixel values for the offset from the anchor control.

You can save the example code as mytag.vtm and test it by editing an empty MYTAG tag. The tag editor dialog box would look like this:

There are only three types of containers:

TabDialog -- A tab dialog control capable of containing TabPage container controls.
TabPage -- Used only inside a TabDialog container control.
Panel -- A general purpose panel container control.

Escaping special characters

In displayable strings used in the tag editor dialog, the C-language convention (\) for escaping special characters can be used. In the following example the CAPTION attribute uses a newline character to split the value into two lines:

<CONTROL NAME="lblXmp" TYPE="label" CAPTION="This is line one\nThis is line two"/>

Other special characters of note include carriage-return (\r), tab (\t), quote (\'), double quote (\"), and backslash (\\).

Populating dialog boxes with tag data

Once the layout of controls is completed you need to define the way in which the editor controls are populated when you are editing an existing tag. This is done in the ATTRIBUTES block of the main tag editor template.

The ATTRIBUTES block can contain ATTRIB and EVENT tags. The ATTRIB tag defines the way tag attribute values get filled into the dialog controls.

<ATTRIBUTES>
    <ATTRIB NAME="VALUE" CONTROL="txtName"/>
    <ATTRIB NAME="TITLE" CONTROL="txtTitle"/>
    <ATTRIB NAME="TITLE" CONTROL="txtTitle2"/>
    <ATTRIB NAME="ALT" CONTROL="txtAltText"/>
    <ATTRIB NAME="ALIGN" CONTROL="dropAlign"/>
</ATTRIBUTES>

The NAME attribute of the ATTRIB tag specifies the name of the attribute, while the CONTROL attribute specifies which control in the user interface the value of that attribute should be assigned to. Notice that you can have multiple ATTRIB tags with the same NAME. This is common for more complex tag editor dialog boxes where a single attribute value may have to be filled into multiple controls.

Special ATTRIB tag variable names

$$TAGBODY -- This special tag attribute name is used when a control needs to be populated by the body of a tag. An example of such a tag editor is the editor for the HTML tag TEXTAREA. The body of the TEXTAREA tag is filled into the txtTextAreaContent control using the following ATTRIB tag.

<ATTRIB NAME="$$TAGBODY" CONTROL="txtTextAreaContent"/>

$$TAGSTRING and $$WHOLETAGSTRING -- These attributes can be used to populate controls with the start-tag string or the whole tag including its start-tag, body and the end-tag. This allows ActiveX controls to be passed the entire tag for custom processing and specialized tag editor behavior.

Consult the Special variables section of the ATTRIBUTES reference for more information about these special variables.

Generating a tag

The final stage in building a tag editor is defining how a tag gets generated from the data in the editor controls. The tag generation logic is stored in one or more TAGLAYOUT sections. Together, these sections form a template used to generate the final tag string.

Note

The markup language used for the TAGLAYOUT template was originally designed for coding wizards and was therefore called the Wizard Markup Language (WIZML). Because of this, all the tags in this section begin with the WIZ prefix.

Consult the WIZML section for more information on this language. You can also look at the TAGLAYOUT sections of existing HTML tag editors located in the \Extensions\TagDefs\HTML directory.

Variables passed to the layout template

WIZML supports variables and functions. The value of each control of the tag editor is passed to the template using a variable with the same name. A ColorPicker named colorBGColor passes its value in the colorBGColor variable. The TAGLAYOUT template can then use this data to generate the tag string.

<TAGLAYOUT>
    <MYTAG COLOR="$${colorBGColor}">
</TAGLAYOUT>

This example shows a simple layout template for a tag with a single attribute. In WIZML, variables are embedded using the $${} delimiters. If the user chose White in the colorBGColor ColorPicker, the template would generate the following tag:

<MYTAG COLOR="White">

Special variables

In addition to the CONTROL variables, a few other parameters get sent to the tag layout template:

OPTIONLowerCaseTags -- Returns 'True' or `False' to specify whether the tag should be generated using lowercase.
EDITORTagIndentString -- Maintains indentation for tag attributes and body.
OPTIONLinearLayout -- Returns `True' or `False' to specify whether the tag should be generated with its attributes in a single line or not.
TAGDATAUnknownAttributes -- Returns a string containing all attributes which were contained in the edited tag string but are not recognized by the editor.
TAGDATATagBodyString - Contains the unedited tag body.

Consult the Special variables section of the TAGLAYOUT reference for more information about these variables.


Customizing the Development Environment