19.1 Customizing Menus

Dreamweaver menus are defined in an XML-like syntax and stored in the Dreamweaver4/Configuration/Menus/menus.xml file. To customize the menus, exit Dreamweaver and modify the menus.xml file in a text editor, such as WordPad (Windows) or BBEdit (Macintosh).

Do not edit the menus.xml file in an XML-savvy editor, as it is not a true XML file. It contains ampersands ( & ) that generate errors when the XML is parsed. Also, don't edit menus.xml in Dreamweaver. Don't change the existing id attributes within the file. If you make a mistake, restore menus.xml from the backup copy, menus.bak , provided by Macromedia in the same folder.

The menus.xml file defines menu bars, menus, and menu items. Example 19-1 shows an excerpt of the code that defines Dreamweaver's Edit menu.

Example 19-1. An excerpt of the Edit menu definition

 <menu name="_Edit" id="DWMenu_MainSite_Edit">   <menuitem name="Cu_t"     key="Cmd+X"  enabled="dw.canClipCut(  )"             command="dw.clipCut(  )"   id="DWMenu_MainSite_Edit_Cut" />   <menuitem name="_Copy"    key="Cmd+C"  enabled="dw.canClipCopy(  )"             command="dw.clipCopy(  )"  id="DWMenu_MainSite_Edit_Copy" />   <menuitem name="_Paste"  key="Cmd+V"  enabled="dw.canClipPaste(  )"             command="dw.clipPaste(  )" id="DWMenu_MainSite_Edit_Paste" />   <separator />   <menuitem name="Select _All" key="Cmd+A"             enabled="site.getCurrentSite(  ) != ''"             command="site.selectAll(  )"             id="DWMenu_MainSite_Edit_SelectAll" /> </menu>

Although you can edit the menus.xml file directly, the Commands menu can be modified indirectly as described in Section 7.3.2 of Chapter 7.

Let's see how to modify Dreamweaver's menus via the menus.xml file directly. After saving your changes to the menus.xml file, restart Dreamweaver to access your new menu commands.

19.1.1 Modifying Menus and Menu Items

As you can see from Example 19-1, the menus.xml file's tags are very similar to HTML tags. Note, for example, that <menu> and </menu> tags appear in pairs and <menuitem> tags are self-contained. You can move and add menus and menu items using these XML-like tags. See the section "About menus.xml tag syntax" under Help Extending Dreamweaver for more information about the format and contents of this file.

19.1.1.1 Moving menus and menu items

To change the order of menus, select an entire menu object from its opening <menu> tag to its closing </menu> tag and all <menuitem> tags in between. Then use your text editor's cut and paste options to reorder menus as desired.

To move a menu item within a menu or to move a menu item to a new menu, select and cut the entire <menuitem> element, and then paste it into its new location.

19.1.1.2 Adding a menu item

To add a menu item to a menu, add a <menuitem> tag, which has the following attributes:

name (required)

Specifies the name of the menu as it should appear in the menu. An underscore in the name indicates that the following letter can be used to access the menu item with the Alt key under Windows (the underscore is ignored on the Macintosh). For example, if the menu item name is C_ut and the menu name is _Edit , the item can be accessed using Alt+E, U under Windows in addition to any shortcut defined by the key attribute.

id (required)

The required menu item id must identify each menu item uniquely. If you add a menu item, ensure that its id doesn't match the id of existing menu items. Do not change the id s of built-in menu items, as doing so would make those items inaccessible to other areas of the program.

key

Specifies the keyboard shortcut for this menu item, including any combination of the following modifiers and special keys. (It is usually easier to modify keyboard commands using Edit Keyboard Shortcuts.) Use a plus (+) sign to separate modifier keys. For example, Cmd+Opt+A indicates that the menu item's command should be executed when the user presses Ctrl+Alt+A (Windows) or Cmd+Opt+A (Macintosh). Dreamweaver automatically accommodates the differences between modifier keys on the two platforms:

Cmd: Indicates the Control key (Windows) or Command key (Macintosh)
Alt or Opt: Indicates the Alt key (Windows) or Option key (Macintosh)
Shift: Indicates the Shift key on both platforms
Ctrl: Specifies the Control key or Ctrl key on both platforms
Special keys: F1 through F12, PgDn, PgUp, Home, End, Ins, Del, Tab, Esc, BkSp, and Space

enabled

