Creating custom server behaviors and Dreamweaver extensions

Note: This article was originally written by Simon Horwith in 2004 and updated by Raymond Camden.

For many people who never used Dreamweaver, the editor has something of a negative reputation. It's the memory hog. It's the editor for designer people, not developers. Basically, it isn't for real programmers. I was certainly in that camp for quite some time. Over the past few months I've had the opportunity to work with Dreamweaver CS4. I'll be honest and say I had to work with it. I was surprised to discover that Dreamweaver CS4 is certainly more then just a simple text editor for those non-developers out there. The editor is truly a platform that serious coders can build upon and expand with their own tools. In this article I discuss one such way of doing that: server behaviors.

What are Dreamweaver server behaviors?

To put it simply, server behaviors are pre-written chunks of text that you can insert into your page in Dreamweaver with a few mouse clicks. If you use other editors, you may have seen features like this with the name Snippets or Short Cuts. Most likely these tools use something similar to what Dreamweaver can provide, but there's a lot more behind server behaviors then just pasting in remembered text. . The major differences between a server behavior and a snippet are:

• Server behaviors can be parameterized.
• Dreamweaver recognizes server behaviors in your code.
• You can package server behaviors as Dreamweaver extensions.

In Dreamweaver CS4, developers can create a snippet of text and associate a keyboard shortcut with that snippet so they can quickly insert it into pages. For very static text, this is fine. However, often times you must customize the code in a snippet in order for it to be accurate for the page you are inserting it into. By using a server behavior, you can parameterize that piece of text and prompt developers for the parameter values before Dreamweaver inserts the text snippet. What's more, the user interface presented to users is not limited to simple text input controls to capture values. You can present them with browse buttons, data source pop-up menus, and many other robust form field types.

In order to extend Dreamweaver with your own functionality, you can extend the environment by writing JavaScript. Under the hood, Dreamweaver exposes its interface, configuration settings, the current document, and more through a special JavaScript DOM. The built-in Server Behavior Builder utility gives Dreamweaver users the ability to extend the environment without having to learn any new technology or scripting language. Most ColdFusion developers place a comment block containing information such as the author name, supported ColdFusion version, file name, purpose, and description, and so on at the top of every page they create. This repetitive task can be made simple and the comments at the top of every page are standard by creating a page comment server behavior. I will start with a typical comment block as follows:

As I mentioned earlier, if all you want is to insert this text at the top of your pages, a snippet will do. However, perhaps you are a consultant or you work on many different applications, possibly running on a variety of ColdFusion application server versions. Every time you use the snippet, you would then have to manually "correct" its information. I will walk through the steps to turn this snippet of text into a server behavior that will ask you for the appropriate values before putting the comment into your document.

1. To begin, open any CFML page with Dreamweaver CS4 (or create a new CFML page by choosing File > New > ColdFusion [Page Type]). You must open a file to use the server behavior panel. You will find the server behaviors tab within the Application panel in Dreamweaver (see Figure 1).

2. To add a new server behavior, click the plus (+) button on the server behaviors tab and select New Server Behavior from the menu. A dialog box similar to Figure 2 will open.

This is a ColdFusion comment, so leave the Document type pop-up menu on its default of ColdFusion.

3. Change the text in the Name text box to Page Comment and leave the option for copying an existing server behavior unchecked.
4. Click OK to continue. Dreamweaver now displays a dialog box similar to Figure 3. In this dialog box, you can add all of the text blocks that the server behavior will insert into a document, define the editable regions of the text block(s), and specify for Dreamweaver where and how in the current document to insert the text block(s).

5. Click the plus (+) button in the upper left corner of the dialog box (see Figure 3) to add a text block to the server behavior. A dialog box asks you to specify the name of this text block.
6. Rename the text block or leave the default value and then click OK.
7. After clicking the OK button to assign a name to the new text block, it returns you to the Server Behavior Builder dialog box (shown in Figure 3). Dreamweaver has added the new text block and displays it in the text area at the top of the window. The default text for this block of text is displayed in the "code block" text area below it. The Insert Parameter in Code Block button and Insert Code pop-up menu are available and a Relative Position pop-up menu and Position text box are available (see Figure 4).

8. Whenever you use the server behavior, you must output the comment block. Copy the comment block listed in the article above to your clipboard and paste it into the Code Block text area, replacing the default text.

   Once the server behavior has inserted the text into documents into the code block text area, you must determine which text area(s) the user will determine dynamically by his/her input. In the page comment example, the application name, ColdFusion version, file name, section of the application, create date, purpose, and description will be dynamic. If the server behavior were intended for use in a single application, the application name would not be dynamic. The author name will not be dynamic because the author will always be you.

9. To flag the application name as dynamic, highlight the area where the user-supplied application name should be inserted; in this case, it's the text My Application (see Figure 5).

