Menu commands

Menu commands make menus more flexible and dynamic. As with regular commands, menu commands can perform almost any kind of edit to the current document, other open documents, or any HTML document on a local drive. The Menu Commands API expands the regular Commands API to accomplish several tasks that are related to displaying and calling the command from the menu system.

Menu commands are HTML files that are referenced in the file attribute of a menuitem tag in the menus.xml file. The BODY section of a Menu Commands file can contain an HTML form that accepts options for the command (for example, how a table should be sorted and by which column). The HEAD section of a Menu Commands file contains JavaScript functions that process form input from the BODY section and control the edits to the user's document.

Menu commands are stored in the Configuration/Menus folder inside the Dreamweaver application folder.

The following table lists the files you use to create a Menu command.

Path	File	Description
Configuration/Menus/	menus.xml	Contains a structured list of menu bars, menus, menu commands, separators, shortcut lists, and keyboard shortcuts. Modify this file to add new menus and menu commands.
Configuration/Menus/	commandname.htm	Contains the functions required by the menu command.

NOTE

If you add custom menu commands to Dreamweaver, add them at the top level of the Menus folder or create a subfolder. The Macromedia folder MM is reserved for the menu commands that come with Dreamweaver.

Modifying the Commands menu

You can add certain kinds of commands to the Commands menu, and change their names, without editing the menus.xml file. For more information about menus.xml, see "Changing menus and menu commands" on page 191.

NOTE

The term "command" has two meanings in Dreamweaver. Strictly speaking, a command is a particular kind of extension. In some contexts, however, "command" is used interchangeably with "menu item" to mean any item that appears in a Dreamweaver menu, no matter what it does or how it's implemented.

To create new commands that are automatically placed in the Commands menu, use the History panel. Alternatively, you can use the Extension Manager to install new extensions, including commands. For more information, see Dreamweaver Help.

To reorder the items in the Commands menu, or to move items between menus, you must edit the menus.xml file.

To rename a command you've created:

1.	Select Commands > Edit Command List. A dialog box appears, listing all the commands whose names you can change. (Commands that are in the default Commands menu don't appear on this list and can't be edited using this approach.)
2.	Select a command to rename.
3.	Enter a new name for it.
4.	Click Close.

The command is renamed in the Commands menu.

To delete a command you've created:

1.	Select Commands > Edit Command List. A dialog box appears, listing all the commands you can delete. (Commands that are in the default Commands menu don't appear on this list and can't be deleted using this approach.)
2.	Select a command to delete.
3.	Click Delete, and then confirm that you want to delete the command. The command is deleted. The file that contains the code for the command is also deleted; deleting a command does not simply remove the menu command from the menu. Be certain that you really want to delete the command before you use this approach. If you want to remove it from the Commands menu without deleting the file, you can find the file in Configuration/Commands and move it to another folder.
4.	Click Close.

How menu commands work

When the user clicks a menu with a menu item that contains a menu command, the following events occur:

1.	If any menuitem tag in the menu contains the dynamic attribute, Dreamweaver calls the geTDynamicContent() function in the associated Menu Commands file to populate the menu.
2.	Dreamweaver calls the canAcceptCommand() function in each Menu Commands file that is referenced in the menu to check whether the command is appropriate for the selection. If the canAcceptCommand() function returns a false value, the menu item is dimmed. If the canAcceptCommand() function returns a TRue value or is not defined, Dreamweaver calls the isCommandChecked() function to determine whether to display a check mark next to the menu item. If the isCommandChecked() function is not defined, no check mark appears.
3.	Dreamweaver calls the setMenuText() function to determine the text that should appear in the menu. If the setMenuText() function is not defined, Dreamweaver uses the text that is specified in the menuitem tag.
4.	The user selects an item from the menu.
5.	Dreamweaver calls the receiveArguments() function, if defined, in the selected Menu Commands file to let the command process any arguments that pass from the menu item. NOTE If it is a dynamic menu item, the ID of the menu item passes as the only argument.
6.	Dreamweaver calls the commandButtons() function, if defined, to determine which buttons appear on the right side of the Options dialog box and what code should execute when the user clicks the buttons.
7.	Dreamweaver scans the Menu Commands file for a FORM tag. If a form exists, Dreamweaver calls the windowDimensions() function to determine the size of the Options dialog box that contains the BODY elements of the file. If the windowDimensions() function is not defined, Dreamweaver automatically sizes the dialog box.
8.	If the Menu Commands file's BODY tag contains an onLoad handler, Dreamweaver executes the associated code (whether or not a dialog box appears). If no dialog box appears, the remaining steps do not occur.
9.	The user selects options in the dialog box. Dreamweaver executes event handlers that are associated with the fields as the user encounters them.
10.	The user clicks one of the buttons that are defined by the commandButtons() function.
11.	Dreamweaver executes the code that is associated with the clicked button.
12.	The dialog box remains visible until one of the scripts in the Menu Commands file calls the window.close() function.