The ATTRIBUTES section is probably the most important section in a Tag Definition file: 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 following subjects are covered in this document:
Related information about VTML and WIZML:
|
Of all the changes introduced with VTML 2 in HomeSite and ColdFusion Studio 4.0 the ones relating to attributes are maybe the most significant ones. The ATTRIB tag has been extended, and there are two new tags.
Although the ATTRIBUTES section can have only two types of content: ATTRIB and EVENT tags, 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.
ATTRIBUTES plays a role in the following VTML-driven tools:
This tag can occur only within a TAG tag in a Tag Definition file.
When editing an existing tag, there must be a way to get the values of the attributes of the tag into the controls of the Tag Editor. The ATTRIBUTES section takes care of this, and this is in fact the function for which the ATTRIBUTES section was designed: 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's not the name of the variable for use in the TAGLAYOUT section: the variable name is the same as the name of the control: 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.
This can be used for instance 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 should take care of
deciding which of those controls is used to (re)write 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 is displayed. 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 (not corresponding 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).
Somewhat similar to a Tag Editor, 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.
Just like attributes listed in ATTRIB tags are arranged under a (collapsible) "Attributes" heading in in Tag Inspector, any events defined in EVENT tags are listed under an "Events" heading.
In HomeSite 4 and Cold Fusion Studio 4 Tag Insight is no longer controlled by a separate file. For every tag, the list of possible attributes presented is now 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.
There is another important consideration when determining how to lay out the ATTRIBUTES section: While in general it doesn't matter much in which order the ATTRIB tags occur, and the order can be quite different from the order in which the controls occur in the EDITORLAYOUT section, it is important which is the first ATTRIB: the control that corresponds to this is the one to receive focus when the Tag Editor is displayed.
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. Simply list the first user input control first, and list the label control somewhere after it. More tips about focus can be found on-line on the HomeSite Help 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.
A special type of attribute in markup tags is the "Flag" attribute which indicates a property that is either
there or not. An example is the COMPACT attribute in lists (UL, OL). Such attributes are just there or not there,
and they correspond to one type of control only: a checkbox which has a state of ON (checked) or OFF (not checked).
Sometimes they can also take the form of NAME=Yes|No or NAME=1|0 but that still means there are only two "states"
possible, and this always corresponds to a checkbox in a user interface.
Notice that a checkbox is indeed the only type of control to be able to receive such boolean information; if you try to use a different control (like a drop-down list) to receive a flag in a visual Tag Editor, you'll find it's unable to display the current state.
Attributes defined with TYPE="Flag" are displayed in Tag Inspector as a CheckBox.
Note: Currently Tag Inspector is unable to properly 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". In those cases where "value" shouold be one from a limited set of possibilities, a drop-down 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. Don't use a radio group for more than six or seven choices. If the list is just a suggestion and other values are possible, a radio group won't do and a dropdown combo box (i.e., a dropdown control with the EDITABLE flag set) is the best alternative.
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 defined with an ATTRIB tag with TYPE="Enumerated" with two ATTRIBOPTION tags for "Yes" and "No" respectively.
Tag Inspector is clever enough not to show an attribute with the name $$TagBody.
Note: Currently it is not possible to prevent all attributes or individual "dummy" attributes used for control purposes in a Tag Editor from showing up as "real" attributes in Tag Inspector. This may be fixed in a maintenance release or a future version.
Tag Insight is clever enough not to show an attribute with the name $$TagBody.
Note: Currently it is not possible to prevent all attributes or individual "dummy" attributes used for control purposes in a Tag Editor from showing up as "real" attributes in Tag Insight. This may be fixed in a maintenance release or a future version.
The Tag Tips function is also clever enough not to show an attribute with the name $$TagBody.
Note: Currently it is not possible to prevent all attributes or individual "dummy" attributes used for control purposes in a Tag Editor from showing up as "real" attributes in a Tag Tip. This may be fixed in a maintenance release or a future version.
All of the tags that can occur within the ATTRIBUTES section have their own reference page; the tag names in the summary table below link to these pages.
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. |