< Day Day Up > |
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
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
Returns Dreamweaver expects one of the following values:
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
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
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:
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
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
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"; } |
< Day Day Up > |