Menu Commands

Menu commands are commands that have enhanced control over how they will appear in the menu. In particular, menu commands can create dynamic menu entries, including custom menu item names , checkmark toggles, and complete submenus of dynamically generated options.

Menu Commands in the Configuration Folder

Menu commands are not stored in the Commands folder, but in a subfolder within the Configuration/Menus folder. All the standard Macromedia menu commands are stored in the Configuration/Menus/MM folder. Macromedia requests that developers not store their own commands there. Instead, create a custom folder with whatever name you choose, and store custom menu commands there. Because all menu commands are given their place in the menu system by using the menus.xml file, this folder name is not something the user will see. Figure 5.24 shows the Menus folder and its subfolders .

Figure 5.24. The Configuration/Menus folder, showing the MM subfolder (where the Macromedia standard menu command files are stored). Only partial contents of the MM folder are shown.

Structure of a Menu Command File

Structurally, menu command files are just like command files, but with added API functions to create their dynamic menu presence. All these extra API functions are optional, and all are called automatically.

setMenuText()

If this function is present in a command file, it determines what text will appear in the menu as this command's menu entry, overriding whatever name is specified in the <menuitem/> tag's name attribute. For instance, the command document LaunchExternalEditor.htm utilizes this function:

 var MENU_strLaunch = "_Edit with ";  function setMenuText()  {  return MENU_strLaunch + dw.getExternalTextEditor();  } 

The dw.getExternalTextEditor() method gathers the user's specified external editor ( chosen in Edit > Preferences and saved in another Dreamweaver configuration file) and concatenates it after the text string Edit with to create the menu entry, as shown in Figure 5.25.

Figure 5.25. The Edit menu, showing different dynamically generated menu text for the Launch External Editor command.

Although setMenuText() does not require any parameters, if the <menuitem/> tag in the menus file includes an arguments attribute, this function will accept them as parameters. This is useful for distinguishing between two commands that call on the same command file.

getDynamicContent (menuID)

This function retrieves content to be used in dynamically generating an indeterminate number of menu items to add to a menu. This function may not be used in conjunction with the setMenuText() functiononly one of the two functions may be used for a given command.

When a user clicks on a menu, Dreamweaver examines the menus.xml file, preparatory to displaying a menu. If any of the <menuitem/> entries for that menu contain a dynamic name attribute in place of the standard name attribute, Dreamweaver looks through that menu item's command file to see if the getDynamicContent() function is present. If that function is present, Dreamweaver calls it, passing it the <menuitem/> 's unique ID as a parameter. The function must return a null value or an array of text strings, each containing the name of a menu item and a unique ID for that menu item, separated from the name by a semicolon. If the function returns null , no change is made to the menuin other words, the menu will display with no dynamically generated items added. If the function returns an array of strings, the first part of each string in the array will become the name of an item in the menu; the second part of each string will become that item's ID, and will be passed to that item's command file as an argument.

As an example of getDynamicContent() , the Window menu's list of open windows is generated by this <menuitem/> tag:

 <menuitem dynamic name="(No Open Documents)" file="Menus/MM/Window_Titles.htm"  id="DWMenu_MainSite_Window" /> 

And this getDynamicContent() function in the Window_Titles.htm file:

 function getDynamicContent(itemID) {        var windowList = null;        var i;        windowList = new Array();        var dwWindowNames = dw.getDocumentList();        if (dwWindowNames.length > 0)        {              for (i=0; i<dwWindowNames.length; i++)              {                    windowList[i] = new String(dwWindowNames[i].getWindowTitle());                    windowList[i] += ";id='"+i+"'";                    windowList[i] = windowList[i].replace(/_/g,"%_");              }        }        return windowList;  } 

If no windows are open when the command is chosen, the windowList variable remains null . When the function returns this variable, Dreamweaver displays the Window menu with one entry named ( No Open Documents )determined by the dynamic name entry of the <menuitem/> entry. If one or more windows are open, the getDynamicContent() function uses the dw. getDocumentList() method to collect information about all open documents and uses that information to put an array of strings in windowList . When the function returns this array, the menu will display an entry for each window.

Figure 5.26 shows the dynamically generated menu entries created by this code.

