The Behaviors API

Two Behaviors API functions are required (applyBehavior() and behaviorFunction()); the rest are optional.

applyBehavior()

Description

This function inserts into the user's document an event handler that calls the function that the behaviorFunction() function inserts. The applyBehavior() function can also perform other edits on the user's document, but it must not delete the object to which the behavior is being applied or the object that receives the action.

Arguments

 uniqueName 

• The argument is a unique identifier among all instances of all behaviors in the user's document. Its format is functionNameInteger, where functionName is the name of the function that behaviorFunction() inserts. This argument is useful if you insert a tag into the user's document and you want to assign a unique value to its NAME attribute.

Returns

Dreamweaver expects a string that contains the function call to be inserted in the user's document, usually after accepting parameters from the user. If the applyBehavior() function determines that the user made an invalid entry, the function can return an error string instead of the function call. If the string is empty (return "";), Dreamweaver does not report an error; if the string is not empty and not a function call, Dreamweaver displays a dialog box with the text Invalid input supplied for this behavior: [the string returned from applyBehavior()]. If the return value is null (return;), Dreamweaver indicates that an error occurred but gives no specific information.

NOTE

Quotation marks ("")within the returned string must be preceded by a backslash (\) to avoid errors that the JavaScript interpreter reports.

Example

The following example of the applyBehavior() function returns a call to the MM_openBrWindow() function and passes user-specified parameters (the height and width of the window; whether the window should have scroll bars, a toolbar, a location bar, and other features; and the URL that should open in the window):

 function applyBehavior() {   var i,theURL,theName,arrayIndex = 0;   var argArray = new Array(); //use array to produce correct     number of commas w/o spaces   var checkBoxNames = new Array("toolbar","location",    "status","menubar","scrollbars","resizable");   for (i=0; i<checkBoxNames.length; i++) {     theCheckBox = eval("document.theForm." + checkBoxNames[i]);     if (theCheckBox.checked) argArray[arrayIndex++] = (checkBoxNames[i] + "=yes");   }   if (document.theForm.width.value)     argArray[arrayIndex++] = ("width=" +       document.theForm.width.value);   if (document.theForm.height.value)     argArray[arrayIndex++] = ("height=" +       document.theForm.height.value);   theURL = escape(document.theForm.URL.value);   theName = document.theForm.winName.value;   return "MM_openBrWindow('"+theURL+"',    '"+theName+"','"+argArray.join()+"')"; } 

behaviorFunction()

Description

This function inserts one or more functions surrounded by the following tags, if they don't yet exist into the HEAD section of the user's document:

 <SCRIPT LANGUAGE="JavaScript"></SCRIPT> 

Arguments

None.

Returns

Dreamweaver expects either a string that contains the JavaScript functions or a string that contains the names of the functions to be inserted in the user's document. This value must be exactly the same every time (it cannot depend on user input). The functions are inserted only once, regardless of how many times the action is applied to elements in the document.

NOTE

Quotation marks ("")within the returned string must be preceded by a backslash (\) escape character to avoid errors that the JavaScript interpreter reports.

Example

The following instance of the behaviorFunction() function returns the MM_popupMsg() function:

 function behaviorFunction(){   return ""+   "function MM_popupMsg(theMsg) { //v1.0\n"+   "  alert(theMsg);\n"+   "}"; } 

The following example is equivalent to the preceding behaviorFunction() declaration and is the method used to declare the behaviorFunction() function in all behaviors that come with Dreamweaver:

 function MM_popupMsg(theMsg){ //v1.0   alert(theMsg); } function behaviorFunction(){   return "MM_popupMsg"; } 

canAcceptBehavior()

Description

This function determines whether the action is allowed for the selected HTML element and specifies the default event that should trigger the action. Can also check for the existence of certain objects (such as SWF files) in the user's document and not allow the action if these objects do not appear.

Arguments

 HTMLElement 

• The argument is the selected HTML element.

Returns

Dreamweaver expects one of the following values:

• A TRue value if the action is allowed but has no preferred events.

• A list of preferred events (in descending order of preference) for this action. Specifying preferred events overrides the default event (as denoted with an asterisk [*] in the Event file) for the selected object. See step 1 in "How Behaviors work" on page 306.

• A false value if the action is not allowed.

If the canAcceptBehavior() function returns a false value, the action is dimmed in the Actions pop-up menu on the Behaviors panel.

Example

The following instance of the canAcceptBehavior() function returns a list of preferred events for the behavior if the document has any named images:

 function canAcceptBehavior(){    var theDOM = dreamweaver.getDocumentDOM();   // Get an array of all images in the document   var allImages = theDOM.getElementsByTagName('IMG');    if (allImages.length > 0){     return "onMouseOver, onClick, onMouseDown";   }else{     return false;   } } 

displayHelp()

Description

If this function is defined, a Help button appears below the OK and Cancel buttons in the Parameters dialog box. This function is called when the user clicks the Help button.

Arguments

None.

Returns

Dreamweaver expects nothing.

Example

 // the following instance of displayHelp() opens // in a browser a file that explains how to use // the extension. function displayHelp(){   var myHelpFile = dw.getConfigurationPath() +     '/ExtensionsHelp/superDuperHelp.htm';   dw.browseDocument(myHelpFile); } 

deleteBehavior()

Description

This function undoes any edits that the applyBehavior() function performed.

NOTE

Dreamweaver automatically deletes the function declaration and the event handler that are associated with a behavior when the user deletes the behavior in the Behaviors panel. It is necessary to define the deleteBehavior() function only if the applyBehavior() function performs additional edits on the user's document (for example, if it inserts a tag).

Arguments

 applyBehaviorString 

• This argument is the string that the applyBehavior() function returns.

Returns

Dreamweaver expects nothing.

identifyBehaviorArguments()

Description

This function identifies arguments from a behavior function call as navigation links, dependent files, URLs, Netscape Navigator 4.0-style references, or object names so that URLs in behaviors can update if the user saves the document to another location and so the referenced files can appear in the site map and be considered dependent files for the purposes of uploading to and downloading from a server.

Arguments

 theFunctionCall 

• This argument is the string that the applyBehavior() function returns.

Returns

Dreamweaver expects a string that contains a comma-separated list of the types of arguments in the function call. The length of the list must equal the number of arguments in the function call. Argument types must be one of the following types:

• The nav argument type specifies that the argument is a navigational URL, and therefore, it should appear in the site map.

• The dep argument type specifies that the argument is a dependent file URL, and therefore, it should be included with all other dependent files when a document that contains this behavior is downloaded from or uploaded to a server.

• The URL argument type specifies that the argument is both a navigational URL and a dependent URL or that it is a URL of an unknown type and should appear in the site map and be considered a dependent file when downloading from or uploading to a server.

• The NS4.0ref argument type specifies that the argument is a Netscape Navigator 4.0-style object reference.

• The IE4.0ref argument type specifies that the argument is an Internet Explorer DOM 4.0-style object reference.

• The objName argument type specifies that the argument is a simple object name, as specified in the NAME attribute for the object. This type was added in Dreamweaver 3.

• The other argument type specifies that the argument is none of the above types.

Example

This simple example of the identifyBehaviorArguments() function works for the Open Browser Window behavior action, which returns a function that always has three arguments (the URL to open, the name of the new window, and the list of window properties):

 function identifyBehaviorArguments(fnCallStr) {   return "URL,other,other"; } 

A more complex version of the identifyBehaviorArguments() function is necessary for behavior functions that have a variable number of arguments (such as Show/Hide Layer). For this example version of the identifyBehaviorArguments() function, there is a minimum number of arguments, and additional arguments always come in multiples of the minimum number. In other words, a function with a minimum number of arguments of 4 may have 4, 8, or 12 arguments, but it cannot have 10 arguments:

 function identifyBehaviorArguments(fnCallStr) {   var listOfArgTypes;   var itemArray = dreamweaver.getTokens(fnCallStr, '(),');   // The array of items returned by getTokens() includes the   // function name, so the number of *arguments* in the array   // is the length of the array minus one. Divide by 4 to get the   // number of groups of arguments.   var numArgGroups = ((itemArray.length - 1)/4);   // For each group of arguments   for (i=0; i < numArgGroups; i++){   // Add a comma and "NS4.0ref,IE4.0ref,other,dep" (because this    // hypothetical behavior function has a minimum of four    // arguments the Netscape object reference, the IE object    // reference, a dependent URL, and perhaps a property value    // such as "show" or "hide") to the existing list of argument    // types, or if no list yet exists, add only   // "NS4.0ref,IE4.0ref,other,dep"   var listOfArgTypes += ((listOfArgTypes)?",":"") + "NS4.0ref,IE4.0ref,other,dep";   } } 

inspectBehavior()

Description

This function inspects the function call for a previously applied behavior in the user's document and sets the values of the options in the Parameters dialog box accordingly. If the inspectBehavior() function is not defined, the default option values appear.

NOTE

The inspectBehavior() function must rely solely on information that the applyBehaviorString argument passes to it. Do not attempt to obtain other information about the user's document (for example, using dreamweaver.getDocumentDOM()) within this function.

Arguments

 applyBehaviorString 

• This argument is the string that the applyBehavior() function returns.

NOTE

If the HTML element contains code that is similar to 'onClick="someBehavior(); return document.MM_returnValue;"', and you add a new behavior from the behavior menu, Dreamweaver calls inspectBehavior() as soon as the new behavior UI pops up, and passes an empty string as the parameter. Consequently, be sure to check the applyBehaviorString parameter, as shown in the following example:

 function inspectBehavior(enteredStr){   if(enteredStr){   //do your work here   } } 

Returns

Dreamweaver expects nothing.

Example

The following instance of the inspectBehavior() function, taken from the Display Status Message.htm file, fills in the Message field in the Parameters dialog box with the message that the user selected when the behavior was originally applied:

 function inspectBehavior(msgStr){   var startStr = msgStr.indexOf("'") + 1;   var endStr = msgStr.lastIndexOf("'");   if (startStr > 0 && endStr > startStr) {     document.theForm.message.value = unescQuotes(msgStr.substring(startStr,endStr));   } } 

NOTE

For more information about the unescQuotes() function, see the dwscripts.js file in the Configuration/Shared/Common/Scripts/CMN folder.

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 Parameters dialog box that is larger than 640 x 480 pixels.

Arguments

 platform 

• The value of the 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 instance of windowDimensions() sets the dimensions of the Parameters dialog box to 648 x 520 pixels:

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