Item tag attributes

The attributes for toolbar item tags have the following meanings:

Required. The id attribute is an identifier for the toolbar item. The id attribute must be unique within the current file and all files that are included within the current file. The itemref tag uses the item id to refer to and include an item within a toolbar.

Example

 <button  . . . > 

showIf="script"

Optional. This attribute specifies that the item appears on the toolbar only if the script returns a TRue value. For example, you can use the showIf attribute to show certain buttons only when a page is written in a certain server-side language such as ColdFusion, ASP, or JSP. If you do not specify showIf, the item always appears.

The showIf attribute is checked whenever the item's enabler runs; that is, according to the value of the update attribute. You should use the showIf attribute sparingly.

You can specify the showIf attribute in the item definition and in a reference to the item on an itemref tag. If the definition and the reference specify the showIf attribute, the item shows only if both conditions are true. The showIf attribute is the same as the showIf() function in a toolbar command file. If you specify both the showIf attribute and the showif() function, the function overrides the attribute.

Example

 showIf="dw.canLiveDebug()" 

image="image_path"

This attribute is required for buttons, check buttons, radio buttons, menu buttons, and combo buttons. The image attribute is optional for color pickers and is ignored for other item types. The image attribute specifies the path, relative to the Configuration folder, of the icon file that displays on the button. The icon can be in any format that Dreamweaver can render, but typically it is a GIF or JPEG file format.

If an icon is specified for a color picker, the icon replaces the color picker entirely. If the colorRect attribute is also set, the current color appears on top of the icon in the specified rectangle.

Example

 image="Toolbars/images/MM/codenav.gif" 

disabledImage="image_path"

Optional. Dreamweaver ignores the disabledImage attribute for items other than buttons, check buttons, radio buttons, menu buttons, color pickers, and combo buttons. This attribute specifies the path, relative to the Configuration folder, of the icon file that Dreamweaver displays if the button is disabled. If you do not specify the disabledImage attribute, Dreamweaver displays the image that is specified in the image attribute when the button is disabled.

Example

 disabledImage="Toolbars/images/MM/codenav_dis.gif" 

overImage="image_path"

Optional. Dreamweaver ignores the overImage attribute for items other than buttons, check buttons, radio buttons, menu buttons, color pickers, and combo buttons. This attribute specifies the path, relative to the Configuration folder, of the icon file that Dreamweaver displays when the user moves the mouse over the button. If you do not specify the overImage attribute, the button does not change when the user moves the mouse over it, except for a ring that Dreamweaver draws around the button.

Example

 overImage="Toolbars/images/MM/codenav_ovr.gif" 

tooltip="tooltip string"

Required. This attribute specifies the identifying text, or tooltip, that appears when the mouse pointer hovers over the toolbar item.

Example

 tooltip="Code Navigation" 

label="label string"

Optional. This attribute specifies a label that displays next to the item. Dreamweaver does not automatically add a colon to labels. Labels for nonbutton items are always positioned on the left of the item. Dreamweaver places labels for buttons, check buttons, radio buttons, menu buttons, and combo buttons inside the button and to the right of the icon.

Example

 label="Title: " 

width="number"

Optional. This attribute applies only to text box, pop-up menu, and combo box items by specifying the width of the item in pixels. If you do not specify the width attribute, Dreamweaver uses a reasonable default width.

Example

 width="150" 

menu

This attribute is required for menu buttons and combo buttons, unless you specify the getMenuID() function in an associated command file. Dreamweaver ignores the menuID attribute for other types of items. This attribute specifies the ID of the menu bar that contains the context menu to pop up when the user clicks the button, menu button, or combo button. The ID comes from the ID attribute of a menubar tag in the menus.xml file.

Example

 menu 

colorRect="left top right bottom"

This attribute is optional for color pickers that have an image attribute. The colorRect attribute is ignored for other types of items and for color pickers that do not specify an image. If you specify the colorRect attribute, Dreamweaver displays the color that is currently selected in the color picker in the rectangle, relative to the left or top of the icon. If you do not specify the colorRect attribute, Dreamweaver does not display the current color on the image.

Example

 colorRect="0 12 16 16" 

file="command_file_path"

Required for pop-up menus and combo boxes. The file attribute is optional for other types of items. The file attribute specifies the path, relative to the Configuration folder, of a command file that contains JavaScript functions to populate, update, and execute the item. The file attribute overrides the enabled, checked, value, update, domRequired, menuID, showIf, and command attributes. In general, if you specify a command file with the file attribute, Dreamweaver ignores all the equivalent attributes that are specified in the tag. For more information about command files, see "The toolbar command API" on page 238.

Example

 file="Toolbars/MM/EditTitle.htm" 

domRequired="true" or "false"

Optional. As with menus, the domRequired attribute specifies whether the Design view should be synchronized with the Code view before Dreamweaver runs the associated command. If you do not specify this attribute, it defaults to a true value. This attribute is equivalent to the isDOMRequired() function in a toolbar command file.

