All the code created by Dreamweaver is structured according to the current Tag Library settings. The Tag Library identifies which codes are indented and which are on their own lines, as well as numerous other specifications regarding HTML writing. Occasionally, a Web designer must work with Web pages created earlier, by other designers using other programs, or even by hand. The Apply Source Formatting and Apply Source Formatting to Selection commands can rewrite the original code — of an entire Web page or a selected part of the page, respectively — so that it is structured according to the current Tag Library settings. The more accustomed your eye is to following Dreamweaver-style HTML, the more you value this command.

The Apply Source Formatting and Apply Source Formatting to Selection commands are examples of Dreamweaver commands that don't display dialog boxes to gather the user's selected parameters — because there are no parameters to set. To invoke the commands, choose Commands

Dreamweaver tends to produce compact, uncluttered HTML/XHTML code, which is not always the case with other HTML/XHTML editors and hand-coded efforts. One of the most common problems is redundant <font> tags, which can result when you select some text, change the font, change the font size, and finally, change the font color. The resulting code is likely to resemble the following:

<font face="Arial"><font size="4"><font color="green">
  Bonanza!</font></font></font>

The Clean Up HTML and Clean Up XHTML commands are custom made to consolidate redundant tags and to remove some of the code clutter that can accumulate during a page's design. In all, you have seven different cleaning operations from which to choose. Note that the Clean Up HTML and Clean Up XHTML commands are applicable only to the current page and cannot be applied sitewide.

XHTML syntax is much less forgiving than HTML; your XHTML code must be nearly perfect to work correctly. The Clean Up XHTML command fixes XHTML code syntax errors, lowercases all tag attributes, and adds (or reports) missing required tag attributes.

To use the Clean Up HTML or Clean Up XHTML commands, follow these steps:

Dreamweaver performs the actions requested on the current document. If you select the Show Log option, an alert displays the changes made, if any.

Although many commands work with the entire HTML document, some require just a portion of text or an object that has been selected by the user. Although it seems a simple task, some quirks in the API make getting a selection a little tricky.

function testCase() {
  var theDom = dreamweaver.getDocumentDOM("document");
  var offsets = dreamweaver.getSelection();
  var theNode =
      dreamweaver.offsetsToNode(offsets[0],offsets[1]);
  var nodeText = theNode.data;
  alert(nodeText);
}

function lowerCase(){
  var theDom = dreamweaver.getDocumentDOM("document");
  var offsets = dreamweaver.getSelection();
  var theNode =
      dreamweaver.offsetsToNode(offsets[0],offsets[1]);
  if (theNode.nodeType == Node.TEXT_NODE) {
    var nodeOffsets = dreamweaver.nodeToOffsets(theNode);
    offsets[0] = offsets[0] - nodeOffsets[0];
    offsets[1] = offsets[1] - nodeOffsets[0];
    var nodeText = theNode.data;
    theNode.data = nodeText.substring(0,offsets[0]) +
      nodeText.substring(offsets[0],offsets[1]).toLowerCase()
      + nodeText.substring(offsets[1], nodeText.length);
    window.close();
  }
  else { //it's not a TEXT_NODE
    var nodeOffsets = dreamweaver.nodeToOffsets(theNode);
    offsets[0] = offsets[0] - nodeOffsets[0];
    offsets[1] = offsets[1] - nodeOffsets[0];
    var nodeText = theNode.innerHTML;
    theNode.innerHTML = nodeText.toLowerCase();
    window.close();
  }
}

function replicate() {
  var theDom = dreamweaver.getDocumentDOM("document");
  var offsets = dreamweaver.getSelection();
  var selObj =
      dreamweaver.offsetsToNode(offsets[0],offsets[1]);
  if (selObj.nodeType == Node.TEXT_NODE) {
    helpMe2();
    window.close();
    return;
  }
  var theCode = selObj.outerHTML;
}

Commands offer a tremendous range of power and can perform actions not available to behaviors or objects. To take advantage of this power with a point-and-click interface, it's best to disguise the command as an object. As an object, the command appears in both the Insert panel and the Insert menu.

