The toolbar command API

 < Day Day Up > 

In many cases where you specify a script for an attribute, you can also implement the attribute through a JavaScript function in a command file. This action is necessary when the functions need to take arguments, as in the command handler for a text box. It is required for pop-up menus and combo boxes.

The command file API for toolbar items is an extension of the menu command file API, so you can reuse menu command files directly as toolbar command files, perhaps with some additional functions that are specific to toolbars.

canAcceptCommand()

Availability

Dreamweaver MX.

Description

Determines whether the toolbar item is enabled. The enabled state is the default condition for an item, so you should not define this function unless it returns a false value in at least one case.

Arguments

For pop-up menus, combo boxes, text boxes, and color pickers, the first argument is the current value within the control. The getdynamicContent() function can optionally attach individual IDs to items within a pop-up menu. If the selected item in the pop-up menu has an ID attached, Dreamweaver passes that ID to canAcceptCommand() instead of the value. For combo boxes, if the current contents of the text box do not match an entry in the pop-up menu, Dreamweaver passes the contents of the text box. Dreamweaver compares against the pop-up menu without case-sensitivity to determine whether the contents of the text box match an entry in the list.

If you specify the arguments attribute for this toolbar item in the toolbars.xml file, those arguments are passed next. If you did not specify the arguments attribute, Dreamweaver passes the ID of the item.

Returns

Dreamweaver expects a Boolean value; true if the item is enabled; false otherwise.

Example

 function canAcceptCommand() {   return (dw.getDocumentDOM() != null); } 

getCurrentValue()

Availability

Dreamweaver MX.

Description

Returns the current value to display in the item. Dreamweaver calls the getCurrentValue() function for pop-up menus, combo boxes, text boxes, and color pickers. For pop-up menus, the current value should be one of the items in the menu. If the value is not in the pop-up menu, Dreamweaver selects the first item. For combo boxes and text boxes, this value can be any string that the function returns. For color pickers, the value should be a valid color, but Dreamweaver does not enforce this. This function is equivalent to the value attribute.

Arguments

None.

Returns

