Building Tag Editors

Defining a Tag Editor is composed of three tasks:

Layout the dialog box controls.

Specify how to populate the controls with tag attributes.
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:

TabDialog A tab dialog control capable of containing TabPage container controls.

TabPage Only used inside a TabDialog container control.

Panel A general purpose panel container control which can contain any regular or container controls.

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:

$$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 code:
```
<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 to the entire tag for custom processing and specialized tag editor behavior.

$$EmbeddedCodeString Represents just the text within a tag. It excludes the tag name, delimiters, and white space outside the text block.

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:

OPTIONLowerCaseTags Returns true or false. Specifies whether the tag should be generated using lowercase.

EDITORTagIndentString Maintains indentation for tag attributes and body.

OPTIONLinearLayout Returns true or false. Specifies whether the tag should be generated with its attributes in a single line or not.

TAGDATAUnknownAttributes A string containing all attributes which were contained in the edited tag string but are not recognized by the editor.

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.

LiveDocs comments are not longer enabled for ColdFusion 5.0. Please use one of the following resources instead.

Version 5.0

Using HomeSite
Customizing the Development Environment