A Dreamweaver object usually consists of two files: an HTML file for the code and a GIF image for the button, all in the Dreamweaver CS5ConfigurationObjectsCategory folder. (The value of Category is the name of the folder that corresponds to the Insert panel category in which the object resides.) When using a command as an object, however, you can have as many as five files split between the Dreamweaver CS5ConfigurationObjectsCategory and Dreamweaver CS5ConfigurationCommands folders. The standard Rollover object is a good example: three associated rollover files are in the Dreamweaver CS5ConfigurationObjectsCommon folder, and two are in the Commands folder. (The Dreamweaver CS5ConfigurationObjectsCommon subfolder alerts you to the fact that the Rollover object resides in the Common category of the Insert panel.) Here is how these rollover files are used:

The key to understanding how to use a command as an object is the code linking the two types of extensions. In the Dreamweaver CS5ConfigurationObjectsCommonRollover.js file is the objectTag(), which is used to write an object into an existing Web page with its return value. In this case, the function first gets the Document Object Model of the relevant command file (Dreamweaver CS5ConfigurationCommandsRollover.htm); this procedure enables the current function to reference any variable set in the other file. Then the popupCommand is executed, which runs Dreamweaver CS5ConfigurationCommandsRollover.htm — which, in turn, launches the dialog box and gets the user parameters. Finally, a result from that command is set to the return value of objectTag() and written into the HTML page. Here's the objectTag() function in its entirety from Dreamweaver CS5ConfigurationObjectsCommonRollover.js:

function objectTag() {
  var rolloverTag = callCommand("Rollover.htm");
  if (rolloverTag) { //if inserting call, update behavior funcs as needed
  updateBehaviorFns("MM_findObj","MM_swapImgRestore",                                    "MM_preloadImages","MM_swapImage");
  }
  else {
    rolloverTag = '';
  }
  return(rolloverTag);
}

Some custom commands disguised as objects make the DOM connection in the command file rather than in the object file. All iCat objects (written to integrate a shopping cart into Dreamweaver), for example, establish the link in the primary functions of their command JavaScript files, in the following manner:

var dom = dreamweaver.getDocumentDOM("../Objects/iCat/Add To Cart.htm");
dom.parentWindow.icatTagStr = icatTagStr;

Then, the corresponding objectTag() function simply returns the icatTagStr variable.

It's relatively straightforward to insert text wherever the cursor has been set in the document — you just set a text string equal to the [innerHTML | data] property of the DOM at that point. But how do you insert code in the <head> section of a Web page, where you don't generally find the cursor? Certain code, such as <script> tags that hold extensive JavaScript functions, must be inserted in the <head>. By design, behaviors return code specifically intended for the <script> tag — except you can't easily use a behavior to include a line such as the following:

<script language="Javascript" src="extend.js"></script>

You can insert such a line with commands, however. This technique, developed by Dreamweaver extensions author Massimo Foti, shows the way.

Unfortunately, no equivalent to the body property exists in the Dreamweaver DOM for the <head> section. The way around this minor limitation is to first locate the sole <head> tag in the document. You can accomplish this task in two lines of JavaScript code:

theDom = dreamweaver.getDocumentDOM("document");
theHeadNode = theDom.getElementsByTagName("HEAD");

Now the script variable needs to be set. Whenever Dreamweaver encounters a closing </script> tag in a JavaScript function, the tag is flagged because it seems to be missing a mate. To avoid this problem, split the tag into two concatenated strings, as follows:

theScript = '<script language="Javascript" src="extend.js"><' + '/script>';

Finally, find the first item in the <head> section and append the script to its innerHTML property:

theHeadNode.item(0).innerHTML = theHeadNode.item(0).innerHTML + theScript;

The full function looks like the following:

function insertScript() {
  var theDom, theHeadNode, theScript;
  theDom = dreamweaver.getDocumentDOM("document");
  theHeadNode = theDom.getElementsByTagName("HEAD");
  theScript = '<script language="Javascript" src="extend.js">< ' + 'script>';
}

As you've seen, the runCommand() function plays a key role in scripting commands. It's worth emphasizing that this same function is used when you want one command to invoke another command. The proper syntax is:

var doNew = dw.runCommand("commandFileName");