Figure 5.26. The list of open windows generated by the Window_Titles.htm command document, using getDynamicContent() .

isCommandChecked()

This function determines whether the command's menu item should display with a checkmark next to it or not. It must return a Boolean ( true/false ) value. If it returns true , a checkmark appears next to the command's menu item; if it returns false , no checkmark appears. The isCommandChecked() function doesn't require any parameters, althoughas with setMenuText() if the argument's attribute is present in the <menuitem/> tag that calls this command file, Dreamweaver passes the arguments to the function as parameters.

The Text_List.htm menu command file is an example of how isCommandChecked() works with arguments passed from the menus.xml entry to determine which item in the Text > List submenu will display with a checkmark. This command file is called by the following code in menus.xml:

 <menuitem name="_None" file="Menus/MM/Text_List.htm" arguments="'None'"  id="DWContext_Table_Text_List_None" />  <menuitem name="_Unordered List" file="Menus/MM/Text_List.htm" arguments="'UL'"  id="DWContext_Table_Text_List_UL" />  <menuitem name="_Ordered List" file="Menus/MM/Text_List.htm" arguments="'OL'"  id="DWContext_Table_Text_List_OL" />  <menuitem name="_Definition List" file="Menus/MM/Text_List.htm" arguments="'DL'"  id="DWContext_Table_Text_List_DL" /> 

The relevant portion of the isCommandChecked() function looks like this:

 function isCommandChecked(){  [etc]      var textList = dw.getDocumentDOM().getListTag();      var what = arguments[0];      if (what == "None")         return (textList == "");      if (what == "UL")         return (textList == "ul");      if (what == "OL")         return (textList == "ol");      if (what == "DL")         return (textList == "dl");      else         return false;  [etc]  } 

What's happening here? Each submenu item that uses this command passes it a tag name ( UL, OL, DL ) as a parameter. The function collects that parameter as the what variable. It also tests the user's selection to determine whether a list tag is selected, collecting the name of the tag in the textList variable. It then uses a series of if statements to determine if the tags match. For the Unordered List menu entry, for instance, the parameter collected is what will be OL . The relevant if statement asks if the user's tag ( textList ) equals "ol" . If it does, the command returns true and the Unordered List menu entry will appear with a checkmark.

Figure 5.27 shows the Text > List submenu, showing that the user currently has an unordered list selected.

Figure 5.27. The Text > List submenu, which uses the isCommandChecked() function to determine which item will appear with a checkmark.

The API Procedure for Menu Commands

The Dreamweaver procedure for handling menu commands is basically the same as its procedure for handling regular commands, but with extra steps at the beginning of the process for the automatic calls to the special menu- related functions just described.

The menu commands API procedure starts when the user clicks a menu that contains a menu command. At that point, the following events occur:

1. If any <menuitem/> tag in the menu contains the dynamic name attribute, Dreamweaver looks in the associated command file for the getDynamicContent() function, and if it's present, executes it. The array of strings returned by getDynamicContent() is used to populate the menu, replacing whatever text was specified as the dynamic name attribute's value. If the getDynamicContent() function is not available, or if it returns a null value, the dynamic name is used in the menu.

2. For each menu item, Dreamweaver looks in the associated command file for the canAcceptCommand() function, and if it's present, executes it. If this function is present and returns false , the menu item is grayed out and the API process for this item stops here. If it's not present, or if it returns true , the following events occur.

3. For each menu item, Dreamweaver looks for the isCommandChecked() function, and if it's present, executes it. If this function returns true , Dreamweaver displays a checkmark next to the menu item.

4. For each menu item, Dreamweaver looks for the setMenuText() function and executes it if it's present. Whatever text string is returned by this function becomes the text of the menu item. If this function isn't present, the default text specified in the <menuitem/> name attribute is used. (Note that this command should not be present if the getDynamicContent() function is present.)

5. Dreamweaver then displays the menu and waits for the user to choose a specific item from the menu. At that point, the API procedure continues, following the same steps as the standard command API procedure.

   Figure 5.28 shows a diagram of the API procedure for menu commands. Compare it to the diagrammed procedure for standard commands, as seen in Figure 5.5.

   Figure 5.28. The API procedure for menu commands.