Server Behavior API

This part of the API is complex and is distinctly different from anything you've seen beforeto accommodate the different languages and structures the server markup can have. The good news is that unless you want to do something fancy, you don't have to code your server behavior extensions by hand. Dreamweaver provides a special interface, the Server Behavior Builder (SBB), to do the coding for you. In this chapter, we'll take a look at working with the builder; then we'll see what's really going on "under the hood" for those occasions when you want to tweak the coding yourself.

note

Standard extensions such as objects and commands can be used to insert server markup. The advantage of coding your custom markup snippets as server behaviors is that you take advantage of the Dreamweaver management system. For instance, your behavior will appear as a menu choice only if the user is working with the appropriate server model and language (for example, ASP/JavaScript).

Server Behavior Builder

Even fairly complex server-side code can be built into an extension without handcoding, by using the SBB. The basic procedure is simple:

Determine exactly what code you want to insert (and make sure it works!), and which portions if any should be user-specified through a dialog box.
In the Server Behaviors panel, click the + button to show the actions list, and choose New Server Behavior (see Figure 9.1). This activates the SBB.

Figure 9.1. Accessing the New Server Behavior command from the Server Behaviors panel.
Follow the instructions in the dialog boxes that follow, and Dreamweaver will build the extension for you.

Some Basic Server Behavior Concepts

Even if you're using the Server Behavior Builder to do all the dirty work, you need to know a few fundamentals of how server behaviors work. These fundamentals will be even more important if you decide to code your own behaviors directly. The following list describes some of these elements, and Figure 9.2 shows how these elements will be added to the SBB main dialog box.

Figure 9.2. The SBB dialog box. Multiple code blocks, parameters, and position/ weighting are set here.

graphics/09fig02.gif

Multiple code blocks. The server markup that comprises a server behavior can consist of several individual blocks of code to be entered in different places in the document. Variables may be set above the <html> tag, for instance, and then used in the <body> . When defining the behavior, each block must be specified separately.
Position and weighting. The various code blocks in a behavior may need to be positioned at the top of the document, above the opening <html> tag; at the bottom, beneath the closing </html> tag; or before, after, or surrounding the user's current selection. For code blocks placed above the <html> tag, certain blocks may need to precede others. Dreamweaver uses a weighting system, from 199, to determine how to order these blocks. The higher a block's weight is, the further down the list it can be placed. A block with a weight of 99 will be added after all other code blocks, directly preceding the <html> tag. A block with a weight of 1 will be inserted as the very first piece of code in the documentafter the language declaration. For each code block you create, you'll be asked where to position it; if the block should be positioned above the <html> tag, you'll also need to specify a weight to determine how it should be placed relative to other above-the-tag elements.
Parameters. If you want your server behavior to include customizable elements that will be determined by user input, you can add parameter placeholders. If the behavior includes one or more parameters, Dreamweaver will automatically generate a dialog box to collect the user input for those parameters. Dreamweaver stores parameter values in the code as @@ parameter_name @@ , so it knows to replace them with user input.

Building Server Behaviors: Practice Session

To see how the SBB works, we'll create a few very simple server behaviors. For the examples shown here, we'll insert various pieces of ASP/JavaScript markup. Feel free to substitute code from another server model or language, if you prefer.

Task 1: Create a server behavior that inserts a "Hello, world" message

For our first behavior, we'll use a simple statement that inserts a line of code:

 <%="Hello, world!"%>

To make things simple, we won't allow for any user inputthis behavior will always insert exactly the same hello message.

Before you can proceed with this task, you need to activate the Server Behaviors panel by defining a dynamic site and opening a dynamic document. Take a moment to do that now, using ASP/JavaScript as your server model. (If you want to, follow the example code shown here.)