where commandFileName is the name of an HTML file in the Dreamweaver CS5ConfigurationCommands folder. No value is returned with runCommand(); the function executes whatever command is called, passing any optional arguments. The function takes the following format:

dreamweaver.runCommand("myCommand.htm","argument01","argument02");

The called command's dialog box is presented and must be completed or canceled before the originating command can continue.

<!-- MENU-LOCATION=NONE-->

Commands aren't limited to working on the current document — you can use a command to read, modify, and even create new files. Any new file created using createDocument() or createXHTMLDocument() is an HTML or XHTML page based on the Default.html or Default.xhtml file found in the Dreamweaver CS5ConfigurationDocumentTypesNewDocuments folder.

Occasionally, however, a command must make a new non-HTML/XHTML document, such as an XML or SMIL file or other file type that doesn't use the <html>...</html> structure. To accomplish this task, you first create an HTML file and then replace its entire contents with your own data — or nothing at all. The following custom function, developed by Andrew Wooldridge, makes and saves a new, blank text file:

function doNew() {
  var newDOM = dreamweaver.createDocument();
  var theDoc = newDOM.documentElement;
  theDoc.outerHTML = ".";
  theDoc.innerHTML = " ";
  dreamweaver.saveDocument(newDOM, '../../empty.txt'),
}

Remember that all of the Dreamweaver document functions — such as saveDocument() — use addresses relative to the file calling them. For example, if the doNew() function is included in a command and, therefore, stored in the Commands folder, the empty.txt document is saved two folders above the Commands folder in the Dreamweaver root directory because the full path to it is Dreamweaver CS5ConfigurationCommands.

Although Dreamweaver now provides a user interface for editing the keyboard shortcuts, sometimes power users must go to the source for major modifications — and the source for shortcuts is menus.xml. The menus.xml file is divided into two main sections: <shortcutlist> and <menubar>. The <shortcutlist> divisions are, as you might suspect, a list of keyboard shortcuts. The <menubar> areas are concerned with the various menu bars — in the main Document window, in the Site panel (Windows only), and in the numerous context menus. <shortcutlist> and <menubar> share several characteristics. They both follow the same basic structure:

<shortcutlist id="shortcutListID" [platform="win|mac"]>
  <shortcut attributeName="value" attributeName="value" ... />
  <shortcut attributeName="value" attributeName="value" ... />
  other shortcut items...
</shortcutlist>
 <menubar name="menubarname" id="menubarID" [platform="win|mac"]>
  <menu name="menuname" id="menuID">
    <menuitem attributeName="value" attributeName="value" ... />
    <menuitem attributeName="value" attributeName="value" ... />
    other menuitem items...
  </menu>
  other menu items...
</menubar>

Shortcuts for menu items are primarily defined within the <menubar> code; the <shortcutlist> is mainly concerned with those shortcuts that do not have a menu item associated with them, such as moving from one word to another. By default, Dreamweaver defines six <shortcutlist> sections: DWMainWindow for the Document window menu, DWMainSite for the Site panel menu (Windows only), DWHTMLContext for the Code inspector/Code view context menu, DWServerBehaviorContext for the Server Behaviors panel context menu, DWDataBindingContext for the Bindings panel context menu, and DWServerComponentContext for the Components panel context menu.

Each <shortcutlist> tag has one required attribute, the ID. The ID refers to a specific window or panel and must be unique within the <shortcutlist> section. The same ID is repeated in the <menubar> section to refer to the same window or panel. For example, the Document window ID is DWMainWindow, whereas the one for the context menu of the Server Behaviors panel is DWServerBehaviorContext. The <shortcutlist> tag takes one optional attribute, platform, which must be set to either win or mac, for Windows and Macintosh systems, respectively. (Note that in syntax statements, optional attributes are enclosed in brackets.) If no platform attribute is listed, the <shortcutlist> described applies to both platforms. Here, for example, is the beginning of the <shortcutlist> definition for the Files panel, which only appears in the Windows version of the software:

<shortcutlist id="DWMainSite" platform="win">

