How Behaviors Are Constructed
Figure 3.1. A Dreamweaver document with behavior code inserted.
Because of the restrictions imposed by the behavior API, there are all kinds of scripting setups you cannot create using behaviors. You can't, for instance, use a behavior to insert a <script> tag into a document's body, and the code inserted by a behavior can't declare global variables , and so on. To extend Dreamweaver so that it performs these kinds of tasks , you need to use other extension types, such as commands. (See Chapter 8, "Mixing Extension Types," for more on this.)
Behaviors in the Configuration Folder
Figure 3.2. The Behavior/Actions folder structure, as it corresponds to the Behaviors panel's actions menu structure.
A behavior consists of the following files:
Structure of a Behavior File
Like objects, behaviors can be simplecontaining only the required elementsor they can be refined with a number of features. The next two sections discuss the elements in both simple and more full-featured behavior files.
Required Elements (Simplest)
Every behavior must have the following basic elements:
Page title. Whatever appears in the document's <title> tag becomes the name of the actions menu item for the behavior.
Function to be inserted. Remember: every behavior must insert a generic function and a customizable function call. The <head> section of the behavior file (or its linked JS file) must include the function you want the behavior to insert, exactly as you want it to be inserted. This function must have a unique name (that is, two Dreamweaver behaviors can't both insert functions with identical names ).
behaviorFunction() function. This function, which is part of the API and is called automatically, returns the name of the function to be inserted, without its ending parentheses. Dreamweaver uses this function to identify the function it's supposed to insert.
applyBehavior() function. This function, also part of the API and also called automatically, returns the function call to be inserted. If the function call depends on user input to customize its parameters, this return statement needs to be constructed from form input, just as we did with the objectTag() function in the previous chapter.
<body> content. Any content in the <body> section becomes the behavior's dialog box.
Listing 3.1 shows the basic structural elements required for a behavior file.
Listing 3.1 A Basic Behavior File, Containing Only Required Elements and Commented for Reference
Optional Elements (Fancier)
In addition to these required elements, the following elements are recommended for the behavior file:
canAcceptBehavior() function. This function determines whether or not the behavior is grayed-out (unavailable) in the actions menu. It can also be used to determine the default event handlers that will be used in the function call when the behavior is inserted into the user's document. Behaviors for controlling layers, for instance, should be unavailable in the menu if there are no layers to control in the user's current document. This function is called automatically as part of the API procedure.
inspectBehavior() function. After a behavior has been inserted into a user's document, it appears in the Behaviors panel whenever the page element it's attached to is selected. The user expects to be able to double-click here to open the behavior's dialog box and edit its settings. The inspectBehavior() function allows Dreamweaver to fill the dialog box with the currently chosen settings. If this function is not present in the behavior file, when the user double-clicks to edit her behavior, she will see a default (blank) dialog box. This function is called automatically as part of the API procedure.
displayHelp() function. This function works in behaviors exactly as it does in object files. If this function is defined, a Help button appears in the behavior's dialog box. The function can be used to call an online or offline help document, or to create a popup window containing help information. (See the description of displayHelp() in the section "Full-Featured Objects" in Chapter 2.)
Local functions. As with object files, behavior files can include any number of custom or "local" functions, as long as they are explicitly defined and called.
API Procedure for Behaviors
After reading the previous descriptions of behavior file elements, you can see that the Dreamweaver procedure for handling behaviors is more complex than that for handling objects.
The procedure starts when the user clicks the + menu in the Behaviors panel. For each file in the Actions folder, Dreamweaver calls the canAcceptBehavior() function to determine which behaviors should be available in the actions popup menu. If the function returns false , the behavior is grayed-out. If the function returns a list of event handlers, Dreamweaver determines whether any of the events listed are valid for the currently selected HTML element and for the target browser; if none is valid, the command is grayed-out. Otherwise, the behavior is available.
After the user selects an available behavior from the menu, the following events occur:
Dreamweaver displays a dialog box containing the contents of the behavior file's <body> tag.
If the <body> tag contains an onLoad event handler, its function is executed now.
Dreamweaver supplies the OK and Cancel buttons . If the program finds a displayHelp() function in the behavior file, it also displays a Help button.
Any local functions attached to individual form elements using onBlur or onChange execute as the user proceeds through the dialog box. Other than responding to these functions, the program waits for the user to click OK.
After the user clicks the OK button, Dreamweaver calls the behaviorFunction() and applyBehavior() functions, and inserts the specified function and function call into the user's document. (Note that Dreamweaver is pretty smart about this. If the function already exists in the user's document, it is not inserted twice; in such a case, only the new function call is inserted.)
Figure 3.3 shows a flowchart diagramming this process.
Figure 3.3. The API procedure for inserting behaviors.
API Procedure for Inspecting Behaviors
After the behavior is inserted into a user's document, the user can inspect and edit it at any time by double-clicking on it in the Behaviors panel. The Dreamweaver procedure for what happens at this point is as follows .
Dreamweaver looks for the inspectBehavior() function in the behavior file. If this function is defined, it is executed and its return value is used to fill in the form fields of the dialog box with the appropriate values. Otherwise, the dialog box appears in its default state (that is, the same way it appeared when the behavior was first chosen, with blank form fields or default values present).
From this point on, the API process is the same as when the behavior was first inserted. Dreamweaver supplies the OK and Cancel buttons for the dialog box; local functions called by onChange and onBlur events are executed as called. When the user clicks OK, the behaviorFunction() and applyBehavior() functions are called, but instead of inserting a new instance of the behavior, they update the behavior that has already been inserted into the document.
If the user later selects the action in the behavior inspector and deletes it, Dreamweaver removes the function call. The function itself is removed only if it is not called elsewhere in the document.
The flowchart shown earlier in Figure 3.3 shows how the inspection process relates to the process for inserting behaviors.