API Functions for Mixing Extension Types


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 graphics/ccc.gif Automatic Alt Text command to run: <form name="myForm"> <input type="button" value="Insert ALT text" onClick="dw.runCommand('Automatic Alt Text. graphics/ccc.gif html')"> </form> //This objectTag() function, in the head of an graphics/ccc.gif object file, runs the Automatic Alt Text command when the user graphics/ccc.gif 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 graphics/ccc.gif file and called onLoad, accesses the Table.htm file in the graphics/ccc.gif Objects folder, and causes that file to run its objectTag( graphics/ccc.gif ) 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 graphics/ccc.gif user-specified text that already has the Set Page Properties graphics/ccc.gif behavior applied to it. <html> <head> <title>Insert Link to Change Page Properties</ graphics/ccc.gif title> <script language="JavaScript"> function objectTag() { linkname = document.myForm.linkname.value; myCall = dw.popupAction("Development/Set Page graphics/ccc.gif 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 graphics/ccc.gif file and called onLoad, inserts the Popup Message behavior graphics/ccc.gif into the user's document, with the function call attached graphics/ccc.gif to the currently selected item: function insertMyBehavior() { var myDOM = dw.getDocumentDOM(); myDOM.addBehavior("onClick","MM_popupMsg('Hello graphics/ccc.gif world')"); } //This objectTag() function, placed in an object graphics/ccc.gif file, inserts the Set Page Properties behavior with graphics/ccc.gif parameters set to black and white, and attaches the event graphics/ccc.gif handler to the selected object, when the user chooses the object graphics/ccc.gif 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( graphics/ccc.gif '#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 graphics/ccc.gif file and called onLoad, inserts a table into the user's graphics/ccc.gif document, and opens the Table Helper floating panel (as if graphics/ccc.gif the user had used the Table object and the Window > Table graphics/ccc.gif 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.



Dreamweaver MX Extensions
Dreamweaver MX Extensions
ISBN: 0735711828
EAN: 2147483647
Year: 2001
Pages: 141
Authors: Laura Gutman

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net