A simple toolbar command file

This simple example implements a Title text box item as seen on the Dreamweaver Document toolbar. The text box item lets the user enter a name for the current Dreamweaver document. You can implement this toolbar example by performing the following steps:

• Creating the text box
  
  
• Writing the JavaScript code
  
  

Creating the text box

To add a toolbar to Dreamweaver, you place an XML file that contains the toolbar definition in the Toolbars folder inside the Dreamweaver Configuration folder.

The following figure shows the Title text box:

The following toolbar editcontrol item defines a text box that is labeled Title:

 <EDITCONTROL    label="Title: "   tooltip="Document Title"   width="150"   file="Toolbars/MM/EditTitle.htm"/> 

The tooltip attribute causes Dreamweaver to display Document Title in a tooltip box when the user places the mouse pointer over the text box. The width attribute specifies the size of the field in pixels. The file attribute specifies that the EditTitle.htm file contains the JavaScript functions that operate on the text box. To see the full definition of the Dreamweaver Document toolbar, see the main toolbar () in the toolbars.xml file.

Writing the JavaScript code

When the user interacts with the text box, it causes Dreamweaver to invoke the EditTitle.htm command file in the Toolbars/MM folder. This file contains three JavaScript functions that operate on the Title text box. These functions are canAcceptCommand(), receiveArguments(), and getCurrentValue().

canAcceptCommand(): enable the toolbar item

The canAcceptCommand() function consists of one line of code that checks to see whether there is a current Document Object Model (DOM) and whether the document is parsed as HTML. The function returns the results of those tests. If the conditions are TRue, Dreamweaver enables the text box item on the toolbar. If the function returns the value false, Dreamweaver disables the item.

The function is as follows:

 function canAcceptCommand() {   return (dw.getDocumentDOM() != null && dw.getDocumentDOM().getParseMode() == 'html'); } 

receiveArguments(): set the title

Dreamweaver invokes the receiveArguments() function, shown in the following example, when the user enters a value in the Title text box and presses the Enter key or moves the focus away from the control.

The function is as follows:

 function receiveArguments(newTitle) {   var dom = dw.getDocumentDOM();   if (dom)     dom.setTitle(newTitle); } 

Dreamweaver passes newTitle, which is the value that the user enters, to the receiveArguments() function. The receiveArguments() function first checks to see whether a current DOM exists. If it does, the receiveArguments() function sets the new document title by passing newTitle to the dom.setTitle() function.

getCurrentValue(): get the title

Whenever an update cycle occurs, as determined by the default update frequency of the onEdit event handler, Dreamweaver calls the getCurrentValue() function to determine what value to display for the control. The default update frequency of the onEdit handler determines the update frequency because the Title text edit control has no update attribute.

For the Title text box, the following getCurrentValue() function calls the JavaScript application programming interface (API) function dom.getTitle() to obtain and return the current title.

The function is as follows:

 function getCurrentValue() {   var title = "";   var dom = dw.getDocumentDOM();    if (dom)     title = dom.getTitle();   return title; } 

Until the user enters a title for the document, the getTitle() function returns Untitled Document, which appears in the text box. After the user enters a title, the getTitle() function returns that value, and Dreamweaver displays it as the new document title.

To see the complete HTML file that contains the JavaScript functions for the Title text box, see the EditTitle.htm file in the Toolbars/MM folder.

The MM folder is reserved for Macromedia files. Create another folder inside the Toolbars folder, and place your JavaScript code in that folder.