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.
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:
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 (\\).
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.
$$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.
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.
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">
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.