Automated Import to Template

Again, we're faced with a powerful command that does exactly what we wantexcept that it does it with only one document at a time. What's clearly needed here is a parallel to the Export XML extensionone that permits the same choices in scope (current document, open documents, selected files in site panel, or entire site) and stores all the HTML documents generated from importing XML files in a single folder. Constructing this extension takes even less time because much of the work (looping through the selected files, for example) has already been done once before. A key point to take away from this sectionaside from how to build the functionis how you can leverage work in one extension to make another.

NOTE

The approach described in this section is not the only way to combine data and templates to create new pages. To see how you can generate HTML pages directly from a data source, look at Chapter 5, "Automating Static Page Production from a Data Source."

NOTE

To View the completed code, see Listing 4-4 at the end of this section.

Let's start by defining how we expect the new extension, Import XML, to work:

1. From the Extension dialog box, the user selects which XML files should be included in the operation.

2. The user also selects a folder to store the generated pages.

3. When the command executes, the program gathers the URL of each XML file.

4. The URL is passed to a function that first creates a blank document to hold the template instance and then imports the XML data.

5. The new file is saved and closedand the next XML file, if any, is processed .

TIP

Remember that Dreamweaver MX now supports multiuser configurations. If you are working with a multiuser-compatible OS (such as Windows 2000 or Mac OS X), the custom extensions need to be saved in the appropriate user/Macromedia/ Dreamweaver MX/ Configuration folder. Extensions for single-user systems are stored in the Programs/Macromedia/ Dreamweaver MX/ Configuration folder (Windows) or in the Applications:Macromedia: Dreamweaver MX: Configuration folder (Macintosh).

The process and the Import XML extension are pretty straightforward. Best of all, we have a starting point to jump off from: the Export XML extension. In a situation like this where so much is duplicated from one extension to the next, I typically open the original extension and do a File, Save As to create a new extension. I save the new file in the appropriate Configuration folder; in this case, that would be Commands.

Next, I change the title of the extension. The title is displayed in the title bar of the Extension dialog box. Changing the title is a small thing, but I often forget to do it if I don't do it right away. Now we can begin to seriously modify the base extension, starting with the user interface. In this case, we'll take away an element found in Export XML that is not needed in Import XML: the Template drop-down list. For this version of Import XML, it is assumed that all the XML files declared their associated template. Why? The primary reason is that the key API function we will be using, dw.importXMLIntoTemplate() , requires it. It also greatly simplifies our coding.

With the Template drop-down list and its label deleted, the Import XML extension (see Figure 4.4) is ready for user input.

Figure 4.4. Why rebuild when you can duplicate? The Import XML extension is a duplicate of Export XML with one user interface element removed.

I need to make only one small change to code within the doCommand() function of Import XML. In the Export XML extension, the Wildcards variable was set to allow almost every type of Web document extension: .htm, .html, .shtm, .shtml, .asp, .cfm, .cfml, .php, and .php3. For the Import XML extension, the selection needs to be limited to just one file type: .xml.

As before, the main function is separated from the code that takes the user's selection of which files to be processed. Here, that function is named importXML() , whereas in the original extension, it was named exportXML() . Because the user selection code calls the function for each choice of scope potentially made, the easiest way to modify the code is to do a find and replace.

The first line in the importXML() function serves to create a new, blank document:

 var theTempDOM = dw.createDocument(); 

If this is not done, the template instance is loaded onto the current document.

The next bit of code represents one of the real pitfalls of extension programming: incorrect documentation. According to the Extending Dreamweaver manual, the importXMLIntoTemplate() function takes a file URL as its only argument. Unfortunately, that's wrong. Although it does take a URL pointing to an XML file, the string should be formatted as a file path , like this:

 D:\fp2dw\newTemp\anotherTest.xml 

instead of a file URL, like this:

 file:///D/fp2dw/newTemp/anotherTest.xml 

Dreamweaver provides a function in the MMNotes API collection that converts a file URL to a file path. We can use that without including any other JavaScript file:

 var theNewURL = MMNotes.localURLToFilePath(theURL); 

With our new URL created, we're ready to perform the key operation of importing the XML into a template:

 dw.importXMLIntoTemplate(theNewURL); 

Now we create a new document name based on the XML filename and save the file. The new name substitutes an .htm extension for the file's original.xml one and incorporates the user-selected path to a folder:

 docName = findObject("folder_text").value +  theURL.substring(theURL.lastIndexOf("/") + 1, theURL.length - 4) +  ".htm";  res = dw.saveDocument(theTempDOM, docName); 

Finally, if the save operation was successful, the document is closed and control passes back to the doCommand() function to get another URL for processing, if necessary.

 if (res) {     dw.closeDocument(theTempDOM);  }  return; 

