Defining a Tag Editor is composed of three tasks:
Open the \Extensions\TagDefs\mytag.vtm file to see how these tasks are coded. The following section explains how to create the editor file.
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:
TabPage
container controls.
TabDialog
container control.
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.
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.
The following special variables can be used:
textarea
. The body of the textarea
tag is filled into the txtTextAreaContent
control using the following attrib
code:
<attrib name="$$TAGBODY" control="txtTextAreaContent"/>
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.
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">
In addition to the control variables, a few other parameters get sent to the taglayout
template:
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>
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.
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:
<mytag color="White" face="Arial" SIZE="10">
<mytag color="White"
face="Arial" size="10">
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.