Inspecting Behaviors

After a user has inserted a behavior into a document, how can he edit it? By opening up the Behaviors panel and double-clicking on the behavior, which reopens the behavior's dialog box and lets him see and change all the parameters assigned to it.

Have you tried doing that with any of the behaviors you created here? It doesn't work! Double-click an existing instance of the Go Back/Forward or Set Page Properties behavior, and the dialog box reopens, but without any of the values you had previously set for it. That's because your behaviors don't have an inspectBehavior() function.

The inspectBehavior() Function and How it Works

The purpose of this function is to fill in the form elements of the behavior's dialog box based on the parameters Dreamweaver finds in the document's inserted function call. It works like this: Whenever the user double-clicks a behavior in the Behaviors panel, Dreamweaver looks in the appropriate behavior file for the inspectBehavior() function and executes that function, automatically passing the inserted function call to it as a text string. It's your job to script the inspectBehavior() function so that it parses that text string to extract the various parameters, and tells Dreamweaver which pieces of information should go into which form fields. Not an impossible job, or even that difficultbut it can be very, very fiddly.

Inspecting Behaviors: Practice Session

To see how the inspection process works, create a very simple practice file and do some inspecting.

Task 1: Create a practice file

The first task is to create a practice file with a passed parameter, and test it.

In your text editor, open My Behavior.htm. Save a copy of it as My New Behavior.htm in the Actions/Development folder. So that neither Dreamweaver nor you get confused between the two My Behaviors, also change the <title> to My New Behavior , and change the defined function name to newBehavior() . (You'll need to change references to the defined function in the behaviorFunction() and applyBehavior() functions as well.)
If you remember, the script inserted by this behavior causes an alert window to open when the function is called. Change the behavior so that Dreamweaver asks the user what message the window should hold; this information should be passed to newBehavior() as part of the function call. This will require adding a form to the <body> and changing the applyBehavior() function so that it constructs the function call based on user input. Listing 3.6 shows the code for the revised behavior file.

Listing 3.6 The Code for My New Behavior.htm, before Inspection Functions Have Been Added
```
 <html>  <head>  <title>My New Behavior</title>  <script language="JavaScript">  function newBehavior(myParameter) {    alert(myParameter)  }  function behaviorFunction() {    return "newBehavior";  }  function applyBehavior() {    var message = document.myForm.messageField.value;    return "newBehavior('"+message+"')";  }  </script>  </head>  <body>  <form name="myForm">  <table>    <tr>      <td><input type="text" name="messageField"></td>    </tr>  </table>  </form>  </body>  </html> 
```
Try the behavior out in Dreamweaver to see how it worksand how it doesn't work. (Don't forget, you'll have to quit and relaunch Dreamweaver to make it recognize the new behavior.) Create a test document with a simple text link and add the behavior to that link (just like you did when testing My Behavior earlier in this chapter). A dialog box should appear, asking for a message. Enter a message and click OK to close the dialog box.
Preview the page in a browser. Clicking the text link opens an alert window containing your custom message.
Now go back to Dreamweaver and try to edit the behavior by double-clicking its entry in the Behaviors panel. The dialog box reopens, but with no message in place (see Figure 3.20).

Figure 3.20. Trying to inspect and edit a behavior in the Behaviors panel when there is no inspectBehavior() function defined.

Task 2: Add the inspectBehavior() function

Now add the inspectBehavior() function and test it to ensure that it works properly.

In your text editor, add the framework code for the inspectBehavior() function to the <script> tag of your behavior file. It should look like this:
```
 function inspectBehavior(fnCall) {  //collect information from fnCall  //put information into form fields  } 
```
The fnCall parameter is what Dreamweaver automatically passes to inspectBehavior() when it's called, as part of the API procedure. This parameter holds a text string that will look something like this:
```
 "newBehavior('Hello world!')" 
```
In the body of inspectBehavior() , you need to pull out the relevant portion of that passed string and use it to refill your dialog box field.
Because the fnCall parameter is a text string, you can do this by using the substring method. The substring method requires that you know the first and last character of the substring you want to remove from the main string, which you should be able to figure out by counting characters : The function call string will always begin with newBehavior(' , which is thirteen characters, and the message will always start after thatso you want your substring to begin at the fourteenth character. You don't know how many characters the substring itself will contain (because you can't know what messages the user will enter into the dialog box each time he inserts the behavior). But you do know that the function call will always end with ') , which is two letters longso the last letter of the substring will always be the third character from the end. With this knowledge, you can add a variable to your function that collects the proper information, like this (new code is in bold):
```
 function inspectBehavior(fnCall) {  //collect information from fnCall  var myMessage=fnCall.substring(13,fnCall.length-2);  //put information into form fields  } 
```
(If you're wondering why you didn't enter 14 as the starting number, remember that computers always count from 0, not 1, so the fourteenth character is character 13.)
After you have collected the message in a variable, you just need to feed this information into the proper field in the form, which in this case is a text field named messageField . So you add one more line to your function (new code is in bold):
```
 function inspectBehavior(fnCall) {  //collect information from fnCall  var myMessage=fnCall.substring(12,fnCall.length-2);  //put information into form fields  document.myForm.messageField.value=myMessage;  } 
```
After you enter this code, reload extensions in Dreamweaver and try again to edit the behavior. As long as your character counting was accurate when you calculated your substring, double-clicking the behavior in the Behaviors panel should open a fully populated dialog box (a dialog box with your message showing in its text field). Figure 3.21 shows this happening. When the behavior's dialog box is open again, you change the contents of the message Dreamweaver goes back through the API process of calling the behaviorFunction() function and applyBehavior() function to insert the updated behavior into your document. (Refer back to the API procedure diagram in Figure 3.3 to see how this works).

Figure 3.21. Inspecting and editing a behavior in the Behaviors panel after the inspectBehavior() function has been defined.

Using the Shared Files to Help Inspect Behaviors

What's wrong with this picture? Nothing, as long as all your function calls are as simple as the one in your practice file. But when you get calls with multiple parameters, character counting isn't efficient. You need to set up loops that can break text strings down into substrings separated by delimiters like commas and quotation marks, and your scripting life just gets a lot more complicated.

Luckily for you, the Macromedia software engineers have already been here and done that. They've solved this problem for you. Dreamweaver ships with a collection of JS files that contain utility scripts for a variety of purposes. All of the standard behaviors that ship with the program use these scripts for tedious tasks such as refilling dialog boxes. None of them is part of the API, but you can use them just as you have been using your own local functions, simply by linking to the relevant JS file.

Finding and Examining dwscripts .js

The most commonly used shared files are stored in the Configuration folder, in the Shared/Common/Scripts folder. The most generally useful shared file is dwscripts.js. This file defines a new object class called dwscripts . The methods of dwscripts include functions for performing many common extension-writing tasks.

Find dwscripts.js, and open it in your text editor. It's a good idea to see what's in there that you might want to use in future extension projects.

The dwscripts.extractArgs() Methods

The key to happy behavior inspecting is the dwscripts.extractArgs() method. This method loops through a text string, pulling out substrings and assigning them to slots in an array. Assuming you pass it a function call as the string to be parsed, the first substring it pulls out is always the function call itself, the next substring is the first parameter that was included in the function call, the following substring is the second parameter, and so on.

Linking to dwscripts.js

Before you can take advantage of dwscripts.extractArgs() , you need to link to the shared file. Do this by adding another <script> tag to the head section of your behavior file, including a relative path to dwscripts.js, like this:

 <script src="../../../Shared/Common/Scripts/dwscripts.js"></script>

This code shows the relative address to dwscripts.js from a file within Behaviors/Actions/Development. If your behavior is not stored in a subfolder within the Actions folder, you need to amend the address accordingly .

note

Remember the rules of relative addressing! A relative address describes the path from one file to another, navigating the hierarchy of the folder structure as it goes. If the two files are in different folders, the path must move up the hierarchy until it reaches a common parent folder before it can move down the hierarchy into the other folder. In writing the path, the characters ../ indicate moving up one folder. When linking from an extension file to a shared file like string.js, the common parent folder is usually the Configuration folder itself. How many folder levels must you traverse up the hierarchy from your extension file to the Configuration folder? That's the number of ../ elements your relative address must include.

The inspectBehavior() Function, Using dwscripts.extractArgs()

With the help of dwscripts.extractArgs() , you can now revisit inspectBehavior() and create a simple script for repopulating (re-filling) the dialog box. All you need to do is revise the inspectBehavior() function so that it calls dwscripts.extractArgs() , passing the fnCall parameter as a string, and feed the results to a new array. Then access the array, one item at a time, assigning each item to a field in your form. Here's how the code would look for the My New Behavior file you practiced on (new code is in bold):

 function inspectBehavior(fnCall) {  var argArray = new Array;   argArray = dwscripts.extractArgs(functionCall);  document.myForm.messageField.value =  argArray[1]  ;  }

note

Warning

Anxious to try this out in the My Behavior 2.html practice file? Here's a word of warning: You may have trouble getting Dreamweaver to recognize the linked JS file, unless you first split your code into My Behavior 2.html and My Behavior 2.js.

The inspectBehavior() Function and How it Works

Inspecting Behaviors: Practice Session

Listing 3.6 The Code for My New Behavior.htm, before Inspection Functions Have Been Added

Figure 3.20. Trying to inspect and edit a behavior in the Behaviors panel when there is no `inspectBehavior()` function defined.

Figure 3.21. Inspecting and editing a behavior in the Behaviors panel after the `inspectBehavior()` function has been defined.

Using the Shared Files to Help Inspect Behaviors

Finding and Examining dwscripts .js

The dwscripts.extractArgs() Methods

Linking to dwscripts.js

The inspectBehavior() Function, Using dwscripts.extractArgs()

Inspecting Behaviors

The inspectBehavior() Function and How it Works

Inspecting Behaviors: Practice Session

Listing 3.6 The Code for My New Behavior.htm, before Inspection Functions Have Been Added

Figure 3.20. Trying to inspect and edit a behavior in the Behaviors panel when there is no inspectBehavior() function defined.

Figure 3.21. Inspecting and editing a behavior in the Behaviors panel after the inspectBehavior() function has been defined.

Using the Shared Files to Help Inspect Behaviors

Finding and Examining dwscripts .js

The dwscripts.extractArgs() Methods

Linking to dwscripts.js

The inspectBehavior() Function, Using dwscripts.extractArgs()

Figure 3.20. Trying to inspect and edit a behavior in the Behaviors panel when there is no `inspectBehavior()` function defined.

Figure 3.21. Inspecting and editing a behavior in the Behaviors panel after the `inspectBehavior()` function has been defined.