In the Server Behaviors panel, click the + button to access the Behaviors menu. From the menu, choose New Server Behavior. In the dialog box that follows , choose your language (ASP/JavaScript, if you're using the code as shown here), and give your behavior the name Hello world (as shown in Figure 9.3). When you're done, click OK to close the dialog box.

Figure 9.3. Naming the new server behavior, and specifying a language for it.
Next, you're presented with the SBB dialog box. The rest of your behavior building will take place in this interface.
Click the + button in the upper left corner to add a new code block. The Create a New Code Block dialog box appears, giving your new code block the default name of Hello_World_block_1 . That's a fine code block name, so click OK to accept it. Figure 9.4 shows this happening.

Figure 9.4. Creating a new code block for the Hello World server behavior.
Back in the SBB dialog box, the top information field shows your new code block in place. The middle field now contains some default code for the block. Replace that code with the code chosen earlier in this Task ( <%="Hello, world!"%> ). At the bottom of the dialog box, from the first popup menu choose to insert the code block Relative to Selection; from the second popup menu, choose to Replace Current Selection. Figure 9.5 shows this happening.

Figure 9.5. The SBB dialog box, showing settings for the Hello World behavior.
That's it! Click OK to close the dialog box, and try it out. As long as you have an ASP/JavaScript document (or whatever kind of document you specified when you created the behavior) open , your new behavior will appear in the + menu of the Server Behavior panel. Inserting it will plug your specified code into the active document, wherever the cursor is.

Task 2: Create a server behavior that inserts a user-defined message

Next, we'll create a behavior that uses a variable to insert a user-specified message into the document. The finished code will consist of two code blocks. Above the <html> tag, the behavior will add the following code (shown in ASP/JavaScript):

 <% var myVar="  @@param1@@  " %>

(The @@param1@@ value will be replaced by the custom message the user chooses when he inserts the behavior.) At the cursor, the behavior will insert the following:

 <%=myVar%>

Start as you did in the previous task, by clicking + in the Server Behaviors panel and choosing New Server Behavior. Name the new behavior Custom Message , and choose the appropriate server model and language (ASP/JavaScript to match the examples here).
In the SBB dialog box, click + to add a new code block. Leave the code block name at the default ( Custom_Message_block_1 ) and click OK to close the dialog box.
For the code block, enter the variable declaration shown previously, but without the @@ -defined parameter, like this:
```
 <% var myVar= %> 
```
Position the cursor where the parameter should be inserted (after the = ) and click the Insert Parameter button. A dialog box opens, asking you to name the parameter. Leave the name at its default (param1) and click OK to close the dialog box (see Figure 9.6). Back in the SBB dialog box, Dreamweaver has entered the parameter code for you.

Figure 9.6. Adding a user-defined parameter to a server behavior code block.
For the positioning and weighting of your code block, use the two popup menus to enter the code block just above the <html> tag. (Its relative position above the tag won't matter because the server won't be accessing the variable until the <body> tag has loaded.) Figure 9.7 shows the dialog box as it should appear when you're done.

Figure 9.7. The SBB dialog box, with settings in place for the first code block of the Custom Message behavior.

Figure 9.8. The SBB dialog box with all settings for the Custom Message behavior in place.
Repeat the previous procedure to create the second code block of your behavior. You won't need to assign any parameters, and the position should be relative to the selection, replacing the current selection. Figure 9.8 shows the finished SBB dialog box.
Now that you've added a parameter, the OK button has been replaced by a Next button. Click this button, and Dreamweaver asks what sort of dialog box should ask for the parameter (see Figure 9.9). For this behavior, leave the input type at Text Field , and click OK. Your behavior is finished. Try it out! Figure 9.10 shows the new server behavior being chosen and inserted.

Figure 9.9. The SBB dialog box for creating a dialog box to collect user input.

Figure 9.10. The Custom Message server behavior being applied.

Beyond the SBB: How Server Behaviors Are Constructed

When you use the SBB, extension files are being manipulated and created for you. If you want to move beyond the confines of the SBBor if you just enjoy knowing what's happening "under the hood" as you workyou'll want to examine the server behavior API in more detail.

Server Behaviors in the Configuration Folder

Each server behavior is constructed from three or more files stored in the Configuration/Server Behaviors folder, in the subfolder corresponding to the appropriate markup language (ASP, JSP, ColdFusion, and so forth).

note

On multiuser systems, these files are stored in the userspecific Configuration folder.

HTML/JS

Like all extensions covered so far, server behaviors begin with an HTML file. The HTML file, with an optional linked JS file, contains instructions for constructing and inserting the server markup into the user's document.

XML

Unlike other extension types covered so far, the API for server behaviors separates the actual content to be insertedthe code blocksfrom the instructions on how to insert them. This content is stored in XML files with the .edml filename extension. For each behavior, the following exist:

One group file , containing information for the behavior as a whole
One participant file for each code block, containing the contents of that code block

Why put the code in XML files? Separating form from content like this allows Dreamweaver to efficiently manage similar server behaviors in each of the multiple server languages it supports.

Figure 9.11 shows the Server Behaviors/ASP_JS folder with the various Hello World and Custom Message files in place. Note that each behavior consists of one HTML file (Hello world.htm and Custom Message.htm). In addition, the first behavior consists of two XML files: a group file for the behavior as a whole (Hello World.edml) and one participant file named after the only code block the behavior inserts (Hello World_block_1.edml). The second behavior consists of three files: a group file (Custom Message.edml) and two participant files for the behavior's two code blocks (Custom Message_block_1.edml and Custom Message_block_2.edml).

Figure 9.11. The Configuration/Extension Data folder showing the XML data files for the Hello World and Custom Message behaviors.

graphics/09fig11.gif

Structure of a Server Behavior (XML)

The actual code to be inserted in the behavior is specified through custom tags and attributes in the group and participant XML files. To see the tags in action, examine the XML files for Hello World and Custom Message. For a complete listing of what the tags and attributes mean, check out Chapter 13 of the Extending Dreamweaver manual.

Structure of a Server Behavior (HTML/JS)

A server behavior's HTML/JS files must contain various functions and other API elements in order to work properly. (To see these elements at work, examine the files created by the SBB for Hello World and Custom Message.)

Page Title

Whatever appears in the document's <title> tag will become the + menu entry for the behavior and the title for any dialog box the behavior calls up.

canApplyServerBehavior(sbObj) Function

This function, which is part of the API and is called automatically, determines whether the behavior can be inserted into the user's document. It requires one argumenta JavaScript object representing the behavior to be insertedwhich Dreamweaver passes to it automatically. It returns true or false .

applyServerBehavior(sbObj) Function

This function, also part of the API and called automatically, inserts whatever code is specified in the XML files into the appropriate places in the user's document. It, too, is automatically passed one argumenta JavaScript object representing the behavior to be inserted. It relies on the applySB() helper function to perform the actual code insertion. (See the explanation of helper functions later in this chapter.)

findServerBehaviors() Function

This function is called automatically whenever a document containing an instance of the server behavior is opened. It returns an array of JavaScript objects representing all instances of the current behavior in the document. It relies on the findSBs() helper function to perform the actual search. (See explanation of helper functions later in this chapter.)

deleteServerBehavior(sbObj) Function

This API function is called automatically when the user clicks the button in the Server Behaviors panel. It is automatically passed a JavaScript object representing the behavior as it appears in the document. Its purpose is to delete the behavior. It relies on the deleteSB() helper function to perform the actual deletion. (See explanation of helper functions later in this chapter.)

analyzeServerBehavior(sbObj,allRecs) Function

This optional API function, if present, is called automatically, in conjunction with findServerBehaviors() , to populate the list of applied behaviors in the Server Behaviors panel. When called, it is automatically passed two parameters: a JavaScript object representing the behavior and an array of records that constitute the data sources for the document. Its purpose is to remove duplicates and other unnecessary items from the behaviors list.

Form

As with any extension, the dialog box for collecting user input is created from a form in the HTML file. The OK and Cancel buttons will be supplied automatically. The form is optional.

inspectServerBehavior(sbObj) Function

This optional API function, if present, is called automatically when the user doubleclicks on a behavior in the Server Behaviors panel's list. It is automatically passed a JavaScript object representing the behavior as it appears in the document. Its purpose is to repopulate the behavior's dialog box so the user can edit any parameters.

displayHelp() Function

If this optional API function is present, any dialog box will include a Help button.

Helper Functions

Back in Chapter 2, "Creating Custom Objects," in introducing the Dreamweaver API, we distinguished between functions that are part of an extension type's API procedure and those that are part of the extension-writing API, but not an automatic part of any process. The former type of function is called automatically, but must be individually scripted to return the required values. The latter type must be explicitly called, but is already scripted to return appropriate values. All of the API functions listed previously are of the former type. But several of them call on helper functions of the latter type.

The helper functions allow you to encode server behaviors with functions that are automatically called, which then call helper functions that are already scripted, and return their values. This can leave very little for you to do. The following code, for instance, finds all instances of a particular behavior in a document, without you doing much more than passing control to a helper function and returning its value:

 function findServerBehaviors() {  var sbObj=findSBs();  return sbObj;  }

Helper functions are unique in that each works only within the API function whose name it matches findServerBehaviors() and findSBs() , for instance. Table 9.1 lists the specifications of the helper functions.

Table 9.1. Server Behavior Helper Functions

Function	`applySB()`
Description	Inserts or updates the markup code for the server behavior. Must be explicitly called from `applyServerBehavior()` .
Syntax	`applySB(paramObj,sbObj)`
Arguments	`paramObj` An object representing any user-defined parameters as collected from a dialog box. This object must have a property matching each defined `@@param@@` in the relevant XML file. It is the job of `applyServerBehavior()` to construct this object. `sbObj` An object representing the server behavior instance that is to be added to the document. This is the same object that Dreamweaver passes to `applyServerBehavior()` when it calls that function.
Returns	True if the code was successfully inserted; false if not.
Example	function applyServerBehavior(sbObj) { //create parameter object paramObj=new Object(); //collect values from dialog box paramObj.msg=document.myForm.msg.value; //call the helper function applySB(paramObj,sbObj);
Function	`findSBs()`
Description	Finds all instances of the current server behavior in the current document. Must be explicitly called from `findServerBehaviors()` .
Syntax	`findSBs(` `serverBehaviorTitle` `);`
Arguments	`serverBehaviorTitle` (optional)Title string used to override the XML title.
Returns	An array of objects, one for each instance of the current behavior found in the document. Object properties contain all behavior information, as well as user-defined parameters (see example following).
Example	function findServerBehaviors() { listSBs=findSBs(); return listSBs; } Assuming the document contains one instance of the Custom Message behavior, this function will return the following array:
	listSBs[0].title="Custom Message (@@myVar@@)"; listSBs[0].type="CustomMessage"; listSBs[0].selectedNode=null; listSBs[0].incomplete=false; listSBs[0].participants[0]=someAspNodePointer; listSBs[0].weights[0]=aboveHTML+99; listSBs[0].types[0]="CustomMessage_block1"; listSBs[0].participants[1]=someAspNodePointer; listSBs[0].weights[1]=replaceSelection; listSBs[0].types[1]="CustomMessage_block2"; listSBs[0].parameters.Param1="This is my message. "; (Compare the results here with the specifications in the Custom FMessage XML files.)
Function	`deleteSB()`
Description	Deletes all code blocks relating to the selected instance of the current behavior. Must be explicitly called from `deleteServerBehaviors()` .
Syntax	`findSBs(` `sbObj` `);`
Arguments	`sbObj` An object representing the server behavior instance that is to be added to the document. This is the same object that Dreamweaver passes to `deleteServerBehavior()` when it calls that function.
Returns	Nothing
Example	function deleteServerBehavior(sbObj) { deleteSB(sbObj); }

API Procedure for Server Behaviors

Figure 9.12 diagrams the API procedure for processing server behaviors. As the diagram shows, various processes can occur, initiated by the user adding, editing, duplicating, or deleting behaviors, or opening documents containing behaviors. The diagram also shows the importance of the JavaScript object array, created by findServerBehaviors() and accessed by other functions. It also shows the interrelationship between the main API functions and their helper functions, and how all processes depend on JavaScript objects representing behavior instances in the document.

Figure 9.12. The API procedure for processing server behaviors. User actions are indicated by text outside boxes.

graphics/09fig12.gif

We'll finish up this look at Server Behaviors with two workshops that will show you how to build behaviors with the SBB and beyond. For the projects and code written here, we'll be using the ASP/JavaScript server model. To develop and test them, you'll need access to an ASP server and a simple database.

note

You can download some sample ASP and database files to play with from this book's companion web site, www.newriders.com (see Appendix F, "Contents of the Extensions Workshop Companion Web Site" for full details).

Server Behavior Builder

Figure 9.1. Accessing the New Server Behavior command from the Server Behaviors panel.

Some Basic Server Behavior Concepts

Figure 9.2. The SBB dialog box. Multiple code blocks, parameters, and position/ weighting are set here.

Building Server Behaviors: Practice Session

Figure 9.3. Naming the new server behavior, and specifying a language for it.

Figure 9.4. Creating a new code block for the Hello World server behavior.

Figure 9.5. The SBB dialog box, showing settings for the Hello World behavior.

Figure 9.6. Adding a user-defined parameter to a server behavior code block.

Figure 9.7. The SBB dialog box, with settings in place for the first code block of the Custom Message behavior.

Figure 9.8. The SBB dialog box with all settings for the Custom Message behavior in place.

Figure 9.9. The SBB dialog box for creating a dialog box to collect user input.

Figure 9.10. The Custom Message server behavior being applied.

Beyond the SBB: How Server Behaviors Are Constructed

Server Behaviors in the Configuration Folder

HTML/JS

XML

Figure 9.11. The Configuration/Extension Data folder showing the XML data files for the Hello World and Custom Message behaviors.

Structure of a Server Behavior (XML)

Structure of a Server Behavior (HTML/JS)

Page Title

canApplyServerBehavior(sbObj) Function

applyServerBehavior(sbObj) Function

findServerBehaviors() Function

deleteServerBehavior(sbObj) Function

analyzeServerBehavior(sbObj,allRecs) Function

Form

inspectServerBehavior(sbObj) Function

displayHelp() Function

Helper Functions

Table 9.1. Server Behavior Helper Functions

API Procedure for Server Behaviors

Figure 9.12. The API procedure for processing server behaviors. User actions are indicated by text outside boxes.