Commands and Menus

Commands and Menus

The API for commands allows you a great deal of control over how commands work in the menus. Although all commands appear in the Commands menu by default with names determined by their filenames, you can override these defaults and place the commands wherever in the menu system you like. Using the receiveArguments() function, you can also make a given command document behave differently by passing it various parameters. The following sections describe how all this works.

Working with menus.xml

The functionality of Dreamweaver menus is determined by another file in the Configuration folder, menus.xml. This file determines what menus appear, what items each menu contains, and what will happen when a user chooses any of these items. This includes menus in the main application menu bar and, for Dreamweaver/Windows, those in the Site window menu bar. It also includes all contextual menus (those that appear when a user right-clicks/Ctrl-clicks) and all panel options menus (those that appear when a user clicks on the popup options menu icon in the upper-right corner of the panels).

menus.xml in the Menus Folder

The menus.xml file is located in the Configuration/Menus folder, along with various other menu- related files (see Figure 5.20). Note that menus.xml is a user-customizable file, which means that if your OS supports multiuser configurations, the copy of it stored in the Dreamweaver main Configuration folder may not be the active copy. Instead, you may find another copy of menus.xml in your user-specific Configuration folder. This is the active copy of the file that you should use in your development work.

Figure 5.20. The Configuration/Menus folder, showing menus.xml.

note

Windows users, look for your menus.xml in c:\Documents and Settings\username\Application Data\ Macromedia\Dreamweaver MX\Configuration\Menus\. Mac OS X users, look in /Users/username/ Library/Application Support/Macromedia/Dreamweaver MX/Configuration/Menus/. (Substitute your user name for username.) For more on extending Dreamweaver in a multiuser environment, see the section on "User-Specific Configuration Files" in Chapter 1.

