| For our practice session, we'll play with some of the previous workshops to give the above functions a test drive. Task 1: Create an object that inserts Alt text To try out the dw.runCommand() method, copy the functionality of your Automatic Alt Text command (refer to Workshop #1 in Chapter 5, "Creating Custom Commands and Menu Commands") into an object, thus creating an Insert Alt Text object. -
Start by creating an HTML containing the basic framework code for an object file. The code should look like this: <html> <head> <title>Alt Text</title> <script language="JavaScript"> function objectTag() { return ""; } </script> </head> <body> </body> </html> The <title> , remember, will become the ToolTip for the Insert bar. The objectTag() function must be present and must have a return statement. The object doesn't need any <body> contentthat will be supplied by the command the object will run. -
Save the file in the Objects > Development folder you created back in Chapter 2, "Creating Custom Objects." Call it Alt Text.htm. -
To make sure the object displays properly in the Insert bar, open Insertbar.xml (in the Configuration/Objects folder) and add the following <button/> entry to your Development category: <button id="DW_Development_AltText" image="" enabled="" showIf="" file="Development\Alt Text.htm" /> -
Save insertbar.xml and close it. -
In the API procedure for object files, remember, the objectTag() function is called automatically. Its purpose is to return the chunk of HTML code to be inserted into the user 's document at the insertion point. For this object, you use objectTag() to call Automatic Alt Text.htm. Because you don't want it to actually insert any code at the insertion point, you have it return an empty string. To accomplish this, add the following code to your objectTag() function (new code is in bold): function objectTag() { dw.runCommand('Automatic Alt Text.htm'); return ""; } (Of course, if you called your Automatic Alt Text command file something else, use that name instead in your code. If you didn't complete the Automatic Alt Text project, you can download the finished project file at this book's companion web site.) -
In Dreamweaver, reload extensions and try it out. Open a file containing some images (and no Alt text) and then choose the Alt Text object. The command should run exactly as if you had chosen it from the Commands menu. Figure 8.1 shows the Alt Text object in action. Listing 8.1 shows the finished code for the Alt Text object file. Figure 8.1. The Alt Text object, calling the Automatic Alt Text command in a user document. Listing 8.1 Complete Code for Alt Text.htm, with Comments for Reference <html> <head> <!ToolTip> <title>Alt Text</title> <script language="JavaScript"> function objectTag() { //call any file in the Commands folder dw.runCommand('Automatic Alt Text.htm'); //return an empty string, so the object inserts no code return ""; } </script> </head> <body> <!the dialog box is provided by the command, so no body content is needed> </body> </html> Task 2: Create a command that inserts an object and opens a floating panel In this task, we'll create a command that inserts a table (just like choosing the Table object) and simultaneously opens the Table Helper floater (refer to Workshop #1 in Chapter 7. We'll use dom.insertObject() and dw.setFloaterVisibility() to do this. -
In your text editor, create a new HTML file, consisting of the basic framework code for a command: <html> <head> <title>Create Table</title> <script language="JavaScript"> function insertMyTable() { //command code goes here } </script> </head> <body onLoad="insertMyTable()"> </body> </html> -
Save the file in the Commands folder as Create Table.htm . -
For the command's main function, use the dom.insertObject() method to access the Dreamweaver Table object. Your function code should look like this: function insertMyTable() { var myDOM = dw.getDocumentDOM(); myDOM.insertObject("Table"); } Don't forget that dom.insertObject() must refer to the object's name, not its complete filename. Create the name by starting with the filename of the object file (Table.htm) and removing the filename extension. Also, because this function is a method of the DOM object, it doesn't work unless you access the DOM first. -
Next, add another statement to this same function to open the Table Helper floating panel. Revise your function code so it looks like this: function insertMyTable() { var myDOM = dw.getDocumentDOM(); myDOM.insertObject("Table"); dw.setFloaterVisibility("TableHelper", true); } Again, dw.setFloaterVisibility() must refer to the floater's name, which is generated from the floater file's filename minus its extension. (Obviously, if you didn't complete the Table Helper floating panel, you won't be able to perform this step as written. If this is the case, you can choose another floater to open.) -
That's all there is to it! In Dreamweaver, reload extensions and try the new command out in a new file. When you choose the command, the Insert Table dialog box should appear, exactly as if you had chosen this object from the Insert bar. When you have created your table, the Table Helper should automatically open to help you work with this table. Figure 8.2 shows the new Create Table command in action. Listing 8.2 shows the finished code for the Create Table command file. Figure 8.2. The Create Table object, inserting a table and opening the Table Helper floating panel. Listing 8.2 Complete Code for the Create Table.htm Command File, Commented for Reference <html> <head> <title>Create Table</title> <script language="JavaScript"> function insertMyTable() { var myDOM = dw.getDocumentDOM(); //duplicate functionality of Insert > Table command or object myDOM.insertObject("Table"); //duplicate functionality of Window > Table Helper dw.setFloaterVisibility("TableHelper", true); } </script> </head> <body onLoad="insertMyTable()"> </body> </html> Task 3: Make a floater updatable from outside itself The previous task may have started you wondering about another possibility in extension-writing. In that task, you automatically opened a floater from a command. But wouldn't it also be nice if the command could interact with the floater? In the case of the Create Table command, wouldn't it be nice if the command could insert a table, open the Table Helper floater, and then automatically generate a table diagram without the user having to click the form button? To perform tasks like this, you need to be able to access the floater's functions from outside the floaterin the case of the Create Table command, you need to call the displayDiagram() function from the Create Table command file. Unfortunately, you can't control floater files externally; but you can control command files externally, using dw.runCommand() . The solution, therefore, is to move the function that the floater normally executes displayDiagram() , in this caseto a command file of its own, and use dw.runCommand() to execute that command file from the floater or from anywhere else in the interface. The following steps take you through that process. -
To start with, create a new command file. Save it in the Configuration/ Commands folder as Table Helper Command.htm. Enter a basic code framework like this: <!MENU-LOCATION=NONE> <html> <head> <title>Table Helper Command</title> <script language="JavaScript"> function myCommand() { //command statements go here } </script> </head> <body onLoad="myCommand()"> </body> </html> This code creates a command with no dialog box (because the <body> is empty) and no menu entry (because of the opening comment line). -
Next, open the TableHelper.htm floater file. Select all command statements within the displayDiagram() function and Edit > Cut. In the place of this code, enter the following as your displayDiagram() code: function displayDiagram(){ dw.runCommand('Table Helper Command.htm'); } Save this file and close it. -
Now go back to the Table Helper Command.htm file, and Edit > Paste the original function code in between the curly braces of the myCommand() function. Make the following change to the code: function runCommand() { etc //move to floater var myConfig=dw.getConfigurationPath(); var myFloater=myConfig+"/Floaters/TableHelper.htm"; var floaterDOM = dw.getDocumentDOM( myFloater ); floaterDOM.body.innerHTML=emptyDOM.body.innerHTML; } What's this change for? Because the function is no longer being executed from within the floater file, you need to be more specific about identifying that file. -
Finally, open the Create Table.htm command file and add the following code, to control the floater externally: function insertMyTable() { var myDOM = dw.getDocumentDOM(); myDOM.insertObject("Table"); dw.setFloaterVisibility("TableHelper", true); dw.runCommand("TableHelper.htm"); } -
Now that you have all of your modules in place, you're ready to rock and roll! Quit Dreamweaver and relaunch (because you're updating a floater). Try using the Table Helper floater on a table you've already created. Then try the Create Table command. If everything is coded properly, this do-it-all-for-you command should now insert a table, open the Table Helper floater, and generate a table diagram. note You can find the code for this modularized version of the Table Helper floater on the book's companion web site at www.newriders.com Task 4: Create a floater that inserts a behavior For this task, you'll use a floating panel to insert a behavior. This involves creating the floater file and adding a corresponding <menuitem/> to menus .xml and adding a form button to the floater that calls the dom.addBehavior() function. -
Start by creating a floater file, with no special functions but including a form button in its layout. The code should look like this: <html> <head> <title>Add Behavior Floater</title> </head> <body> <form name="myForm"> <input type="button" value="Insert Behavior"> </form> </body> </html> -
Save this file in the Configuration/Floaters folder as AddPopup.htm. -
Next, add the menu item to hide and show this floater. Open menus.xml and find the <menuitem/> entries you created in previous chapters for Float Me and Table Helper. Immediately following those entries, add the following code: <menuitem name="Add Popup Behavior" enabled="true" command="dw.toggleFloater('AddPopup')" checked="dw.getFloaterVisibility('AddPopup')" id="MyStuff_AddPopup_Floater"/> -
Now experiment with the dom.addBehavior() API method by adding the following <script> tag to your floater file's <head> section: <script language="JavaScript"> function insertHelloMessage() { var myDOM = dw.getDocumentDOM(); myDOM.addBehavior("onClick", "MM_popupMsg('Hello world')"); } </script> This method adds a function and its function call into the user's document, without bringing up the behavior's dialog box. The code you've entered here inserts the Popup Message behavior, using the onClick event handler. (The dom.addBehavior() function must return the event handler and the function call, remember.) note Before you can insert a behavior using this command, obviously you need to know exactly what a valid function call for that behavior looks like. You may need to use a test file to insert the behavior the normal way and examine the code it creates before proceeding with your extension development. -
The function you just created is local (not part of the API procedure), so you need to call it when the user clicks the form button. Add the function call to your floater file's form button, like this: <form name="myForm"> <input type="button" value="Insert Behavior" onClick="insertHelloMessage()" > </form> -
Try out your floater. Remember that you need to quit Dreamweaver and relaunch it to get the new floater code to implement. Then create a test file to insert the behavior into, and enter a simple text link, like that shown in Figure 8.3. Figure 8.3. Using a simple floater to insert the Popup Message command. -
Select the text link, choose Window > Add Popup Behavior to open your floater, and click the Insert Behavior button. Your test document should look like the one shown in Figure 8.3. -
If you want to give the user a chance to customize the behavior as it's being inserted, you need to collect that information in the floater and feed it to dom.addBehavior() to be used in constructing the return statement. To try that out, in your text editor, add a text field to the floater file's <form> named message , like this: <form name="myForm"> <input type="text" name="message"> <input type="button" value="Insert Behavior"> </form> -
Then change your function to collect information from the text field and process it: 1 function insertHelloMessage() { 2 myDOM = dw.getDocumentDOM(); 3 var message = document.myForm.message.value; 4 message = message.replace(/'/g,"\'"); 5 myDOM.addBehavior("onClick","MM_popupMsg(' "+message+" ')"); 6 } What's happening here? In line 3, the message is collected from the form. Line 4 escapes any apostrophes the message might contain. Line 5 feeds the revised message into the addBehavior() function. -
Try out the revised floater. Your results should look like those shown in Figure 8.4. Figure 8.4. Floater that asks for user input, and uses it to create and insert the Popup Message behavior. Task 5: Create an object that inserts a behavior and some HTML code In this task, we'll create an object that inserts a text link into the user's document with the Set Page Properties behavior (or another behavior, if you like) already attached to it. To accomplish this, we'll use dw.PopupAction() . -
Create a new HTML file containing the basic object file framework: <html> <head> <title>Interactive Page Properties</title> <script language="JavaScript"> function objectTag() { return ""; } </script> </head> <body> </body> </html> -
Save this file in the Objects/Development folder as Interactive Page Properties.htm. -
To make sure the object displays properly in the Insert bar, open Insertbar.xml and add a <button/> entry to your Development category: <button id="DW_Development_PageProp" image="" enabled="" showIf="" file="Development\Interactive Page Properties.htm" /> -
The dw.popupAction() method only inserts the function code for the specified behavior, but it returns the proper function call. Therefore, your objectTag() function has to construct and return the event handler and function call using that returned information. To insert an unformatted piece of text that says Click here and contains the function call, revise your objectTag() function like this: function objectTag() { myCall = dw.popupAction("Development/Set Page Properties.htm"); returnString = '<a href="#" onClick="'+myCall+'">Click here<\/a>'; return returnString; } -
Try it out! Launch Dreamweaver and open a new document. From the Development category of the Insert bar, click your new Interactive Page Properties object and see what happens. -
If you want to give the user the chance to determine the text to be inserted, you need to add a simple form to your object file's <body> section: <body> <form name="myForm"> <input type="text" name="linkname"> </form> </body> And revise the objectTag() function to look like this: function objectTag() { linkname = document.myForm.linkname.value; myCall = dw.popupAction("Development/Set Page Properties.htm"); returnString = '<a href="#" onClick="'+myCall+'"> '+linkname+' <\/a>' return returnString; } -
Try out the new object. Your object should call up its own dialog box and then the behavior's dialog box. Your results should look like those shown in Figure 8.5. Figure 8.5. An object that inserts a text link already attached to a behavior. You may have noticed a problem that is common when you ask Dreamweaver to perform more than one extension task at a time, like this. If the user clicks Cancel in the object's dialog box (the first one that appears), the operation is completely canceled ; but if the user clicks Cancel from the behavior's dialog box, an incomplete portion of the intended code gets inserted. -
To address this, tweak the objectTag() function so it looks like this: function objectTag() { linkname = document.myForm.linkname.value; myCall = dw.popupAction("Development/Set Page Properties.htm"); if (myCall) { returnString = '<a href="#" onClick="'+myCall+'">'+linkname+'<\/a>'; }else{ returnString = ""; } return returnString; } There you go! Your object should now insert HTML code plus a behavior. The new behavior will even show up in the Behaviors panel after it's inserted, so the user can edit it from there. Can you see the difference between this sample, using dw.popupAction() , and the workings of the dom.addBehavior() method? The dom.addBehavior() method does not call up the behavior's own dialog box, so it requires you to assemble the function call yourself. The dw.popupAction() does call up the behavior's dialog box, but it still requires you to construct the exact function call as appropriate. |