A simple menu command example

This simple menu command example shows how Undo and Redo menu commands might work. The Undo menu command reverses the effect of a user's editing operation, and the Redo item reverses an Undo operation and restores the effect of the user's last editing operation.

You can implement this example by performing the following steps:

• Creating the menu commands
  
  
• Writing the JavaScript code
  
  
• Placing the command file in the Menu folder
  
  

Creating the menu commands

Add the following HTML menu tags to the end of the menus.xml file to create a menu called MyMenu that contains the Undo and Redo menu items.

 <menu name="MyMenu" > <menuitem name="MyUndo" key="Cmd+Z" file="Menus/MyMenu.htm"   arguments="'undo'"  /> <menuitem name="MyRedo" key="Cmd+Y" file="Menus/MyMenu.htm"   arguments="'redo'"  /> </menu> 

The key attribute defines keyboard shortcut keys that the user can type to invoke the menu item. The file attribute specifies the name of the command file that Dreamweaver executes when Dreamweaver invokes the menu item. The value of the arguments attribute defines the arguments that Dreamweaver will pass when it calls the receiveArguments() function.

The following figure shows these menu items:

Writing the JavaScript code

When the user selects either Undo or Redo on the MyMenu menu, Dreamweaver calls the MyMenu.htm command file, which is specified by the file attribute of the menuitem tag. Create the MyMenu.htm command file in the Dreamweaver Configuration/Menus folder and add the three menu command API functions, canAcceptCommand(), receiveArguments(), and setMenuText(), to implement the logic associated with the Undo and Redo menu items. The following sections describe these functions.

canAcceptCommand()

Dreamweaver calls the canAcceptCommand() function for each menu item in the MyMenu menu to determine whether it should be enabled or disabled. In the MyMenu.htm file, the canAcceptCommand() function checks the value of arguments[0] to determine whether Dreamweaver is processing a Redo menu item or an Undo menu item. If the argument is "undo", the canAcceptCommand() function calls the enabler function dw.canUndo() and returns the returned value, which is either true or false. Likewise, if the argument is "redo", the canAcceptCommand() function calls the enabler function dw.canRedo() and returns its value to Dreamweaver. If the canAcceptCommand() function returns the value false, Dreamweaver dims the menu item for which it called the function. The following example shows the code for the canAcceptCommand() function:

 function canAcceptCommand() {   var selarray;   if (arguments.length != 1) return false;   var bResult = false;   var whatToDo = arguments[0];   if (whatToDo == "undo")   {     bResult = dw.canUndo();   }   else if (whatToDo == "redo")   {     bResult = dw.canRedo();   }   return bResult; } 

receiveArguments()

Dreamweaver calls the receiveArguments() function to process any arguments that you defined for the menuitem tag. For the Undo and Redo menu items, the receiveArguments() function calls either the dw.undo() function or the dw.redo() function, depending on whether the value of the argument, arguments[0], is "undo" or "redo". The dw.undo() function undoes the previous step that the user performed in the document window, dialog box, or panel that has focus. The dw.redo() function redoes the last operation that was undone.

The receiveArguments() function looks like the following example code:

 function receiveArguments() {   if (arguments.length != 1) return;   var whatToDo = arguments[0];   if (whatToDo == "undo")   {     dw.undo();   }   else if (whatToDo == "redo")   {     dw.redo();   } } 

In this command, the receiveArguments() function processes the arguments and executes the command. More complex menu commands might call different functions to execute the command. For example, the following code checks whether the first argument is "foo"; if it is, it calls the doOperationX() function and passes it the second argument. If the first argument is "bar", it calls the doOperationY() function and passes it the second argument. The doOperationX() or doOperationY() function is responsible for executing the command.

 function receiveArguments(){   if (arguments.length != 2) return;   var whatToDo = arguments[0];   if (whatToDo == "foo"){     doOperationX(arguments[1]);   }else if (whatToDo == "bar"){     doOperationX(arguments[1]);   } } 

setMenuText()

Dreamweaver calls the setMenuText() function to determine what text appears for the menu item. If you do not define the setMenuText() function, Dreamweaver uses the text that you specified in the name attribute of the menuitem tag.

The setMenuText() function checks the value of the argument that Dreamweaver passes, arguments[0]. If the value of the argument is "undo", Dreamweaver calls the dw.getUndoText() function; if it is "redo", Dreamweaver calls dw.getRedoText(). The dw.getUndoText() function returns text that specifies the operation that Dreamweaver will undo. For example, if the user executes multiple Redo operations, dw.getUndoText() could return the menu text "Undo Edit Source." Likewise, the dw.getRedoText() function returns text that specifies the operation that Dreamweaver will redo. If the user executes multiple Undo operations, the dw.RedoText() function could return the menu text "Redo Edit Source."

The setMenuText() function looks like the following example code:

 function setMenuText() {   if (arguments.length != 1) return "";   var whatToDo = arguments[0];   if (whatToDo == "undo")     return dw.getUndoText();   else if (whatToDo == "redo")     return dw.getRedoText();   else return ""; } 

Placing the command file in the Menu folder

To implement the menu Undo and Redo menu items, you must save the MyMenu.htm command file in the Dreamweaver Configuration/Menus folder or a subfolder that you create. The location of the file must agree with the location that you specified in the menuitem tag. To make it accessible to Dreamweaver, either restart Dreamweaver or reload extensions. For information on how to reload extensions, see "Reloading extensions" on page 104.

To run the menu commands, select the menu item when it is enabled. Dreamweaver will invoke the functions in the command file, as described in "How menu commands work" on page 196.