10. Selecting your dynamic region, click the Insert Parameter in Code Block button, assign the unique name appname to this region and click OK. After clicking OK, note that the text in the block is renamed to @@appname@@.
11. Repeat this process for all of the remaining regions you plan to make dynamic.

    Note: Be sure to give the regions the exact same names shown in Figure 7 below. Specifically, you need to use the names filename, appsection, and createdate for those respective parameter names. The names are case sensitive. Failure to name these correctly will cause errors in the form field auto-population JavaScript that I cover later in the article.

    Because this is a comment block that is supposed to be at the very top of a document, leave the Insert Code pop-up menu on its default value (Above the <html> tag) and change the Relative Position pop-up menu to The Beginning of the File.

12. Click Advanced to reveal a check box that tells Dreamweaver to identify this block of text in a document and display it in the Server Behaviors panel if present. (Be sure to select this check box if it isn't already.) Change "Code block to select" to the name of your code block. The dialog box now looks like Figure 6.

13. Figure 6. Ready to continue building the server behavior. Click Next to display Generate Behavior dialog box. Specify the User Interface to display for each of the dynamic regions of the text block that this server behavior inserts into a document. It contains a table with each of the parameter names along with its UI type displayed in a row. There are also up and down arrows for positioning the input parameters in the form window that will display when you run the server behavior. Selecting any row displays an arrow on the far right, in which you can assign a UI Type to the parameter, as shown in Figure 7.

The default UI Interface for parameters is Text Field, which is fine for all but the ColdFusion Version parameter. Technically, a text field would suffice for this parameter, but selecting the ColdFusion Version from a pop-up menu is more useful.

14. Click the cfversion entry in your table, click the arrow on the right, and select List Menu from the menu (see Figure 7). After you've assigned your desired UI Interface types to the parameters, click OK.
15. To test the new server behavior, click the plus (+) button on the server behaviors tab (refer back to Figure 1). There should now be a Page Comment entry in the menu.
16. Click the Page Comment menu entry to test the server behavior.

Dreamweaver displays a form for you to specify each parameter with one exception. The ColdFusion Version pop-up menu doesn't have any options aside from "***No values specified". The form itself may also need some cleaning up. This is OK. In addition to cleaning up the form and adding options to the select list, it would be useful to pre-fill the filename text box with the file name the user is currently editing, pre-fill the application section box with the path to the current document, and to pre-fill the create date text box with today's date (see Figure 8). You can do all of this with a little bit of HTML and JavaScript knowledge!

On Windows, the files that define a ColdFusion server behavior are stored in:

C:\Documents and Settings\Administrator\Application Data\Adobe\Dreamweaver CS4\en_US\Configuration\ServerBehaviors\ColdFusion

On Macintosh, the files are in:

Users/YOURUSERNAME/Library/Application Support/Adobe/Dreamweaver CS4/en_US/Configuration/ServerBehaviors/ColdFusion

There you will find an EDML file for the behavior, text block, and HTML file (Page Comment.htm in this example). The EDML files define which text block(s) are part of the behavior, which text block(s) layout(s) are, and where to position dynamic parameters. The HTML file defines the actual UI, which is what you want to modify. Use the following steps to do this:

1. Open Page Comment.htm in Dreamweaver or any other text editor. This file contains mostly JavaScript and the HTML for the form at the bottom.
2. Find the <select> tag for the ColdFusion versions, and delete the current option and add your own options, one for each ColdFusion Version you want to appear in the pop-up menu.
3. To default all of the values in the other form fields, change the <BODY> tag onload event value to: javascript:initializeUI();defaultFields();
4. Add the following JavaScript immediately following the first <SCRIPT> block on the page:

Without getting into too much of the nitty-gritty detail, this is some simple JavaScript to calculate and assign the default values for the text controls. One thing you'll notice is the use of a Dreamweaver object in the JavaScript. This is one of the objects added to the DOM that the Dreamweaver extension JavaScript has access to. You can learn much more about this DOM (and about extending Dreamweaver with other technologies) in the Dreamweaver API reference. You can also learn about server behaviors and other ways to extend Dreamweaver with the Extending Dreamweaver reference.

Where to go from here?

In addition to the references and utilities that come with Dreamweaver, with a little bit of research and practice, you can extend the Dreamweaver functionality pretty much any way you desire. You can even take your extensions and package them for distribution through the Adobe Dreamweaver Exchange. This requires very little work once you create the extension locally. Simply copy the EDML and HTML files for your extension to a separate directory and add a new file to that directory with an MXI extension. You can find MXI examples in the Adobe Extension Manager installation directory and you can also learn more about how to define the installation package in an MXI file here.

After creating the MXI file, which is really nothing more than a relatively simple XML file, double-click it, which launches the Extension Manager Compiler and click OK. The MXP file is then created and ready for you to distribute or to upload to the Dreamweaver Exchange. It's really not too difficult at all. Even if all this talk about JavaScript and HTML configuration files scares you, the truth is that the visual interface to the server behavior builder offers most of the functionality you need to create and use local Dreamweaver extensions, and it doesn't require any coding at all! There's really no excuse not to click around and try creating some behaviors yourself for a half-hour. Who knows, you may like it. You can't break anything… if you don't like a behavior you create, simply delete it with the Edit Server Behaviors option in the main Server Behaviors panel menu.