A simple command example | Developing Extensions for Macromedia Dreamweaver 8

< Day Day Up >

This simple extension adds an item to the Commands menu and lets you convert selected text in your document to either uppercase or lowercase. When you click the menu item, it activates a three-button interface that lets you submit your choice.

You create this extension by performing the following steps:

Creating the UI
Writing the JavaScript code
Testing the extension

This example creates two files in the Commands folder: Change Case.htm, which contains the UI, and Change Case.js, which contains the JavaScript code. If you prefer, you can create only the Change Case.htm file and put the JavaScript code in the HEAD section.

Creating the UI

The UI is a form that contains two radio buttons that let the user select uppercase or lowercase.

To create the user interface:

Create a new blank file.

Add the following code to the file to create the form:

 <!DOCTYPE HTML SYSTEM "-//Macromedia//DWExtension layout-engine 5.0//dialog"> <HTML> <HEAD> <!-- Copyright 2001-2002 Macromedia, Inc. All rights reserved. --> <Title>Make Uppercase or Lowercase</Title> <SCRIPT src="/books/4/533/1/html/2/Change Selection Case.js"></SCRIPT> </HEAD> <BODY>  <form name="uorl">   <table border="0">     <!--DWLayoutTable-->     <tr>       <td valign="top" nowrap> <p>           <label>           <input type="radio" name="RadioGroup1" value="uppercase" checked>           Uppercase</label>           <br>           <label>           <input type="radio" name="RadioGroup1" value="lowercase">           Lowercase</label>         </p></td>     </tr>   </table>   </div> </form> </BODY> </HTML>

Save the file as Change Case.htm in the Configuration/Commands folder.

The contents of the Title tag, Make Uppercase or Lowercase, appears in the top bar of the dialog box. Within the form, a table with two cells controls the layout of the elements. Within the table cells are the two radio buttons, Uppercase and Lowercase. The Uppercase button has the checked attribute, making it the default selection and ensuring that the user must either select one of the two buttons or cancel the command.

The form looks like the following figure.

The commandButtons() function supplies the OK and Cancel buttons that let the user submit the choice or cancel the operation.

Writing the JavaScript code

The following example consists of two extension API functions, canAcceptCommand() and commandButtons(), which Dreamweaver calls, and one user-defined function, changeCase(), which is called from the commandButtons() function.

In this example, you will write JavaScript to perform the following tasks:

Determining whether the command should be enabled or dimmed
Linking functions to the OK and Cancel buttons
Letting the user specify uppercase or lowercase

Determining whether the command should be enabled or dimmed

The first task in creating a command is to determine when the item should be active and when it should be dimmed. When a user clicks the Commands menu, Dreamweaver calls the canAcceptCommand() function for each menu item to determine whether it should be enabled. If canAcceptCommand() returns the value TRue, Dreamweaver displays the menu item text as active or enabled. If canAcceptCommand() returns the value false, Dreamweaver dims the menu item. In this example, the menu item is active when the user has selected text in the document.

To determine whether the command should be active or dimmed:

Create a new blank file.