Dreamweaver expects a string that contains the current value to display. For the color picker, the string contains the RGB form of the selected color (for example #FFFFFF for the color white).

Example

 function getCurrentValue() {   var title = "";   var dom = dw.getDocumentDOM();    if (dom)     title = dom.getTitle();   return title; } 

getDynamicContent()

Availability

Dreamweaver MX.

Description

This function is required for pop-up menus and combo boxes. As with menus, this function returns an array of strings that populate the pop-up menu. Each string can optionally end with ";id=id". If an ID is specified, Dreamweaver passes the ID to the receiveArguments() function instead of the actual string to appear in the menu.

The name geTDynamicContent() is a misnomer because this function should be used even if the list of entries in the menu is fixed. For example, the Text_Size.htm file in the Configuration/Menus/MM folder is not a dynamic menu; it is designed to be called from each one of a set of static menu items. By adding a geTDynamicContent() function that simply returns the list of possible font sizes, however, the same command file can also be used for a toolbar pop-up menu. Toolbar items ignore underscores in the strings in a returned array so you can reuse menu command files. In the menu command file, Dreamweaver ignores the geTDynamicContent() function because the menu item is not marked as dynamic.

Arguments

None.

Returns

Dreamweaver expects an array of strings with which to populate the menu.

Example

 function getDynamicContent() {   var items = new Array;   var filename = dw.getConfigurationPath() + "/Toolbars/MM/AddressList.xml";   var location = MMNotes.localURLToFilePath(filename);   if (DWfile.exists(location))   {     var addressData = DWfile.read(location);     var addressDOM = dw.getDocumentDOM(dw.getConfigurationPath() +       '/Shared/MM/Cache/empty.htm');     addressDOM.documentElement.outerHTML = addressData;     var addressNodes = addressDOM.getElementsByTagName("url");     if (addressNodes.length)     {       for (var i=0; i < addressNodes.length ; i++ )       {         items[i] = addressNodes[i].address + ";id='" +           addressNodes[i].address + "'";       }     }   }   return items; 

getMenuID()

Availability

Dreamweaver MX.

Description

Only valid for menu buttons. Dreamweaver calls the getMenuID() function to get the ID of the menu that should appear when the user clicks the button.

Arguments

None.

Returns

Dreamweaver expects a string that contains a menu ID, which is defined in the menus.xml file.

Example

 function getMenuID() {   var dom = dw.getDocumentDOM();   var menuID = '';   if (dom)   {     var view = dom.getView();     var focus = dw.getFocus();     if (view == 'design')     {       menuID = 'DWDesignOnlyOptionsPopup';     }     else if (view == 'split')     {       if (focus == 'textView')       {         menuID = 'DWSplitCodeOptionsPopup';       }       else       {         menuID = 'DWSplitDesignOptionsPopup';       }     }     else if (view == 'code')     {       menuID = 'DWCodeOnlyOptionsPopup';     }     else     {       menuID = 'DWBrowseOptionsPopup';     }   }   return menuID; } 

getUpdateFrequency()

Availability

Dreamweaver MX.

Description

Specifies how often to run the handlers for the enabled, checked, showIf, and value attributes to update the visible state of the item.

You must specify the update frequency for toolbar items because they are always visible, unlike menus. For this reason, you should always select the lowest frequency possible and make sure your enabled, checked, and value handlers are as simple as possible.

This function is equivalent to the update attribute in a toolbar item.

Arguments

None.

Returns

Dreamweaver expects a string that contains a comma-separated list of update handlers. For a complete list of the possible update handlers, see "update="update_frequency_list"" on page 236.

Example

 function getUpdateFrequency() {   return onSelChange"; } 

isCommandChecked()

Availability

Dreamweaver MX.

Description

Returns a value that specifies whether the item is selected. For a button, checked means that the button appears on or depressed. The isCommandChecked() function is equivalent to the checked attribute in a toolbar item tag.

Arguments

For pop-up menus, combo boxes, text boxes, and color pickers, the first argument is the current value within the control. The getdynamicContent() function can optionally attach individual IDs to items within a pop-up menu. If the selected item in the menu has an ID attached, Dreamweaver passes that ID to the isCommandChecked() function instead of the value. For combo boxes, if the current contents of the text box do not match an entry in the pop-up menu, Dreamweaver passes the contents of the text box. For determining whether the text box matches, Dreamweaver compares against the menu without case-sensitivity.

If you specified the arguments attribute, those arguments are passed next. If you do not specify the arguments attribute, Dreamweaver passes the ID of the item.

Returns

Dreamweaver expects a Boolean value: true if the item is checked; false otherwise.

Example

The following example determines which item, if any, should be checked in a pop-up menu of paragraph formats and CSS styles:

 function isCommandChecked() {   var bChecked = false;   var style = arguments[0];   var textFormat = dw.getDocumentDOM().getTextFormat();   if (dw.getDocumentDOM() == null)     bChecked = false;   if (style == "(None)")     bChecked = (dw.cssStylePalette.getSelectedStyle() == '' || textFormat == "" || textFormat == "P" || textFormat == "PRE");   else if (style == "Heading 1")     bChecked =  (textFormat == "h1");   else if (style == "Heading 2")     bChecked =  (textFormat == "h2");   else if (style == "Heading 3")     bChecked =  (textFormat == "h3");   else if (style == "Heading 4")     bChecked =  (textFormat == "h4");   else if (style == "Heading 5")     bChecked =  (textFormat == "h5");   else if (style == "Heading 6")     bChecked =  (textFormat == "h6");   else     bChecked = (dw.cssStylePalette.getSelectedStyle() == style);   return bChecked; } 

isDOMRequired()

Availability

Dreamweaver MX.

Description

Specifies whether the toolbar command requires a valid DOM to operate. If this function returns a TRue value or if the function is not defined, Dreamweaver assumes that the command requires a valid DOM and synchronizes the Code view and Design view for the document before executing the associated command. This function is equivalent to the domRequired attribute in a toolbar item tag.

Arguments

None.

Returns

Dreamweaver expects a Boolean value: TRue if the DOM is required; false otherwise.

Example

 function isDOMRequired() {   return false; } 

receiveArguments()

Availability

Dreamweaver MX.

Description

Processes any arguments that pass from a toolbar item. The receiveArguments() function is equivalent to the command attribute in a toolbar item tag.

Arguments

For pop-up menus, combo boxes, text boxes, and color pickers, the first argument is the current value within the control. The getdynamicContent() function can optionally attach individual IDs to items within a pop-up menu. If the selected item in the pop-up menu has an ID attached, Dreamweaver passes that ID to the receiveArguments() function instead of the value. For combo boxes, if the current contents of the text box do not match an entry in the pop-up menu, Dreamweaver passes the contents of the text box. To determine whether the text box matches, Dreamweaver compares against the pop-up menu without case-sensitivity.

If you specified the arguments attribute, those arguments are passed next. If you did not specify the arguments attribute, Dreamweaver passes the ID of the item.

Returns

Dreamweaver expects nothing.

Example

 function receiveArguments(newTitle) {   var dom = dw.getDocumentDOM();   if (dom)     dom.setTitle(newTitle); } 

showIf()

Availability

Dreamweaver MX.

Description

Specifies that an item appears on the toolbar only if the function returns a true value. For example, you can use the showIf() function to show certain buttons only when the page has a certain server model. If the showif() function is not defined, the item always appears. The showIf() function is the same as the showIf attribute in a toolbar item tag.

The showIf() function is called whenever the item's enabler runs; that is, according to the value that the getUpdateFrequency() function returns.

Arguments

None.

Returns

Dreamweaver expects a Boolean value: true if the item appears; false otherwise.

Example

 function showif() {     var retval = false;     var dom = dw.getDocumentDOM();     if(dom)     {       var view = dom.getView();       if(view == 'design')       {         retval = true;       }     }     return retval; } 

     < Day Day Up > 


    Developing Extensions for Macromedia Dreamweaver 8
    Developing Extensions for Macromedia Dreamweaver 8
    ISBN: 0321395409
    EAN: 2147483647
    Year: 2005
    Pages: 282

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net