Home / Developer Center / Dreamweaver Developer Center /

Dreamweaver Article

by François Richardson
www.f-r-d.com

This article briefly describes the creation of a Macromedia Dreamweaver MX extension, PHPbreadcrumbs.mxp (available from the Dreamweaver exchange). It is offered here, because examples can be very helpful, but prior to developing extensions, there just is no substitute for spending a good amount of time reading the Dreamweaver MX extension documentation. A good background in JavaScript is also required (one book I found very helpful is O'Reilly's JavaScript: The Definitive Guide).

Writing extensions can allow you to easily share the code you write, even with non-technical members of your team. I originally created some PHP code to dynamically generate breadcrumb links by reading a page's URL. To allow others to easily use that code as well, I placed it within a HTML file that works as a Dreamweaver command, according to the rules of the Dreamweaver MX API. The Dreamweaver MX API is a set of objects available to coders who want to create Dreamweaver MX extensions. Finally, so that I would not have to manually install the command on every team member's machine, I packaged it in an extension.

What may be particularly interesting about the extension this article focuses on is that it simply dumps code onto a page. That code is stored within a variable inside the Dreamweaver command file that the extension generates. A developer could easily repeat the steps taken here, but replace the PHP breadcrumbs source with whatever code he or she needs. The code itself could be in any language, server or client side. But the Dreamweaver command that inserts such code, of course, needs to be written in Dreamweaver MX API JavaScript.

If you are curious, you can take a look at the PHP code that generates the breadcrumbs.

Once the code has been tested, it can be placed within a Dreamweaver command file. To create the Dreamweaver command, make a blank HTML file in the Dreamweaver MX/Configuration/Commands folder, and start filling it with the following:


  <html><head> <title>Insert breadcrumbs</title><script 
  language="javascript">

  var what2insert = 'my dynamic breadcrumb code will eventually go here';

  function canAcceptCommand(){

Let's stop here for a second. Dreamweaver MX commands are just HTML files with JavaScript. This type of code should look familiar to web designers. The function canAcceptCommand() is JavaScript, but it is specific to the Dreamweaver MX API. When placed inside a command file, if canAcceptCommand() returns true, the command is allowed to execute. If the canAcceptCommand() method returns false, the command aborts silently. The content of canAcceptCommand() is up to the developer to fill in. I chose to do the following:


var dDOM = dw.getDocumentDOM();

  var dSel = dDOM.getSelection();

  return(dSel[0] == dSel[1]);

  }

First, I use the dw.getDocumentDOM() Dreamweaver MX API method to retrieve the DOM object for the document currently opened in Dreamweaver MX. Then, I use getSelection() (a method defined for every DOM object in Dreamweaver MX) to get an array containing the positions of the current selection in Dreamweaver MX. This means that at the time my command executes, I can tell what is selected in whatever document happens to be open in Dreamweaver. The array, which I named dSel, contains two elements: the start position for the current selection, and the end position. They are counted in character offsets from the start of the source code for the document. Once I have those two values, I compare them and return the boolean value from the comparison. This means that I return true if the two values are equal, and false if they are not equal. The only way for the values to be equal is if the current selection is just a cursor, with no elements or code selected in Dreamweaver MX. So far, I have prevented my command from executing if anything is selected. This is good, because I don't want my contributors accidentally replacing anything with the breadcrumbs they insert.

Now, I start my own function to insert what I need into a Dreamweaver MX page:


function stickItIn(){

  var dDOM = dw.getDocumentDOM();
  var dSel = dDOM.getSelection();
  var dDoc = dDOM.documentElement;
  var dHTML =dDoc.outerHTML;

First, I get the DOM of whatever document is open in Dreamweaver MX at the time my command runs. Then I get the current selection, then the object representing the HTML node--documentElement, then the outer HTML of that node--outerHTML (everything between <HTML> and </HTML>, inclusive).

The second part of my function replaces the HTML of the currently opened document with a substring going up to the start point of the selection--dSel[0], concatenated with the string I want to insert--what2insert, concatenated with a substring starting at the end selection point--dSel[1] (and going to the end of the HTML):


dDoc.outerHTML = dHTML.substring(0,dSel[0]) + what2insert + dHTML.substring(dSel[1]);

I've taken the whole page, sliced it in half at the selection point, then put it all back together with my what2insert string inserted in the middle. After all these operations, the selection point will no longer be what it was when I started. Out of courtesy to my users, I reset the selection point using the setSelection() method of the Dreamweaver MX DOM object. I set it back to what it was, using the dSel array I obtained earlier:


  dDOM.setSelection(dSel[0],dSel[1]);

  }

