Building Tag Editors

Defining a Tag Editor is composed of three tasks:

  1. Layout the dialog box controls.
  2. Specify how to populate the controls with tag attributes.
  3. Define the tag generation template.

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

Defining controls

The control and container tags represent graphical controls. The tags are nearly identical in definition, the difference being that only container tags have the capability to contain control tags.

A Panel control is a good example of a control that can be a container containing a control, such as a label or a text box:

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

You can name the above template mytag.vtm and test it by attempting to edit an empty mytag tag.

The example displays a single Panel container containing Label and TextBox controls. Only a few controls can be containers:

The control represented by a control or a container tag is defined by the type attribute, the width and height attributes determine the size.

The anchor and corner attributes determine the point relative to which the control is positioned. The anchor can be specified as the name of any control that was already laid down. The corner specifies the corner of the anchor control to be used for positioning. The possible values are NE, NW, SE, and SW. The down and right attributes then specify the pixel offset from the anchor control.

See control and container in the VTML Reference for syntax and usage information.

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 in which tag attribute values are inserted 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 control specifies which control the value of that attribute should be assigned to. 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

The following special variables can be used:

Generating a tag

The final stage in the process of building a tag editor is defining how a tag gets generated from the date entered in the editor controls. The tag generation logic is stored in the taglayout block. This block contains a short template used to generate the final tag string.

A good way to get started is to have a look at the taglayout sections of existing HTML tag editors located in the \Extensions\TagDefs\HTML directory.

See taglaout in the VTML Reference for syntax and usage information.

Variables passed to the layout template

The value of each control of the tag editor is passed to the template using a variable with the same name, for example, a ColorPicker control named colorBGColor will pass its value in a 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 hypothetical tag with a single attribute, color. Notice that variables are embedded using the $${} delimiters. If the user selects White in the colorBGColor ColorPicker control, the template generates this tag:

<mytag color="White">

Special variables

In addition to the control variables, a few other parameters get sent to the taglayout template:

Using OPTIONLowerCaseTags

You can use this parameter to create a layout template, which generates a tag in lower or upper case based on user preferences. 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>

Maintaining tag indentation

The variable EditorTagIndentString contains an indentation string for the currently selected tag. If the start tag is indented using tabs and characters, the string is represented as the corresponding combination of tabs and spaces. This variable can be used to correctly indent tag attributes, as well as tag body contents for tags which are already indented.

Using OPTIONLinearLayout

Here is a version of the mytag layout template that responds to user preferences for single line or indented layout:

<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 template would generate a tag based on the following user layout preference:

LINEAR:

<mytag color="White" face="Arial" SIZE="10">

NONLINEAR:

<mytag color="White" 
  face="Arial" 
  size="10">

Using TAGDATAUnknownAttributes

The TagDataUnknownAttributes tag contains the list of attributes that are contained in the original tag string but are not supported by the editor. For example, you can write an editor for the HTML tag input. that provides editing capabilities for all basic attributes, however, the editor will not cover JavaScript event attributes such as, onCLick). To prevent loss of what are in effect 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 you edit a tag <mytag color="Blue" onClick="CallThis">, the above template preserves the onClick attribute even though it is not supported in the editor.

Comments