The ATTRIBUTES section is the most important section in a Tag Definition file because its contents determine part or all of the behavior of four different VTML-driven tools: Tag Editors, Tag Inspector, Tag Insight and Tag Tips.
The ATTRIBUTES section can have only two types of content: ATTRIB and EVENT tags, but it is an extremely important part of a Tag Editor file. It is not only the basis of much of the behavior of the visual part of a Tag Editor, it also provides all of the information for Tag Insight and Tag Tips and most of the information for Tag Inspector.
Apart from ATTRIB and EVENT tags, normal HTML comments are possible; these can be quite useful when arranging ATTRIB and EVENT tags for a tag with many possible attributes and events.
This tag can occur only within a TAG tag in a Tag Definition file.
When editing an existing tag, the ATTRIBUTES section handles the input of the attribute values into the controls of the Tag Editor. Thus, for each attribute in the tag that needs to be edited, there should be an ATTRIB tag in the ATTRIBUTES section.
The NAME attribute of the ATTRIB tag specifies the name of the attribute to be picked up, while CONTROL specifies which control the value of that attribute should be assigned to. The CONTROL attribute should correspond to the name of a control in the EDITORLAYOUT section. Note that NAME corresponds to the name of the attribute in the tag; it is not the name of the variable for use in the TAGLAYOUT section. The variable name is the same as the name of the control, that is, the thing that holds the value within a Tag Editor.
Notice that you can have multiple ATTRIB tags with the same NAME, each corresponding to a different control.
This is common for more complex Tag Editor dialogs where a single attribute value may have to be
filled into multiple controls.
For example, this naming convention can be used to display a current attribute value in a label control while also making
the value editable in a text box or to display the same attribute in different edit controls
located on different tab pages. In the latter case, the WIZML in the TAGLAYOUT section determines which of those controls is used to write or rewrite the tag.
The first entry mentioned in an ATTRIB tag in the ATTRIBUTES section determines which control will
have focus when the Tag Editor dialog displays. See Special Considerations below for more information.
Preventing attributes from being picked up by TAGDATAUnknownAttributes
If attributes should be written only under the control of logic in the TAGLAYOUT section, they should not be picked up by the TAGDATAUnknownAttributes special variable when editing an existing tag. Listing such attributes in the ATTRIB section will prevent this. In this case, the NAME attribute of the ATTRIB tag corresponds to the attribute that is possibly present, the CONTROL attribute is a dummy name, that is, it does not correspond to any control in the EDITORLAYOUT section).
An example of this technique can be found in the Editorlayout, Container and Control Tag Editors, where LFWIDTH and LFHEIGHT are generated only (and only on request).
Tag Inspector reads the attributes listed in the ATTRIB tags and displays them in the controls of the property sheet. The TYPE attribute of the ATTRIB tag determines the type of control used for user entry; the default is TYPE="Text". This implies that Tag Editors written for HomeSite 3.01 or ColdFusion Studio 3.11 can be used with the versions 4 of these programs. Tag Inspector will show all of the attributes listed in this section but will default to text entry boxes for each of them.
If the ATTRIB tag has an attribute of TYPE="Enumerated" it becomes a container and needs an end tag. It should contain one or more ATTRIBOPTION tags. The VALUES of these ATTRIBOPTION tags determine the list of possible values presented in a dropdown combobox for the tag attribute in the property sheet.
As attributes listed in ATTRIB tags are arranged under a (collapsible) Attributes heading in in Tag Inspector, so any events defined in EVENT tags are listed under an "Events" heading.
In version 4 and above, Tag Insight is no longer controlled by a separate file. For every tag, the list of possible attributes presented is determined by the list of ATTRIB tags in the ATTRIBUTES section.
If the ATTRIB tag has an attribute of TYPE="Enumerated" the VALUE attributes of the contained ATTRIBOPTION tags determine the list of possible values presented in the next window that appears after this attribute has been entered from the first window in Tag Insight. In a Tag Tip the possible values will be listed separated by a vertical bar. (See ATTRIB for more details.)
<ATTRIBUTES> </ATTRIBUTES> |
---|
(No attributes) |
The special variable $$TagBody is used when a control needs to be populated by the body of a tag. It is active only if the BODYEDITING flag is specified in the TAG tag. (See also the documentation about the BODYEDITING flag in the TAG tag.) An example of such a Tag Editor is the editor for the HTML tag TEXTAREA. The body of the TEXTAREA tag in the example below is filled into the txtContent control using the following ATTRIB tag.
<ATTRIB NAME="$$TagBody" CONTROL="txtContent"/>
These special variable names are intended for use in combination with an ActiveX control. While $$TagBody contains only the body of a container tag (and only if the BODYEDITING flag is specified in the TAG tag), $$TagString is populated with the complete contents of a start tag or an empty tag while $$WholeTagString will contain the whole tag, including start tag, body and end tag. An ActiveX (or other) control can be passed the entire tag for custom processing and specialized Tag Editor behavior.
The order in which the ATTRIB tags are listed in the section is not important and it can be different from the order in which the controls occur in the EDITORLAYOUT section, but the control that corresponds to the first ATTRIB listed receives focus when the Tag Editor displays.
While it is possible to use ATTRIB tags to read current attribute values and display them in a Label Control, and it is quite possible to have such a label occur as the first control in a Tag Editor, make sure this label control is not the first one listed in the ATTRIBUTES section: the result would be that no input control gets focus when the editor window is displayed. List the first user input control first and list the label control after it. More tips about focus can be found at the HomeSite Help Web site: VTML Tips and Techniques: Attributes.
Although the first attribute in the list of ATTRIB tags determines which control gets focus when the Tag Editor window is displayed, the order in which ATTRIB tags appear does not determine tabbing order in the editor. That is determined by the order in which the controls appear in the EDITORLAYOUT section.
The Flag attribute is a special type in markup languages because it indicates whether a property exists or not. An example is the COMPACT attribute in lists (UL, OL). Such attributes correspond to a checkbox which has a state of ON (checked) or OFF (clear).
Such controls can also take the form of NAME=Yes|No or NAME=1|0 but there are only two states possible, and this always corresponds to a checkbox in a user interface.
Notice that a checkbox is the only type of control that can receive such boolean information; if you try to use a different control (like a dropdown list) to receive a flag in a visual Tag Editor, you will find it is unable to display the current state.
Attributes defined with TYPE="Flag" are displayed in Tag Inspector as a CheckBox.
Note: Tag Inspector cannot always detect and change attributes that have a value of "Yes" or "No"
but are defined as TYPE="Flag" in the ATTRIB tag.
Flags in VTML are documented in a separate file.
All other attributes take the form NAME="value". When "value" should be selected from a limited set of possibilities, a dropdown list or radio group is usually the best corresponding control. Note that a radio group forces a choice while a drop down list box with an empty choice or one that is editable gives the user the choice whether or not to specify the attribute. Do not use a radio group for more than six or seven choices. If the list is just a suggestion and other values are possible, then a dropdown combo box, such as a dropdown control with the EDITABLE flag set, is the best solution.
Some attributes, especially in VTML, take only "Yes" or "No" values but cannot be considered a Flag when their default value is "Yes". In the definition for a Tag Editor, this can be handled with a Checkbox CONTROL which has has the flag CHECKED defined. For Tag Inspector, such an attribute can be defined with an ATTRIB tag with TYPE="Enumerated" with two ATTRIBOPTION tags for "Yes" and "No" respectively.
Tag Inspector will not show an attribute with the name $$TagBody.
Tag Insight will not show an attribute with the name $$TagBody.
The Tag Tips function is also clever enough not to show an attribute with the name $$TagBody.
Tag | Description |
---|---|
ATTRIB | Shows a (possible) attribute in a Tag Editor, Tag Inspector, Tag Insight and a Tag Tip. In a Tag Editor and Tag Inspector it also controls databinding between the value of an attribute in the tag being edited and the control used to display or edit this attribute. |
ATTRIBOPTION![]() |
Shows a possible attribute value in Tag Inspector, Tag Insight and Tag Tips. |
EVENT![]() |
This tag has a function only for Tag Inspector: a Tag Editor and Tag Insight can do nothing with it. Events defined by this tag are listed as a separate category; when editing the event, you can choose between a JavaScript or VBScript event handler. After that, a name can be entered for the function that is going to be the event handler for the event, and (if necessary) a SCRIPT tag is created in the HEAD section of the document with an empty function stub for the named event handler. |