Another item of interest in the Menus folder is the Custom Sets folder. This folder stores the custom shortcut key definitions that appear when a user accesses the Dreamweaver Edit > Edit Shortcut Keys command. (Again, if you're working in a multiuser environment, the active copy of the Custom Sets folder is stored in your user-specific Configuration folder.)

The Structure of menus.xml

Before opening the menus file, quit Dreamweaver. It's not good to open the menus file while the application is still running because, unlike most other extension files, the menus file needs to be continually accessed.

note

menus.xml is a long, possibly confusing file with long lines of markup code. Turn off softwrapping in your text editor to get a better sense of how the file structure works.

After you quit Dreamweaver, go to your text editor and open menus.xml. Snoop around in there until you get a handle on what's stored in there.

As an XML file, menus.xml is built from a series of custom tags that describe menus and menu items. In fact, the entries in this file create the menus and menu items in Dreamweaver, and assign each entry its functionality. Figure 5.21 shows a diagram of the main elements of the file; Table 5.3 shows a list of attributes used in the <menuitem/> tag.

Figure 5.21. Diagram of entries in menus.xml.

Table 5.3. Elements of <menuitem> entries in menus.xml

Parameter Name	Accepted Values	Examples	Description
name	String containing a name.	name="Edit _Query"	This is the name that appears in the menu. Underscores create Windows-OS shortcuts (those activated by typing the Windows key on a PC keyboard).
dynamic name	String containing a placeholder or default entry for a name to be dynamically determined at runtime.	dynamic name=" xxx " dynamic name= "No Browsers Selected"	This parameter can be used with menu commands instead of the name parameter. (One or the other must be present, but not both.)
key (optional)	Reference to a key and modifiers, formatted as a string. Modifiers are "Cmd" (refers to Cmd/Mac and Ctrl/PC), " Shift ", and " Option "; and are separated by " + ".	key="Cmd+Shift+Q"	This parameter creates the shortcut key that appears in the menu. Shortcuts specified here are overridden by the shortcut files found in Configuration/ Menus/Custom Sets, and specified under the Dreamweaver Edit: Edit Shortcuts interface.
enabled (optional)	String containing a conditional statement that must resolve to true .	enabled="dw. getDocumentDOM ().getSelectedNode(). nodeType=='3' "	This parameter is generally used when the code to be executed is specified in the command parameter. When code is specified in the file parameter, the file can contain the canAcceptCommand() parameter instead.
command	String containing one or more of JavaScript statements to be executed when the menu item is chosen .	command="dw. getDocumentDOM(). insertHTML ('Hello world') "	The menu entry gets its functionality from either the code in this parameter or the code in a file called by the file parameter. One of these two, but not both, is required.
file	String containing a link to a file containing JavaScript code to be executed when the menu item is chosen.	file="Commands/ "Query.html"	Any link specified here must be root-relative to the Configuration folder. Files used can be stored in the Commands folder, the Menus folder, or elsewhere.
platform (optional)	String containing "Mac" or "Win" .	platform="Win"	This parameter indicates that a menu item should appear only on one platform or another. (For instance, only the Mac platform has the "Edit with BBEdit" menu item.) If the parameter is not present, the item appears in all platforms.
app (optional)	String containing "dreamweaver" or "ultradev" .	app="ultradev"	This parameter indicates that a menu item should appear only in a particular application: Dreamweaver or UltraDev. If the parameter is not present, the item appears in both programs.
domRequired (optional)	String containing "true" or "false" , representing whether the command requires a valid DOM.	domRequired="true"	If a valid DOM is required, the command can be executed only if the Design and Code views have been synchronized. This parameter is most important when the menu's executable code is specified in the command parameter. When the file parameter is used to link to code, the file contains the isDomRequired() function instead.
arguments (optional)	String containing any parameters to be passed to the executable code.	arguments="value1, value2, value3"	Arguments are passed to executable code in a file using the receiveArguments() function in the file. Arguments are passed as an array called arguments .
checked	String containing a conditional statement.	"dw.getDocumentDOM() .getTextAlignment() == 'center' "	Checkmarks are generally used as toggles, determined by some condition in the user's document (whether a particular floating panel is showing, for instance). If the statement resolves to true , the menu item shows with a checkmark next to it.
id	String containing a unique, one-word identifier code.	id="MyStuff_ QueryCommand"	The ID must be present, and must be unique. Macromedia recommends affixing your company name to the beginning of the ID to avoid possible conflicts with other developers' IDs. All Macromedia IDs start with "MM_" .

note

XML is a more rigidly structured language than HTML. Its syntax must be followed carefully , and it is case-sensitive.

Customizing the Menus

You can extensively customize the menus in Dreamweaver, without any scripting, by tinkering with the menus.xml file.

• Rearrange menu items. To make a menu item appear in a different position in a menu or in a different menu altogether, find the line of code that creates that item in the menus file, and cut and paste it into its new location.

• Add items to contextual menus. All Dreamweaver contextual menus are also controlled by this file. To put a menu item into a contextual menu, find the line of code that creates it, and paste a copy into the appropriate contextual menu.

• Add separator lines. Separators are the horizontal dividing lines that break menus up into logical groupings for easier reading. To add a separator, just add this line of code between two menu items:

   <separator/> 

  Note that, in keeping with XML syntax requirements, tags like this that don't occur in pairs must include a forward slash before the closing tag.

• Add shortcut keys. Although it is possible to add shortcuts by altering the code in the menus file, it's much simpler to use the Dreamweaver Edit > Edit Shortcuts command (not available prior to Dreamweaver 4).

Controlling a Command's Appearance in the Menus

Although newly added commands appear by default at the bottom of the Commands menu, you can override those defaults by tweaking the menus file and the command file. This is a two-step process:

1. Remove the command from the Commands menu.

   To do this, put the following code in the very first line of the command document:

    <! MENU-LOCATION=NONE > 

   This comment must be the first line in the document, above the <html> tag. If you have separated your command document into separate HTML and JS files, the preceding statement must appear in the HTML file, not the JS file.

2. Add the command to the desired menu.

   To do this, add a properly formatted <menuitem/> entry in the menus file. For instance, to add the Automatic Alt Text command to the top of the Modify menu, the following entry should be added to menus.xml immediately following the entry creating the Modify menu and immediately preceding the entry for the Page Properties command:

    <menuitem name="Automatic Alt Text" file="Commands/Automatic Alt Text.html"  id="MyStuff_AltText"/> 

   After you've done this, the command file's filename no longer determines the menu item entry, and the command file's location (in the Commands folder) no longer determines its location in the menu system.

Passing Parameters to Commands Using receiveArguments()

After a command has an entry in the menus file, you can pass parameters to the command file to govern exactly how it works. The Import Word HTML and Clean Up Word HTML commands, for instance, both use the same command file document, Clean Up Word HTML.htm, with only a difference in passed parameters to distinguish them.

This process requires two steps: adding an argument to the menus file and receiving the argument in the command file. Because these steps are a bit more complicated than those for controlling a command's appearance in the menus, each step is discussed separately in the following sections.

Menu File: Adding the Arguments Parameter

Within the menus file, you pass parameters to a command by adding an arguments property to the <menuitem/> tag (see Table 5.3 for details). In the menus.xml entries for the two Word HTML commands, for instance, the first one passes an argument, and the second one doesn't:

 <menuitem name="Import _Word HTML..."  file="Commands/Clean Up Word   HTML.htm" arguments="'import'"  id="DWMenu_File_Import_WordHTML" />  <menuitem name="Clean _Up Word HTML..."  file="Commands/Clean Up Word   HTML.htm"  id="DWMenu_Commands_CleanUpWordHTML" /> 

Command File: Using the receiveArguments() Function

Within the command file, you receive the passed arguments and process them by using the receiveArguments() function. This function is called automatically as part of the API procedure for commands (refer back to Figure 5.5). Items specified as arguments in the menus file are passed to this function as an array called arguments .

Within the receiveArguments() function, you can call on the elements in the arguments array to set global variables for the main command function to act on, or you can cause actions to happen independently of the command function. In the Clean Up Word HTML command file, for instance, the main command function cleans up Word HTML. But if arguments[0] == "import" is passed then, before the main function executes, the receiveArguments() function creates a new document and copies the contents of the specified Word file into it, as dictated by the function's code:

 var curDOM, newDOM;          // Select the word file to be imported, don't show images, supress not in root  warnings.          var HTMLfileTypes = new Array("Word HTML Files (*.htm; *.html)*.htm;*.  htmlTEXT");          var fileName = browseForFileURL("open", MSG_Word_Import, false, true,  HTMLfileTypes);  //returns a local filename          if (fileName) {              // Check for name may not exist.              curDOM = dw.getDocumentDOM(fileName);              if (curDOM) {              newDOM = dw.createDocument();                if (newDOM) {                    newDOM.documentElement.outerHTML = curDOM.documentElement.outerHTML;                }              }           }