Example

 domRequired="false" 

enabled="script"

Optional. As with menus, the script returns a value that specifies whether the item is enabled. If you do not specify this attribute, it defaults to enabled. The enabled attribute is equivalent to the canAcceptCommand() function in a toolbar command file.

Example

 enabled="dw.getFocus() == 'textView' || dw.getFocus() == 'html'" 

checked="script"

This attribute is required for check buttons and radio buttons. Dreamweaver ignores the checked attribute for other types of items. As with menus, the script returns a value that specifies whether the item is checked or unchecked. The checked attribute is equivalent to isCommandChecked() in a toolbar command file. If you do not specify this attribute, it defaults to unchecked.

Example

 checked="dw.getDocumentDOM() != null && dw.getDocumentDOM().getView() == 'code'" 

value="script"

This attribute is required for pop-up menus, combo boxes, text boxes, and color pickers. Dreamweaver ignores the value attribute for other types of items.

To determine what value to display for pop-up menus and combo boxes, Dreamweaver first calls isCommandchecked() for each item in the menu. If the isCommandchecked() function returns a TRue value for any items, Dreamweaver displays the value for the first one. If no items return a TRue value or the isCommandChecked() function is not defined, Dreamweaver calls the getCurrentValue() function or executes the script that the value attribute specifies. If the control is a combo box, Dreamweaver displays the returned value. If the control is a pop-up menu, Dreamweaver temporarily adds the returned value to the list and displays it.

In all other cases, the script returns the current value to display. For pop-up menus or combo boxes, this value should be one of the items in the menu list. For combo boxes and text boxes, the value can be any string that the script returns. For color pickers, the value should be a valid color but Dreamweaver does not enforce this.

The value attribute is equivalent to the getCurrentValue() function in a toolbar command file.

update="update_frequency_list"

Optional. This attribute specifies how often the enabled, checked, showif, and value handlers should run to update the visible state of the item. The update attribute is equivalent to the getUpdateFrequency() function in a toolbar command file.

You must specify the update frequency for toolbar items because these items are always visible, unlike menu items. For this reason, you should always select the lowest frequency possible and make sure your handlers for the enabled, checked, and value handlers are as simple as possible.

The following list shows the possible handlers for update_frequency_list, from least to most frequent. If you do not specify the update attribute, the update frequency defaults to onEdit frequency. You can specify multiple update frequencies, separated by commas. The handlers run on any of the following specified events:

• onServerModelChange executes when the server model of the current page changes.

• onCodeViewSyncChange executes when the Code view becomes in or out of sync with the Design view.

• onViewChange executes whenever the user switches focus between Code view and Design view or when the user changes between Code view, Design view, or Split view.

• onEdit executes whenever the document is edited in Design view. Changes that you make in Code view do not trigger this event.

• onSelChange executes whenever the selection changes in Design view. Changes that you make in Code view do not trigger this event.

• onEveryIdle executes regularly when the application is idle. This can be time-consuming because the enabler/checked/showif/value handlers are running often. It should be used only for buttons that need to have their enable state changed at special times, and handlers should be quick.

NOTE

In all these cases, Dreamweaver actually executes the handlers after the specified event occurs, when the application is in a quiescent state. It is not guaranteed that your handlers run after every edit or selection change; your handlers run soon after a batch of edits or selection changes occur. The handlers are guaranteed to run when the user clicks on a toolbar item.

Example

 update="onViewChange" 

command="script"

This attribute is required for all items except menu buttons. Dreamweaver ignores the command attribute for menu buttons. Specifies the JavaScript function to execute when the user performs one of the following actions:

• Clicks a button

• Selects an item from a pop-up menu or combo box

• Tabs out of, presses Return in, or clicks away from a text box or combo box

• Selects a color from a color picker

The command attribute is equivalent to the receiveArguments() function in a toolbar command file.

Example

 command="dw.toggleLiveDebug()" 

arguments="argument_list"

Optional. This attribute specifies the comma-separated list of arguments to pass to the receiveArguments() function in a toolbar command file. If you do not specify the arguments attribute, Dreamweaver passes the ID of the toolbar item. In addition, pop-up menus, combo boxes, text boxes, and color pickers pass their current value as the first argument, before any arguments that the arguments attribute specifies, and before the item ID if no arguments are specified.

Example

On a toolbar that has Undo and Redo buttons, each button calls the menu command file, Edit_Clipboard.htm, and passes an argument that specifies the action, as shown in the following example:

 <button   image="Toolbars/images/MM/undo.gif"  disabledImage="Toolbars/images/MM/undo_dis.gif"  tooltip="Undo"  file="Menus/MM/Edit_Clipboard.htm"  arguments="'undo'"  update="onEveryIdle"/> <button   image="Toolbars/images/MM/redo.gif"  disabledImage="Toolbars/images/MM/redo_dis.gif"  tooltip="Redo"  file="Menus/MM/Edit_Clipboard.htm"  arguments="'redo'"  update="onEveryIdle"/>