The Commands API

The custom functions in the Commands API are not required.

canAcceptCommand()

Description

This function determines whether the command is appropriate for the current selection.

NOTE

Do not define canAcceptCommand() unless it returns a value of false in at least one case. If the function is not defined, the command is assumed to be appropriate. Making this assumption saves time and improves performance.

Arguments

None.

Returns

Dreamweaver expects a TRue value if the command is allowed; if the value is false, Dreamweaver dims the command in the menu.

Example

The following example of the canAcceptCommand() function makes the command available only when the selection is a table:

 function canAcceptCommand(){   var retval=false;   var selObj=dw.getDocumentDOM.getSelectedNode();   return (selObj.nodeType == Node.ELEMENT_NODE && selObj.tagName=="TABLE");{     retval=true; } return retval; } 

commandButtons()

Description

This function defines the buttons that should appear on the right side of the Options dialog box and their behaviors when they are clicked. If this function is not defined, no buttons appear, and the BODY section of the Commands file expands to fill the entire dialog box.

Arguments

None.

Returns

Dreamweaver expects an array that contains an even number of elements. The first element is a string that contains the label for the topmost button. The second element is a string of JavaScript code that defines the behavior of the topmost button when it is clicked. The remaining elements define additional buttons in the same way.

Example

The following instance of commandButtons() defines three buttons: OK, Cancel, and Help:

 function commandButtons(){   return new Array("OK" , "doCommand()" , "Cancel" , "window.close()" , "Help" , "showHelp ()"); } 

isDomRequired()

Description

This function determines whether the command requires a valid DOM to operate. If this function returns a value of true or if the function is not defined, Dreamweaver assumes that the command requires a valid DOM and synchronizes the Design and Code views of the document before executing. Synchronization causes all edits in the Code view to update in the Design view.

Arguments

None.

Returns

Dreamweaver expects a true value if a command requires a valid DOM to operate; false otherwise.

receiveArguments()

Description

This function processes any arguments that pass from a menu item or from the dw.runCommand() function.

Arguments

 {arg1}, {arg2},...{argN} 

• If the arguments attribute is defined for a menuitem tag, the value of that attribute passes to the receiveArguments() function as one or more arguments. Arguments can also pass to a command by the dw.runCommand() function.

Returns

Dreamweaver expects nothing.

windowDimensions()

Description

This function sets specific dimensions for the Parameters dialog box. If this function is not defined, the window dimensions are computed automatically.

NOTE

Do not define this function unless you want an Options dialog box that is larger than 640 x 480 pixels.

Arguments

 platform 

• The value of the platform argument is either "macintosh" or "windows", depending on the user's platform.

Returns

Dreamweaver expects a string of the form "widthInPixels,heightInPixels".

The returned dimensions are smaller than the size of the entire dialog box because they do not include the area for the OK and Cancel buttons. If the returned dimensions do not accommodate all options, scroll bars appear.

Example

The following example of the windowDimensions() function sets the dimensions of the Parameters dialog box to 648 x 520 pixels:

 function windowDimensions(){   return "648,520"; }