Building Tag Editors

Defining a Tag Editor requires three tasks:

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:

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:

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:

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