| The Dreamweaver API offers methods for invoking the functionality of almost all extension types from within other extensions. Take a look at these in the following sections, based on extension type. Running Commands Commands are the most flexible of the extension types, giving you access to every aspect of the user's document. Did you ever want to execute the code in a command file without the user having to choose the command from a menu? The API function that allows you to do this is dw.runCommand() . Table 8.1 lists the specifications for this function, and shows some examples of its use. Table 8.1. The dw.runCommand() Function Specifications | Function | dw.runCommand() | | Description | Executes the specified command. This function provides the capability to call a command from another extension file, exactly as if the user had chosen the command from a menu. | | Syntax | dw.runCommand( commandFile , [commandArg1, etc] ) | | Arguments | commandFile The name of a file in the Configuration/Commands folder. commandArg1 , and so onAny arguments that need to be passed to the command file. | | Returns | Nothing. | | Notes | Only items in the Commands folder can be accessed from this function. This means that dynamic menu commands (that is, those stored in Configuration/Menus) cannot be accessed using dw.runCommand() . | | Examples | //This code, in the body of a floater or property inspector, creates a button that causes the Automatic Alt Text command to run: <form name="myForm"> <input type="button" value="Insert ALT text" onClick="dw.runCommand('Automatic Alt Text. html')"> </form> //This objectTag() function, in the head of an object file, runs the Automatic Alt Text command when the user chooses the object from the objects panel: function objectTag() { dw.runCommand('Automatic Alt Text.html'); return ""; } | What can dw.runCommand() do for you? It lets you reuse the code that's already present in the Commands folder or create special command files and put them in the Commands folder specifically to be called on. Maybe you want to create an object that inserts Microsoft Word-generated HTML code into your document and then automatically cleans it up. Just use dw.runCommand() in your object file, passing it Clean Up Microsoft Word HTML.htm as an argument. note Note that dw.runCommand() works only on files actually in the Commands folder. This means menu commands (those stored in the Menus folder) aren't eligible. Inserting Objects Would you like your commands, behaviors, inspectors, or floaters to automatically insert objects? The API function that allows you to do this is dom.insertObject() . Table 8.2 lists the specifications for this function. Table 8.2. Specifications of the dom.insertObject() Function | Function | dom.insertObject() | | Description | Inserts a specified object into the user's document. This allows other extension types to insert object code into a document, as if the user had chosen the object from the Insert bar. | | Syntax | dom.insertObject( objectName ) | | Arguments | objectName The name of an object in the Configuration/Objects folder. This is the name of the object file minus its filename extension. No subfolder path (that is, Common/Table) need be included. | | Returns | Nothing. | | Example | //This function, placed in the head of a command file and called onLoad, accesses the Table.htm file in the Objects folder, and causes that file to run its objectTag( ) function: function insertMyTable() { var myDOM = dw.getDocumentDOM(); myDOM.insertObject("Table"); } | This function can be used any time we want Dreamweaver to respond as if the user had clicked on an icon in the Insert bar or chosen a command from the Insert menu. Commands, inspectors, and such may not be able to use the objectTag() function, but they can call on object files that use that function. With dom.insertObject() , we also have access to the functionality of all the standard objectsImage, Table, and so onfor exploitation in your extensions. Because we can even call dom.insertObject() from within another object file, we can create custom objects that build on standard Dreamweaver objects. Inserting Behaviors There are two API methods for inserting behaviors from other extensions, each with its own unique functionality: dw.popupAction() and dom.addBehavior() . The specifications for both of these methods are shown in Tables 8.3 and 8.4. Table 8.3. Specifications for the dw.popupAction() Function | Function | dw.popupAction() | | Description | Inserts a behavior, exactly as if the user had chosen the behavior from the + menu in the behaviors panel. This function can only be called from within objectTag() , or from any script within a command or inspector file. | | Syntax | dw.popupAction( actionName , [functionCall] ) | | Arguments | ActionName A string representing the name of a file in the Configuration/Behaviors/Actions folder that contains a JavaScript action. The filename must include the relative path from the Actions folder, including any subfolder names (for example, Development/Set Page Properties.html). [ functionCall ]A string representing the function call for the action specified in the previous parameter. This is the same code that would be returned by the applyBehavior() function if the behavior were chosen using the + menu (for example, "MM_popupMsg('Hello world')") . | | Returns | The function call for the behavior action (for example, MM_popupMsg('Hello world')) . | | Notes | When the user clicks OK to exit the behavior's dialog box, the function is added to the document, but not the function call. That value is returned. It must be added separately, and must be inserted into the user document separately (see the example below). | | Example | //This object file inserts a text link with user-specified text that already has the Set Page Properties behavior applied to it. <html> <head> <title>Insert Link to Change Page Properties</ title> <script language="JavaScript"> function objectTag() { linkname = document.myForm.linkname.value; myCall = dw.popupAction("Development/Set Page Properties.html"); returnString = '<a href="#" onClick="'+myCall+'">'+linkname+'<\/a>'; return returnString; } </script> </head> <body> <form name="myForm"> <input type="text" name="linkname"> </form> </body> </html> | Table 8.4. Specifications for the dom.addBehavior() Function | Function | dom.addBehavior() | | Description | Inserts a behavior into the user's document, but without calling up a dialog box; instead, any parameters must be set in the function itself. | | Syntax | dom.addBehavior( event, action, [ event-based index] ) | | Arguments | event A string representing the event handler to be used in creating the function call (for example, onClick) action A string representing the complete function call, as it would be returned from the applyBehavior() function if the user had chosen the behavior from the + menu (for example, MM_popupMsg('Hello world')) . [event-based index] A number indicating the position among other function calls that this one should take. If the selected object already has the specified event handler applied to it, but specifying a different function call, this determines the order in which the function calls are placed (for example, onClick="MM_popupMsg ('Hello world'); setProperties('#000000','#ffffff')") . This is a zero-based index. In the previous example, the Popup Message call would be index 0, and the Set Page Properties call would be index 1. If this argument is not present, the action is added after all other actions. | | Returns | Nothing. | | Examples | //This command, placed in the head of a command file and called onLoad, inserts the Popup Message behavior into the user's document, with the function call attached to the currently selected item: function insertMyBehavior() { var myDOM = dw.getDocumentDOM(); myDOM.addBehavior("onClick","MM_popupMsg('Hello world')"); } //This objectTag() function, placed in an object file, inserts the Set Page Properties behavior with parameters set to black and white, and attaches the event handler to the selected object, when the user chooses the object from the Insert bar: <html> <head> <title>Insert Page Properties</title> <script language="JavaScript"> function objectTag() { myDOM = dw.getDocumentDOM(); pagecolor = document.myForm.pagecolor.value; textcolor = document.myForm.textcolor.value; myDOM.addBehavior("onClick","setProperties( '#000000', '#FFFFFF') "); return ""; } | | Notes | Various commands are available to work with inserted behaviors. In the Extending Dreamweaver manual, check out dom.getBehavior() , dom.reapplyBehaviors() , dom.removeBehavior() , dw.getBehaviorElement() , and dw.getBehaviorTag() . | What's the difference between these two? Neither one completely re-creates the experience of a user choosing and configuring a behavior. With dom.addBehavior() , you can tell Dreamweaver to insert a behavior, but the standard behavior dialog box doesn't appear. Instead, your script must create the function call, with all of its arguments. If you want to ask for user input, you have to create your own <form> for processing input. With dw.popupAction() , you can tell Dreamweaver to call up the behavior's dialog box and create the function call, but this function does not cause the behavior function to be inserted in the document. You have to use other scripting to do that. Accessing Inspectors and Floaters Although there is no mimicking the functionality of an inspector or floater, you can use scripting to show and hide them. For this, you use the dw.setFloaterVisibility() API method (introduced in Chapter 7 "Creating Custom Floating Panels"). The specifications for this function are listed in Table 8.5. Table 8.5. Specifications for the dw.setFloaterVisibility() function. | Function | dw.setFloaterVisibility() | | Description | Opens or closes a floating panel or properties inspector, as if the user had chosen it from the Window menu to access it. | | Syntax | dw.setFloaterVisibility( floaterName , bIsVisible ) | | Arguments | FloaterName A string representing the name of the floating panel or inspector to be opened or closed. Built-in panels are accessed with these keywords: objects , properties , launcher , site files , site map , library , css styles , html styles , behaviors , timelines , html , layers , frames , templates , history . To access custom floaters, use the floater's name (filename minus extension). BIsVisible A Boolean value, indicating whether to open or close the specified floater or inspector. | | Returns | Nothing. | | Examples | //This function, placed in the head of a command file and called onLoad, inserts a table into the user's document, and opens the Table Helper floating panel (as if the user had used the Table object and the Window > Table Helper command): function insertMyTable() { var myDOM = dw.getDocumentDOM(); myDOM.insertObject("Table"); dw.setFloaterVisibility('TableHelper',true); } | With this and the other API methods described here, you can start programming the way Dreamweaver interface elements interact and share resources with each other. Your extension-writing skills won't be ready for prime time until you learn to go beyond individual extension types. |