Now that my functions are defined, I need to trigger them. The canAcceptCommands() function always automatically triggers if it's placed in a Dreamweaver MX Command file. I'll trigger my stickItIn() function with an onLoad handler and close out the HTML:


</script></head><body onLoad="stickItIn()"></body>

</html>

Next, I test the code to make sure it behaves as I intend it to. I've created a Dreamweaver MX command that inserts into the current document whatever I assign my variable what2insert. It is placed with the Commands folder of the Dreamweaver MX application Configuration. I start up Dreamweaver, choose Commands > Insert breadcrumbs to test that everything works. If it does, I can go back to editing the command file I created. If it doesn't, or if I made a mistake that is bad enough to impair Dreamweaver, I can always delete the file I created, and start over. Let's assume that everything works. I can then go back to my command and modify the assigned value of the what2insert variable, replacing it with the dynamic code I need. Because one piece of code (my HTML/JavaScript "Insert Breadcrumbs.htm" file) is processing another (my dynamic code), I need to escape dangerous characters. In my case, I've escaped all single quotes and new lines in the source.

View the final result, with added PHP code.

I now have a working command in Dreamweaver MX. Instead of copying and pasting my dynamic breadcrumbs code, I can just choose Commands > Insert Breadcrumbs. It took some work to create the command, and I want to share it with others. So, I'll package it into an MXP file that the Macromedia Extension Manager will install into other computers running Dreamweaver MX.

First, I need to create an MXI file. If you've already installed extensions, you can look at the MXI files for those extensions. They are found under Dreamweaver MX/Configuration/Extensions. The MXI file is a road map of your extension, detailing its author, purpose, and among other things, what files to create where on the end user's machine. In our example, we need the MXI file to contain instructions to place the command file we created in the Dreamweaver MX/Configuration/Commands folder.

An MXI file is just an XML page with Dreamweaver MX-specific tags. Let's create one. The first half is a description that will appear to the end user in the Extension Manager during installation:


  <macromedia-extension name="Insert breadcrumbs" 
  version="1.0" type="Command">
  <author name="Francois Richardson" />
  <products>
  <product name="Dreamweaver" version="3"
  primary="true" 
  />
  </products>
  <description>
  <![CDATA[
  Inserts a dynamic script in PHP that reads the path to the page and
  turns it into breadcrumbs.
  ]]>
  </description>
 <ui-access>
  <![CDATA[
  Commands > Insert PHP breadcrumbs

  ]]>
  </ui-access>

Most of this should be pretty self-explanatory. The version attribute of the <product> tag is a minimum version, so this extension will install on Dreamweaver 3 and above.

The second part of the MXI file tells the Extension Manager where to find the files you've created, and where to insert them on the end user's machine:

<files>
  <file source="Insert PHP breadcrumbs.htm" 
  destination="$dreamweaver/configuration/Commands"/>
  </files>

  <configuration-changes>
  </configuration-changes>
  </macromedia-extension>

The only thing worth noting here is the $dreamweaver. That name gets translated to the Application folder for Dreamweaver MX on the end user's machine. I can now put the MXI file and my Insert PHP breadcrumbs.htm document into a folder somewhere, and start the Extension Manager. Within the Extension Manager, I choose File > Package Extension, and select my MXI file. The extension manager creates an MXP file, ready to be sent to anyone with the Macromedia Extension Manager.

Creating Dreamweaver MX extensions can allow the programmer on a web team to tailor Dreamweaver MX for a specific company or project. Any person with strong JavaScript skills, (and the time to seriously read the Dreamweaver API documentation! ) can create a Dreamweaver command, allowing others to execute custom entries in the Commands menu. Packaging such a command into a Dreamweaver MX extension makes the installation of the command very easy for the end user. Download the PHP breadcrumbs extension from the solutions website.

About the author
François Richardson is proud to have led Macromedia's Dreamweaver Technical Support teams worldwide. On the Dreamweaver Product Team, he enjoyed representing the needs and workflow of today's developer community, at a time when new directions for the product were being envisioned. François has provided training, technical writing, and design services for Macromedia, CDNET, Sykes, Management Solutions Japan, gay.com, and Newriders Publishing. He now works as a Web & Graphics Designer, in San Francisco.