| A toolbar is simply a list of radio buttons, check buttons, edit boxes, and other toolbar items, optionally divided by separator tags. Each toolbar item can be a reference to an item using the itemref tag, a separator using the separator tag, or a complete toolbar item definition, for a checkbox or an edit box, for example, as described in "Toolbar item tags" on page 226. Each toolbar definition file starts with the following declarations: <?xml version="1.0" encoding="optional_encoding"?> <!DOCTYPE toolbarset SYSTEM "-//Macromedia//DWExtension toolbar 5.0">
If the encoding is omitted, Dreamweaver uses the default encoding of the operating system. After the declarations, the file consists of a single toolbarset tag, which contains any number of the following tags: toolbar, itemref, separator, include, and itemtype tags, where itemtype is a button, checkbutton, radiobutton, menubutton, dropdown, combobox, editcontrol, or colorpicker. The following example, which is an abbreviated excerpt from the toolbars.xml file, illustrates the hierarchy of tags in the toolbar file. The example substitutes ellipses (. . .) for the toolbar item attributes that are described in the following sections. <?xml version="1.0"?> <!DOCTYPE toolbarset SYSTEM "-//Macromedia//DWExtension toolbar 5.0"> <toolbarset> <!-- main toolbar --> <toolbar label="Document"> <radiobutton . . ./> <radiobutton . . ./> <radiobutton . . ./> <separator/> <checkbutton . . ./> <checkbutton . . ./> <separator/> <editcontrol . . ./> <menubutton . . ./> <menubutton . . ./> <separator/> <button . . ./> <button . . ./> <menubutton . . ./> <menubutton . . ./> </toolbar> </toolbarset>
The following section describes each of the toolbar tags. <toolbar> Description Defines a toolbar. Dreamweaver displays the items and separators from left to right in the specified order, laying out the items automatically. The toolbar file does not specify control over the spacing between the items, but you can specify the widths of certain kinds of items. Attributes id, label, {container}, {initiallyVisible}, {initialPosition}, {relativeTo}
docEmphasis">unique_id" Required. An identifier string must be unique within a file and within all files that the file includes. The JavaScript API functions that manipulate a toolbar refer to it by its ID. For more information on these functions, see the Dreamweaver API Reference. If two toolbars that are included in the same file have the same ID, Dreamweaver displays an error. label="string" Required. The label attribute specifies the label, which is a character string, that Dreamweaver displays to the user. The label appears in the View >Toolbars menu and in the title bar of the toolbar when it's floating. container="mainframe" or "document" Defaults to "mainframe". Specifies where the toolbar should dock in the Dreamweaver workspace on Windows. If the container is set to "mainframe", the toolbar appears in the outer workspace frame and operates on the front document. If the container is set to "document", the toolbar appears in each document window. On the Macintosh, all toolbars appear in each document window. initiallyVisible="true" or "false". This tag specifies whether the toolbar should be visible the first time that Dreamweaver loads it from the Toolbars folder. After the first time, the user controls visibility. Dreamweaver saves the current state to the system registry (Windows) or the Dreamweaver Preferences file (Macintosh) when the user quits Dreamweaver. Dreamweaver restores the setting from the registry or the Preferences file when it restarts. You can manipulate toolbar visibility using the dom.getToolbarVisibility() and dom.setToolbarVisibility() functions, as described in the Dreamweaver API Reference. If you do not set the initiallyVisible attribute, it defaults to true. initialPosition="top", "below", or "floating". Specifies where Dreamweaver initially positions the toolbar, relative to other toolbars, the first time that Dreamweaver loads it. The possible values for intialPosition are described in the following list: top This is the default position, so the toolbar appears at the top of the document window. If multiple toolbars specify top for a given window type, the toolbars appear in the order that Dreamweaver encounters them during loading, which might not be predictable, if the toolbars reside in separate files. below The toolbar appears at the beginning of the row immediately below the toolbar that the relativeTo attribute specifies. Dreamweaver reports an error if the relativeTo toolbar isn't found. If multiple toolbars specify below relative to the same toolbar, they appear in the order that Dreamweaver encounters them during loading, which might not be predictable if the toolbars reside in separate files. floating Toolbar is not initially docked to the window; it floats above the document. Dreamweaver automatically places the toolbar so it is offset from other floating toolbars. On the Macintosh, floating is treated the same as top.
As with the initiallyVisible attribute, the initialPosition attribute applies only the first time that Dreamweaver loads the toolbar. After that, the toolbar's position is saved to the registry or the Dreamweaver Preferences file. You can reset the position of the toolbar by using the dom.setToolbarPosition() function. For more information on the dom.setToolbarPosition() function, see the Dreamweaver API Reference. If you do not specify the initialPosition attribute, Dreamweaver positions the toolbar in the order that it is encountered during loading. relativeTo="toolbar_id" This attribute is required if the initialPosition attribute specifies below. Otherwise, it is ignored. Specifies the ID of the toolbar below which this toolbar should be positioned.
Contents The toolbar tag contains include, itemref, and separator tags as well as individual item definitions such as button, combobox, dropdown, and so on. For descriptions of the item definitions that you can specify, see "Toolbar item tags" on page 226. Container The toolbarset tag. Example <toolbar label="Edit">
<include/> Description Loads toolbar items from the specified file before continuing to load the current file. Toolbar items that are defined in the included file can be referenced in the current file. If a file attempts to recursively include another file, Dreamweaver displays an error message and ignores the recursive include. Any toolbar tags in the included file are skipped, although toolbar items in those toolbars are available for reference in the current file. Attributes Contents None. Container The toolbar tag or the toolbarset tag. Example <include file="mine/editbar.xml"/>
<itemtype/> Description Defines a single toolbar item. Toolbar items include buttons, radio buttons, check buttons, combo boxes, pop-up menus, and so on. For a list of the types of toolbar items that you can define, see "Toolbar item tags" on page 226. Attributes The attributes vary, depending on the item that you define. For a complete list of the attributes that you can specify for toolbar items, see "Item tag attributes" on page 232. Contents None. Container The toolbar tag or the toolbarset tag. Example <button .../>
<itemref/> Description Refers to (and includes in the current toolbar) a toolbar item that was defined either inside a previous toolbar or outside of all toolbars. Attributes id, {showIf}
docEmphasis">id_reference" Required. Must be the ID of an item that was previously defined or included in the file. Dreamweaver does not allow forward references. If a toolbar item tag references an undefined ID, Dreamweaver reports an error and ignores the reference. showIf="script" Specifies that this item appears on the toolbar only if the specified script returns a TRue value. For example, you can use showIf to show certain buttons only in a given application or only when a page is written in a server-side language such as ColdFusion, ASP, or JSP. If you do not specify showIf, the item always appears. Dreamweaver checks this property whenever the item's enabler runs; that is, according to the value of the update attribute. You should use this attribute sparingly. The showIf attribute can be used either in the item definition or in a reference to the item from a toolbar. If both the definition and the reference specify the showIf attribute, Dreamweaver shows the item only if both conditions are true. The showIf attribute is equivalent to the showIf() function in a command file.
Contents None. Container The toolbar tag or the toolbarset tag. Example <itemref >
<separator/> Description Inserts a separator at the current location in the toolbar. Attributes {showIf}
The showif attribute specifies that the separator should appear only on the toolbar if the given script returns true. For example, you can use the showIf attribute to show the separator only in a given application or only when the page has a certain document type. If the showIf attribute is unspecified, the separator always appears.
Contents None. Container The toolbar tag. Example <separator/>
|