A separate <shortcut> tag exists for every keystroke defined in the <shortcutlist>. The <shortcut> tag defines the key used, the tag's ID, the command or file to be executed when the keyboard shortcut is pressed, and the applicable platform, if any. Shortcuts can be defined for single special keys or key combinations using modifiers. The special keys are as follows:

Modifiers can be used in combination with standard keys, with special keys, or by themselves. A combination keyboard shortcut is indicated with a plus sign between keys. Available modifiers include those described in Table 33-1.

You can also combine multiple modifiers, as in Command+Shift+Z.

The format of the <shortcut> tag is identical to that of the <menuitem> tag, as described in the following section.

Each <menubar> section of the menus.xml file describes a different menu strip, either on a window or on the context menu associated with a panel. Nested within the <menubar> tag is a series of <menu> tags, each detailing a drop-down menu. The individual menu items are defined in the <menuitem> tags contained within each set of <menu>...</menu> tags. Here, for example, is the context menu for the HTML Styles panel (I've abbreviated the complete <menuitem> tag for clarity):

<menubar name="" id="DWHtmlStyleContext">
  <menu name="HTML Style Popup" id="DWContext_HTMLStyle">
    <menuitem name="Edit..." />
    <menuitem name="Duplicate..." />
    <menuitem name="Delete" />
    <menuitem name="Apply" />
    <separator />
    <menuitem name="New..." />
  </menu>
</menubar>

The <menubar> and <menu> tags are alike in that they both require a name — which is what appears in the menu system — and an ID. The ID must be unique within the <menubar> structure to avoid conflicts. If a conflict is found (that is, if one item has the same ID as another), the first item in the XML file is recognized, and the second item is ignored.

Numerous other attributes exist for the <menuitem> tag. The required attributes are name, id, and either file or command, as marked with an asterisk in Table 33-2.

You can create submenus by nesting one set of <menu> tags within another. The following example is a simplified look at the File

<menu name="_File" id="DWMenu_File">
  other menu items...
  <menu name="_Import" id="DWMenu_File_Import">
    <menuitem name="_XML into Template..." />
    <menuitem name="_Word HTML..." />
    <menuitem name="_Tabular Data..." />
  </menu>
  other menu items...
</menu>

Note how the <menu> tag defining the Import submenu is nested within the <menu> tag that defines the File menu.

Two main items define a custom Property inspector:

More than one Property inspector can be defined for a particular tag, making it possible for separate inspectors to be used if different attributes are specified. Therefore, each Property inspector is assigned a priority that determines the one to be displayed. Property inspectors are further defined by whether the current selection is within the tag indicated or if it contains the entire tag; this feature enables two different Property inspectors to be defined, as with the <table> tag. Finally, optional graphic elements are definable: a horizontal line to delineate the upper and lower portions of the Property inspector, and a vertical line to separate the object's name from the other parts of the Property inspector.

Here is the custom Property inspector DTD:

<!DOCTYPE HTML SYSTEM "-//Adobe//DWExtension
  layout-engine 6.0//pi">

The HTML comment line uses the following syntax:

<!-- tag:ID,priority:1-10,
  selection:exact|within,hline,vline,serverModel-->

(The last three values of the selection attribute — hline, vline, and serverModel — are all optional.) For example, the Property inspector for the <link> tag (a <head> element) is defined as follows:

<!-- tag:LINK,priority:5,selection:within,vline,hline-->

The individual sections of the definition are as follows:

Figure 33-6. The Property inspector for the <img> tag uses both the hline and vline attributes.

To control the circumstances under which your custom Property inspector is displayed, use the canInspectSelection() function. Like canAcceptBehavior() and canAcceptCommand() for behaviors and commands, respectively, if canInspectSelection() returns true, the custom Property inspector is shown; if it returns false, the Property inspector is not shown.

As noted earlier, the canInspectSelection() function is mandatory. If no conditions exist under which the Property inspector should not be displayed, use the following code:

function canInspectSelection() {
  return true;
}

Access to several of the standard Dreamweaver <head> elements' Property inspector files is restricted by the canInspectSelection() function to specific tags. In the following example, from the <meta> Description object, the current selection is examined to see if a <meta> tag is selected, and the name attribute is set to description:

function canInspectSelection() {
  var dom = dw.getDocumentDOM();
  var metaObj = dom.getSelectedNode();
  if (!metaObj || !metaObj.getAttribute) return false;
  return (metaObj.tagName && metaObj.tagName == "META" &&
   metaObj.getTranslatedAttribute("name") &&
   metaObj.getTranslatedAttribute("name").toLowerCase()=="description");
}

The inspectSelection() function is the workhorse of the custom Property inspector code and is responsible for pulling the information from the selected tag for display in the various Property inspector fields. Depending on the code design, the inspectSelection() function can also be used to update the HTML code when the attribute values are modified in the Property inspector.

Here's an excerpt of the inspectSelection() function from the Link Property inspector file:

function inspectSelection() {
  TEXT_HREF = findObject("Href");
  ...
  if (linkObj.getAttribute("href"))
    TEXT_HREF.value = linkObj.getAttribute("href");
  else
    TEXT_HREF.value = "";
  ...
}

In this example, if an attribute (href) exists, its value is assigned to the Property inspector's appropriate text box value (TEXT_HREF.value). The remainder of the inspectSelection() function for the <link> tag consists of a series of statements such as those shown in the sample code.

Many Property inspectors update their HTML tags when a change occurs in one of the input boxes. No real standard method exists to accomplish this because there are so the many possible variations with Property inspectors. However, one of the most commonly used events is onBlur(), as in the following example, taken from the Keywords Property inspector file:

var minText = '<textarea name="Keywords" onBlur="setMetaTag()" '
  + 'style="width:350;height:32" rows="2" wrap="virtual"></textarea>'

The setMetaTag() function that is called is a local one that assigns whatever is currently in the textarea of the Property inspector to the content attribute.

The getTranslatorInfo() function simply sets up and returns an array of text strings that are read by Dreamweaver during initialization.

The structure of the array is relatively rigid. The number of array elements is specified when the Array variable is declared, and a particular text string must correspond to the proper array element. The array order is as follows:

The number of array elements — and thus, the detail of the function — depends entirely on the translator. Here, for example, is the code for getTranslatorInfo() from Live Picture's translator, where a file must have a particular <meta> tag to be translated:

function getTranslatorInfo(){
  returnArray = new Array( 5 );
  returnArray[0] = "FPX";     // translatorClass
  returnArray[1] = "Flashpix Image Translator";     // title
  returnArray[2] = "0";       // number of extensions
  returnArray[3] = "1";       // number of expressions
  returnArray[4] = "<meta http-equiv="refresh" content="0;url=http://";
  return returnArray;
}

By comparison, the standard SSI translator's getTranslatorInfo() function has 10 array elements, and Webmonkey's XSSI has 17.

Although the getTranslatorInfo() function initializes the translator, the translateMarkup() function actually does the work. As noted earlier, most translators rely on a custom C-level extension to handle the inner workings of the function, but translateMarkup() provides the JavaScript shell.

The translateMarkup() function takes three arguments, which must be declared, but whose actual values are provided by Dreamweaver:

Typically, the docContent text string is parsed using either JavaScript or a C-level extension within the translateMarkup() function that returns the translated document. Dreamweaver then displays this translated document.

Here's an excerpt of the translateMarkup() function from the ColdFusion translator:

function translateMarkup(docNameStr, siteRootStr, inStr) {
  var outStr = "";
  ...
  // translate
  if (inStr.indexOf("<cf") != −1 || inStr.indexOf("<CF") != −1) {
    var TM =
      new TranslationManager(TRANSLATOR_CLASS, SERVER_MODEL_FOLDER, "");
    TM.serverModelAlwaysCheckTag = myAlwaysCheckTag;
    TM.serverModelAlwaysCheckAttribute = myAlwaysCheckAttribute;

var split = TranslationManager.splitBody(inStr);
    outStr = TM.translate(split.inStr);
    if (outStr != "")
      outStr = split.preInStr + outStr + split.postInStr;
  }
  ...
  return outStr;
}

In this example, notice that the translated document in the form of outStr is built by creating a TranslationManager object named TM and then calling this object's translate() method: TM.translate(split.inStr).