Add the following code:


 function canAcceptCommand(){   var theDOM = dw.getDocumentDOM(); // Get the DOM of the current document   var theSel = theDOM.getSelection(); // Get start and end of selection   var theSelNode = theDOM.getSelectedNode(); // Get the selected node   var theChildren = theSelNode.childNodes; // Get children of selected node   return (theSel[0] != theSel[1] && (theSelNode.nodeType == Node.TEXT_NODE || theSelNode .hasChildNodes() && (theChildren[0].nodeType == Node.TEXT_NODE))); }

Save the file as Change Case.js in the Configuration/Commands folder.

The first lines of the canAcceptCommand() function retrieve the selected text by retrieving the DOM for the user's document and calling the getSelection() function on the document object. Next, the function retrieves the node that contains the selected text, followed by any children of the node, as shown in the following code. Then, the last line checks to see if the selection or its first child is text and returns the result as a value of TRue or false.

The first part of the return statement (theSel[0] != theSel[1]) checks if the user has selected anything in the document. The variable theSel is a two-slot array that holds the beginning and ending offsets of the selection within the document. If the two values are not equal, content has been selected. If the values in the two slots are equal, there is only an insertion point and nothing has been selected.

The next part of the return statement (&& (theSelNode.nodeType == Node.TEXT_NODE) checks to see if the selected node type is text. If so, the canAcceptCommand() function returns the value TRue. If the node type is not text, the test continues to see if the node has children (|| theSelNode.hasChildNodes()), and if the type of the first child node is text (&& (theChildren[0].nodeType == Node.TEXT_NODE))). If both conditions are true, canAcceptCommand() returns the value TRue, and Dreamweaver enables the menu item at the bottom of the Commands menu, as shown in the following figure:

Otherwise, canAcceptCommand() returns the value false and Dreamweaver dims the item, as shown in the following figure:

Linking functions to the OK and Cancel buttons

When the user clicks OK or Cancel, the extension needs to perform the appropriate action. You determine the appropriate action by specifying which JavaScript function to perform when either button is clicked.

To link the OK and Cancel button to functions:

Open the file Change Case.js in the Configuration/Commands folder.

At the end of the file, add the following code:

 function commandButtons() {   return new Array("OK", "changeCase()", "Cancel", "window.close()"); }

Save the file.

The commandButtons() function causes Dreamweaver to supply the OK and Cancel buttons and tells Dreamweaver what to do when the user clicks them. The commandButtons() function tells Dreamweaver to call changeCase() when the user clicks OK and to call window.close() when the user clicks Cancel.

Letting the user specify uppercase or lowercase

When the user clicks a menu item, the extension needs a mechanism to let the user select uppercase or lowercase. The UI provides this mechanism by defining two radio buttons to let the user make that choice.

To let the user specify uppercase or lowercase:

Open the file Change Case.js.

At the end of the file, add the following code:

 function changeCase() {   var uorl;   // Check whether user requested uppercase or lowercase.   if (document.forms[0].elements[0].checked)     uorl = 'u';   else     uorl = 'l';   // Get the DOM.   var theDOM = dw.getDocumentDOM();   // Get the outerHTML of the HTML tag (the   // entire contents of the document).   var theDocEl = theDOM.documentElement;   var theWholeDoc = theDocEl.outerHTML;   // Get the node that contains the selection.   var theSelNode = theDOM.getSelectedNode();   // Get the children of the selected node.   var theChildren = theSelNode.childNodes;   var i = 0;   if (theSelNode.hasChildNodes()){     while (i < theChildren.length){       if (theChildren[i].nodeType == Node.TEXT_NODE){         var selText = theChildren[i].data;         var theSel = theDOM.nodeToOffsets(theChildren[0]);         break;       }       ++i;     }   }   else {   // Get the offsets of the selection   var theSel = theDOM.getSelection();   // Extract the selection   var selText = theWholeDoc.substring(theSel[0],theSel[1]); } if (uorl == 'u'){     theDocEl.outerHTML = theWholeDoc.substring(0,theSel[0]) +     selText.toUpperCase() + theWholeDoc.substring(theSel[1]);   }   else {     theDocEl.outerHTML = theWholeDoc.substring(0,theSel[0]) +     selText.toLowerCase() + theWholeDoc.substring(theSel[1]);   } // Set the selection back to where it was when you started   theDOM.setSelection(theSel[0],theSel[1]);   window.close(); // close extension UI }

Save the file as Change Case.js in the Configuration/Commands folder.

The changeCase() function is a user-defined function that is called by the commandButtons() function when the user clicks OK. This function changes the selected text to uppercase or lowercase. Because the UI uses radio buttons, the code can rely on one choice or the other being checked; it does not need to test for the possibility that the user makes neither choice.

The changeCase() function first tests the property document.forms[0].elements[0].checked. The document.forms[0].elements[0] property refers to the first element in the first form of the current document object, which is the UI for the extension. The checked property has the value true if the element is checked (or enabled) and false if it is not. In the interface, elements[0] refers to the first radio button, which is the Uppercase button. Because one of the radio buttons is always checked when the user clicks OK, the code assumes that if the choice is not uppercase, it must be lowercase. The function sets the variable uorl to "u" or "l" to store the user's response.

The remaining code in the function retrieves the selected text, converts it to the specified case, and copies it back in place in the document.

To retrieve the selected text for the user's document, the function gets the DOM. It then gets the root element of the document, which is the html tag. Finally, it extracts the whole document into the theWholeDoc variable.

Next, changeCase() calls getSelectedNode() to retrieve the node that contains the selected text. It also retrieves any child nodes (theSelNode.childNodes) in case the selection is a tag that contains text, such as <b>text</b>.

If there are child nodes (hasChildNodes() returns the value true), the command loops through the children looking for a text node. If one is found, the text (theChildren[i].data) is stored in selText, and the offsets of the text node are stored in theSel.

If there are no child nodes, the command calls getSelection() and stores the beginning and ending offsets of the selection in theSel. It then extracts the string between those two offsets and stores it in selText.

The function then checks the uorl variable to determine whether the user selected uppercase. If so, the function writes the HTML code back to the document in sections: first, the beginning of the document to the beginning of the selection; then the selected text, converting it to uppercase (selText.toUppercase()); and last, the end of the selected text to the end of the document.

If the user selects lowercase, the function performs the same operation, but calls selText.toLowerCase() to convert the selected text to lowercase.

Finally, changeCase() resets the selection and calls window.close() to close the UI.

Testing the extension

After you place the files in the Commands folder, you can test the extension.

To test the extension:

1.	Restart Dreamweaver or reload extensions. For information on reloading extensions, see "Reloading extensions" on page 104. The Change Case entry should now appear on the Commands menu.
2.	Type some text in a document.
3.	Select the text. NOTE Change Case is dimmed until the user selects text in the document.
4.	Select Change Case from the Commands menu. The text changes case.

< Day Day Up >