Specifies a JavaScript function that returns true if the menu item should be active. As seen in Example 19-1, the dw.canClipCut( ) function determines whether the Edit Cut menu item should be active. Presumably, this function checks whether something is selected in the Document window. If not, there is nothing to cut, and the menu choice is inactivated.

checked

Specifies a JavaScript function that returns true if the menu item should have a checkmark appearing next to it, as seen in the View Visual Aids submenu.

dynamic

Indicates a menu item that is configured dynamically by an HTML file. If you include the dynamic attribute, you must also supply a file attribute.

command

Specifies a JavaScript command that is executed when a user selects this menu item. A menu item must include either a file or command attribute.

file

Specifies an HTML file that controls the function of the menu item. For example, selecting Insert Table opens the document Dreamweaver4/Configuration/Commands/FormatTable.htm . That document may display a dialog box asking for additional input and run an appropriate JavaScript function. The file attribute overrides the command , enabled , and checked attributes. A menu item must include either a file or command attribute.

arguments

Provides a comma-separated list of arguments passed to the file specified by the file attribute. Enclose string arguments within single quotes (') inside the double quotes used to delimit the attribute's value, such as arguments="'right', false" (see Example 19-2).

domrequired

Indicates whether the Design view and Code view should be synchronized before executing the code associated with this menu item. If the value is false , the changes made to the document do not require synchronization before execution.

app

Specifies whether to show this menu item in dreamweaver (Dreamweaver) or ultradev (UltraDev) only. If this attribute is omitted, the menu item is shown in both applications.

platform

Specifies whether to show this menu item on either mac (Macintosh) or win (Windows) only. If this attribute is omitted, the menu item is shown on both platforms.

19.1.1.3 Adding a separator

You can add a horizontal separator to a menu by adding a <separator /> element . Separators can appear between any two <menuitem> elements, but not between <menu> elements.

The <separator /> element has one optional attribute, app , which can be set to dreamweaver or ultradev as described previously.

19.1.2 Adding a Menu

To create a new menu or submenu, add a <menu> element to the menus.xml file. The <menu> element has the following attributes:

name (required): Specifies the name of the menu that appears in Dreamweaver's menu bar. An underscore in the name indicates that the following letter can be used to access the menu with the Alt key under Windows (the underscore is ignored on the Macintosh). For example, if the menu name is _Edit , it can be accessed using Alt+E under Windows.
id (required): The required menu id must identify each menu uniquely. If you add a menu, ensure that its id doesn't match the id of existing menus. Do not change the id s of built-in menus, as it makes those items inaccessible to other areas of the program.
app: Specifies whether to show this menu in dreamweaver (Dreamweaver) or ultradev (UltraDev) only. If this attribute is omitted, the menu is shown in both applications.
platform: Specifies whether to show this menu on either mac (Macintosh) or win (Windows) only. If this attribute is omitted, the menu is shown on both platforms.

A <menu> element can contain one or more <menuitem> tags, as well as multiple <separator/> elements, and must be terminated with a </menu> tag. To create a submenu, nest a <menu> element within another <menu> element. The outermost <menu> element must be contained within a pair of <menubar> </menubar> tags.

19.1.3 Menu Bars

The menus.xml file defines a number of menu bars for Dreamweaver using the <menubar> tag. Many menu bars are used for contextual pop-up menus, although menus.xml also defines the main menu bar for the Macintosh and the Document window and Site window menu bars under Windows. The <menubar> attributes are explained here for developers writing third-party extensions (see Chapter 22) that define their own menu bars.

name (required): The menus.xml file defines menu bars named "Main Window" and "Site Window," but menu bars are identified by id , not name . The menu bar name is required but can be set to "" (blank), such as for contextual menus.
id (required): The required menu bar id must identify each menu bar uniquely. Do not change the id s of built-in menu bars, as it prevents them from being displayed in the program.
app: Specifies whether to show this menu bar in dreamweaver (Dreamweaver) or ultradev (UltraDev) only. If this attribute is omitted, the menu bar is shown in both applications.
platform: Specifies whether to show this menu bar on either mac (Macintosh) or win (Windows) only. For example, the Site window menu bar is defined for Windows only, as explained in Chapter 6. If this attribute is omitted, the menu item is shown on both platforms.

A <menubar> element must contain one or more <menu> tags and be terminated with a </menubar> tag. All <menu> elements must be contained within <menubar> elements.