The most common error to watch for when using an extension like this is malformed XML. If you encounter problems, check the XML file by choosing Validate Current Document as XML from the Validation panel.

Listing 4-4 Import XML (04_importXML.mxp)

 <html>  <head>  <title>Import XML</title>  <script language="javascript"  src="../Shared/Beyond/Scripts/Beyond_Site.js"></script>  <script language="JavaScript" src="../Shared/MM/Scripts/CMN/UI.js"  type="text/JavaScript"></script>  <script language='javascript'>   //init globals ***************************************************  var theSelect = findObject('fileList');  var theWildText = findObject('wildText');  var theXML = "";  //******************** Primary Functions *************************  function commandButtons(){      return new Array( 'OK', 'doCommand()', 'Cancel',      'window.close()', 'Help', 'getHelp(theHelpFile)')  }  function importXML(theURL) {     var theTempDOM = dw.createDocument();     var theNewURL = MMNotes.localURLToFilePath(theURL);     dw.importXMLIntoTemplate(theNewURL);     docName = findObject("folder_text").value +     theURL.substring(theURL.lastIndexOf("/") + 1, theURL.length -    4) + ".htm";     res = dw.saveDocument(theTempDOM, docName);     if (res) {        dw.closeDocument(theTempDOM);     }     return;  }  function doCommand() {     var selectArray = new Array("currentDoc","openedDocs",     "siteSelected","wholeSite");     var theRes = 1     var theWildCards = ".xml"     for (var i=0; i<theSelect.options.length; i++){        if (theSelect.options[i].selected){           whichFiles = selectArray[i];     }  }  switch (whichFiles){     case "currentDoc":        urlArray = getCurrentDoc();        if(urlArray){           importXML(urlArray);        }        break;     case "openedDocs":        agree = confirm("This command cannot be undone.        Proceed?");        //If it's ok, go        if (agree){           openFilesArray = new Array();           //Get the currently opened files           openFilesArray = getOpenedDocs();           //Filter them to get just the ones matching extensions           urlArray = filterFiles(theWildCards,openFilesArray);           for (var i=0; i<openFilesArray.length; i++){              importXML(urlArray[i]);           }        } else {           return;        }        break;           case "siteSelected":        var siteFocus,agree;        siteSelectedArray = new Array();        writeSiteSelectedArray = new Array();        siteFocus = site.getFocus();        if(siteFocus == "local"  "site map"){           //Ask the user               agree = confirm("This command cannot be undone.              Proceed?");              //If it's ok, go              if (agree){                 //Get the urls of the files selected inside the                 //site window                 siteSelectedArray = site.getSelection();                 if (siteSelectedArray.length == 0                  siteSelectedArray[0].indexOf(".") == -1) {                    alert("No files in Site window selected.\nChoose                    another Generate From option.")                    return;                 }                 //Filter them to get just the matching extensions                 urlArray = filterFiles(theWildCards,                 siteSelectedArray);                 for (var i=0; i<urlArray.length; i++){                    importXML(urlArray[i]);                 }              } else {                 return;              }           }           else{              alert("This command can affect only local files");           }           break;        case "wholeSite":           var agree;           wholeSiteArray = new Array();           writeFilesArray = new Array();           //Ask the user           agree = confirm("This command cannot be undone.           Proceed?");           //If it's ok, go           if (agree){              //Get all the urls of files in the site with matching              //extensions              wholeSiteArray = getWholeSite();              //Filter them to get just the matching extensions              urlArray = filterFiles(theWildCards,wholeSiteArray);              for (var i=0; i<urlArray.length; i++){                 importXML(urlArray[i]);              }           } else {              return;           }           break;     }     window.close();     return;  }  function findFolder() {     findObject("folder_text").value = dw.browseForFolderURL();  }  function findFile() {     findObject("file_text").value = dw.browseForFileURL("select");  }  function getTemplateList() {     //returns a list of templates in site     var theTemplateDir = dw.getSiteRoot() + "Templates/";     var theTemplates = new Array();     theTemplates = DWfile.listFolder(theTemplateDir + "*.dwt",     "files");     if (theTemplates){        loadSelectList(theTemplateList,theTemplates);     }  }   function initUI() {  }  </script>  </head>  <body onLoad="initUI()">  <form name="theForm">    <table border="0">      <tr>        <td nowrap> <div align="right">Import XML from</div></td>        <td nowrap> <select name="fileList" style="width:220px">            <option selected>Current Document</option>            <option>All Open Documents</option>            <option>Selected Files in Site Window </option>            <option>Entire Site</option>          </select> </td>      </tr>      <tr>        <td><div align="right">Save In</div></td>        <td><input name="folder_text" type="text" id="folder_text"        style="width:155">          <input type="button" name="Button" value="Browse"          onClick="findFolder()"></td>      </tr>    </table>  </form></body>  </html>