When developing an extension you may need to know how long the user's machine has been running and thanks to a handy undocumented API, you can.

dw.getMilliseconds() returns the number of milliseconds since the start of the current OS session.

Example of use.

var sessionMill=dw.getMilliseconds()

A handy undocumented API call is available to those developers wanting to write extensions that deal with stylesheets.

getSelectorsDefinedInStylesheet('selector'), this API call is a child method of the Document Object, so once again a reference to a DOM is required.

getSelectorsDefinedInStylesheet('selector') does exactly as its name implies, it returns a array of selectors that match the type passed in as an attribute. The passed in attribute can be either 'class' or 'id'.

To get an array of the 'class' selectors we would use the following:

var dom=dw.getDocumentDOM();
var classSelectors = dom.getSelectorsDefinedInStylesheet('class');

To get an array of 'id' selectors we would use the following:

var dom=dw.getDocumentDOM();
var classSelectors = dom.getSelectorsDefinedInStylesheet('id');

Paul Boon has been going nuts over in his blog An Infinite Number of Monkeys putting up a ton of undocumented Dreamweaver extensibility API calls. His latest, Locating the systems temp folder, discusses a method of determining a couple of folder locations, Dreamweaver's Temp folder and the system's Temp folder. While I've not had occasion to need the system's Temp folder I have used Dreamweaver's Temp folder for pulling files from remote servers to use locally.

When you're done with you're operations in the Temp folder, you typically want to clean up after yourself. One way to do that would be to use DWfile.remove(fileURL) to delete the file(s) that you created, and you can even use DWfile.remove(fodlerURL) to delete your own sub-folder. That's all well and good, but Dreamweaver offers a quick and easy way to clean out the Temp folder using the MMHttp object. The MMHttp object provides access to a remote server, such as grabbing the contents of a file for updating your extension, or even posting data to a server to update the powers that be that you're done with your part of the project. (see my 4 part series on this object, Sending and Receiving Data within Dreamweaver Extensions for more information on this). As part of its functionality, the MMHttp object may pull files into the Dreamweaver Temp folder, so it also offers a documented method (sorry folks no hidden gem in this post) of cleaning up after itself, clearTemp(). This method deletes the contents of the Temp folder. Example usage below:

MMHttp.clearTemp();

The documented API call dreamweaver.getTempFolderPath() returns a File URL to a temporary folder within Dreamweaver's configuration folder where you can store temporary or transient files. These are usually files that you may need during a session of Dreamweaver but are not needed across sessions.

I commonly use this location when one of my extensions needs to write out temporary data collected from other locations or when performing complex file system operations, as it is safe known place to move files during the current DW session.

Note: When using this folder you should treat it like the shared folder, by first creating your own child folder.

However you may require access to the operating systems own temp folder and luckily there is yet again an undocumented API call the comes to the aid of us extension developers.

getSystemTempFolder() This undocumented call is exposed by the DWfile File I/O Object and so to reference it we use DWfile.getSystemTempFolder();

Example of use:

var systemTempFolder = DWfile.getSystemTempFolder();

Note: This call returns an operating system file path and not a file URL like other path related API calls.

From the time Macromedia launched Dreamweaver and introduced the ability for everyday users to extend the product by developing extensions, one extension type was missing, the Toolbar extension. With the release of Dreamweaver MX, extension developers finally got the chance to customize Dreamweaver's toolbars.

Toolbar based extensions are extremely useful, each button or item on a toolbar can be used to launch a single feature/function or by the use of popup menus can be used as the launch point for a group of features/functions. They take up a small amount of screen real estate and allow functions/ features that otherwise might be berried within the menu system to be no more than a mouse click away.

When developing a toolbar item you can choose from eight different base item types, those being Button, Checkbutton, Radiobutton, Menubutton, Dropdown, Combobox, Editcontrol and Colorpicker.

The toolbar items are defined in an xml file called toolbars.xml. Each toolbar is deinfed using a Toolbar tag and toolbar items are defined as child tags, using one of the eight item types i mentioned before.

<toolbar id="DW_Toolbar_Main" label="Document">
  <button id="MyButton"
    command="alert('hello mum') "
    enabled="true"
    image="Shared/images/alert_on.gif"
    disabledimage="Shared/alert_off.gif"
    tooltip="hello mum."
    update="onEveryIdle" />
</toolbar>

Whilst toolbars and toolbar items are easy to define, one of the main issues developers find is the lack of ability to dynamically change a toolbar item tags attributes at run time, and for those changes to be effective within the current active session.

Developers often ask if its possible to change a toolbar items defined image at runtime or want to change the tooltip that appears when the users mouse passes over a toolbar item.

Changes made to a toolbar items definition only take effect the next time Dreamweaver is restarted or after a forced reload of Dreamweaver's extensions, using the Dreamweaver.reloadExtensions() API call.

It would be nice to be able to change a toolbar items defined attributes and for the change to take effect on the fly, without doing a restart or using the dw.reloadExtensions() API call. Thanks to an undocumented API call this is possible.

The undocumented call is a child method of the Core Document Object and is called setToolbarItemAttribute();
To use this method we first either need to get a reference to the DOM of a document or to reference the DOM directly when using the method like so:

Example of changing the tooltip for the toolbar item defined above.

var dom=dw.getDocumentDOM();
dom.setToolbarItemAttribute('DW_Toolbar_Main', 'MyButton', 'tooltip', 'Boo');

As you can see from the example above the first argument is the unique id of the parent toolbar, followed by the unique id of the toolbar item we want to change. Then comes the attribute you want to change, in our case this is the tooltip attribute. The final argument is the new value to use.

Following on from Danilo's blog on Locating a root folder for a specific site. There is another undocumented API call dw.getSiteConfigurationPath(). This API call returns a URL of the current selected site within Dreamweavers site panel.

Example of use:

var selectedSiteRoot =dw.getSiteConfigurationPath();

Note: This API call only returns the URL for the site currently selected within the Sites panel. If you need the URL of a site thats not the current selected site, you should follow the instructions here: Locating a root folder for a specific site

Dreamweaver's DOM (Documeny Object Model) is made up of a subset of objects, properties, and methods from the World Wide Web Consortium (W3C) DOM Level 1 and some properties of the Microsoft Internet Explorer 4.0 DOM.

The most usefull methods available to extension developers are the methods used to return a custom collection of elements contained within a Document Object, such as getElementsByTagName().

However there is a another undocumented method for returning a custom collection of elements that is not part of W3C DOM standards or from Microsofts IE DOM, this being getElementsByAttributeName('passedInAttributeName').

This handy API call works in a similiar way to the getElementsByTagName() API call but as its name implies it returns a collection of elements that have the attibute passed in defined within thier markup.

Example Element Markup with a style attribute defined:

<div id="myDivOne" style="width:100px;height:200px" ></div>

So if we were looking to get all elements within a document that contained a defined style attribute we would use the following:

var elementsWithAStyleAttribute = dw.getDocumentDOM().getElementsByAttributeName('style');

or

var dom=dw.getDocumentDOM();
var elementsWithAStyleAttribute = dom.getElementsByAttributeName('style');

As this method is also an undocumented child method of the core Element Object you can also use this method to return a collection of elements that are child elements of another element, for example a Form element or Div based element.

For Example, to return all elements contained within the second Div element that have a style attribute defined we could use the following:

var dom = dw.getDocuentDOM();
var divElements=dom.getElementsByTagName('div');
var Div2=divElements[1];
var childElements=Div2.getElementsByAttribute('style');

Sometimes you want you users to be able to select a site into which you're going to perform some action, perhaps to copy in some files to install the latest version of your server side application. So maybe you want to have a select list to display all the of sites for the user to choose from.

Dreamweaver makes it simplie to grab an array of all the defined site by using site.getSites(), so all you need to do is to place the site names into a specified select list. Sure you could use JavaScript DOM methods to find and manipulate a select list with a particular ID, but there is an easier way. By combining site.getSites() with a pre-built JavaScript object that is available in configuration folder: ListControl. The ListControl object has a number of methods that make it easy to add items to a select list, as well as grabbing the selected item. To use the ListControl object, just include the JavaScript file /Shared/Common/Scripts/ListControlClass.js into your extenion. to link in from a Command use the following code:

<script src="../Shared/Common/Scripts/ListControlClass.js"></script>

Because I've had to create site lists so many times, I've created a function that takes the name of a select list as a string, and creates a ListControl object out of it and then inserts a list of site names into the select list. I've also added another string parameter that is used as the first item in the select list if you want a "Please choose a site" item at the top. Here is that function:

function cmx_SiteList(listName,insertTextAtTop){
var theList = new ListControl(listName);
var sites = site.getSites();
if(insertTextAtTop) sites.unshift(insertTextAtTop);
theList.setAll(sites, null);
if(insertTextAtTop) theList.setIndex(0);
return theList;
}

Note: This function requires that the ListControl object be available, so remember to include the ListControlClass.js file, as indicated above.

To use this function, insert a <select> tag into your document, and give it a name, let's say, mySiteList. then use one of the following lines of code. The first is used to get a reference to a ListControl obejct stored in siteListObj, and the second get a reference, and also inserts an item at the top of the list:

var siteListObj = SiteList('mySiteList');

var siteListObj = SiteList('mySiteList','Choose a site');

From here on out, you can just use the ListControl's methods and properties to be able to determine which site your user has selected so that you can do further processing from there. If you want to be able to grab the path to a site's root folder, check out this entry: Locating root folder for a specific site

When developing cross platform extensions (Windows or Mac), a developer may need to write a different piece of code for each operating system. A good example of this is when handling OS based file paths (not file URLs), as Windows and Mac Operating systems use different formats. Another example of the need for determining the operating system being used, is the need to use different styles of graphics for extension interfaces, so as to conform with an operating systems look and feel.

The standard Documentation does not explain the different ways a developer can handle these situations, but there are in fact a number of Undocumented API calls that we can use in these situations.

Undocumented DWfile Object (file I/O) API
The DWfile Object exposes an undocumented call getPlatform() that can be used to determine if the extension is running on a Windows or Mac based machine.

Example of use:

var osType = DWfile.getPlatform();

In the above example DWfile.getPlatform() returns 'macos' when executed on a Mac or 'win32' when executed on a windows based.

navigator Object API's
The core navigator Object also exposes a documented property for finding out what operating system Dreamweaver is running on. This is the navigator.platform property, this property works in a similar way to the previous mentioned DWfile.getPlatform() API call.

Example of use:

var osType = navigator.platform;

Note: this is a property of the navigator Object and is not a method of the Object so we do not add the () at the end of the statement like we have when using DWfile.getPlatform().

The navigator Object does have an Undocumented sister static property, this handy property is navigator.winOSname and holds a string value representing the family version of Windows Dreamweaver is running on. For Windows 98 the property value is 'Win98', for Windows XP or 2K the value stored is 'WinXP2K' and for Windows NT the value stored is 'WinNT'.

The type of situation this might be needed is when a developer needs to access a different folder on the system to get to windows specific information or by using a third party API accessing different parts of the windows registry.

Example of use:

switch(navigator.winOSname.toLowerCase()){
  case 'win98':
       Place code for Windows 98 based situation here...   break;
  case 'winxp2k':
       Place code for Windows XP/2K based situation here...   break;
  case 'winnt':
       Place code for Windows NT based situation here...   break;
}

Undocumented dwscripts Static Properties
A developer can reference a number of static properties of the undocumented dwscripts class to determine if they are dealing with a Mac or Windows based machine, as well as finding out the version of windows being used. The static properties of the dwscripts Object that relate to operating system identification are listed below.

dwscripts.IS_MAC, true if on a Mac false if windows.
dwscripts.IS_WIN, true if on window false if a Mac.
dwscripts.IS_WIN_98, true for Windows 98 false if not.
dwscripts.IS_WIN_XP_2K, true for Windows XP or 2K false if not
dwscripts.IS_WIN_NT, true for Windows NT false if not

Example of use:

if(dwscripts.IS_MAC){        
    Place code for Mac based situation here...
}else{       
    Place code for Windows based situation here...
}

Other Undocumented Operating system related API calls.
Finally there are two other undocumented API calls that can be used in relation to the operating system Dreamweaver is running on, these are dreamweaver.isXPThemed() and dreamweaver.isOSX(). These API calls are referred to as enablers, as they are usually used to determine if a function/feature is enabled or disabled.

dreamweaver.isXPThemed() returns true or false. If the user has a Windows XP theme running as there desktop theme then the call would return true. This is the normal or default state for Windows XP. The call would only return false if the user is running Windows XP using the classic mode or running a version of Windows that does not support themes.

dreamweaver.isOSX() returns true or false depending on the type of Mac OS the user is running, if the user is running a version of Mac OSX then the call would return true.

These calls would primarily be used to handle the display of different styles of user interface graphics, making sure the extension had the look and feel of the versions of operating system being used to run Dreamweaver. Although these calls would be used in conjunction with some or all of the above mentioned API calls and properties.

Example of use:

if(dwscripts.IS_MAC){
    if(dreamweaver.isOSX()){
       Place OSX interface code here...
    }else{
      Place non-Mac OSX interface code here...
    }
}else{
     if(dreamweaver.isXPThemed()){
       Place Win XP interface code here...
    }else{
      Place non-Win XP interface code here...
    }
}

When developing an extension you may need to know the file path the user used when installing Dreamweaver. An obvious example of this is when a developer needs to access files to do with the JVM (Java Virtual Machine) that ships with Dreamweaver. The JVM is installed in a child folder to the main applications parent folder, but is not inside Dreamweaver's Configuration path. Luckily there is an Undocumented API call that will return the path used to Install Dreamweaver. The undocumented call is dreamweaver.getRootDirectory(), unlike nearly all other path related API calls in Dreamweaver, this call returns a file path and not a URL.

Example of use:

var dwInstallDIR=dreamweaver.getRootDirectory();

This call is also helpful if you need to get access to other files installed alongside the main Dreamweaver executable or to the folder help files are installed in by default.

Ever wondered who is behind Dreamweaver MX 2004's extensibility, well thanks to an undocumented static property you can find out.

Whilst this API property has no real use when it comes to extension development, you can at least see who you should be thanking or screaming at when it comes to extension development :-).

So here is the static property:

dreamweaver.credits (type String)

The best way to see the result is simply to alert the property like so:

alert(dreamweaver.credits);

Also do not forget to take note of the last part of the message that appears...

For developers developing extensions to manipulate snippets, the main issue has been the lack of an API call to force the Snippets panel to refresh itself. This especially becomes an issue when your extension makes dynamic changes to the Snippets folder within Dreamweaver's configuration directory.

An undocumented API call comes to the rescue once again, this time in the shape of:

dreamweaver.snippetPalette.reloadSnippetList()
dw.snippetPalette.reloadSnippetList()

This handy API call simply reloads the Snippet Panel showing any and all changes made to the snippets folder structure.

The main issues many developers find when starting to write extensions is that many of the techniques used to develop DHTML Interface elements simply are not possible within Dreamweaver extension Interfaces.

Another issue is the annoyance that something that is possible in one type of extension is not available in another type of extension.

An example of this is the classic popup menu. Popup Menus can be a life saver when designing an interface for an application, as they allow the developer to group similar or related features to a single interaction point within an interface.

Of course when developing toolbars they are nearly always essential. Without popup menus interfaces would be at best large and confusing and at worst impossible, resulting in most cases with the developer having to leave out a feature that might otherwise have been added in.

When developing Toolbars and Insertbar Objects Extensions for Dreamweaver, developers can make use of popup menus by utilizing the MENUBUTTON tag. But according to the documentation that ships with Dreamweaver if your developing commands or other types of extensions there seems little a developer can do... or is there?

An undocumented Core Object type comes to the rescue with the somewhat obvious name PopupMenu Object. The PopupMenu Object is not packed with features and does not support sub menus or icons and other graphics and menu items can not be grayed out. But it does allow the developer to call a popup menu when and where ever they wish within any extension type.

So how do we use this object?

To define a popup menu in your code you simply declare a variable being of type PopupMenu like so.

Var myPopupMenu = new PopupMenu();

To add items to the menu you make use of addItem method that is one of the two methods the PopupMenu Object exposes. So if we wanted to have four items in the menu when it pops up we would need to call this method four times like so.

myPopupMenu.addItem('item 1');
myPopupMenu.addItem('item 2');
myPopupMenu.addItem('item 3');
myPopupMenu.addItem('item 4');

To make the popup menu appear we need to call the other exposed method which is the popup method. This displays the popup menu allowing the user to select an item from the menu.

var respone = myPopupMenu.popup();

When a user clicks a menu item on the menu the menu item text is assigned to the variable used, in the case of the example above the variable response is assigned the value of the menu item selected.

A simple way to make use and to simplify the code is to write a function to handle the creation and displaying of the menu. This way we can pass in an array of menu items and then use a single function call when ever we need to call a popup menu. The code below demonstrates how to do this.

function popupMenu(a){
    var m = new PopupMenu();
    for(var i=0;i < a.length;i++){
       m.addItem(a[i]);
    }
    var s=m.popup();
    return s;
}

to use this function we simply call the function popupMenu() passing it an array of menu items and it returns the item the user selected.

Example 1 (Code example)

var myMenuItems=new Array('item 1','item 2','item 3','item 4');
var response = popupMenu(myMenuItems);
alert(response)

Example 2 (Code example)

alert(popupMenu([ 'item 1','item 2','item 3','item 4' ]));

Dreamweaver documents a couple of methods for obtaining the root folder for a site: dw.getSiteRoot() and site.getLocalPathToFiles(). However, both of these functions will return the root folder for the site that the currently focused document belongs to, the former a file:/// path and the latter a C:\ type of reference. If there are no documents open, then the root folder of the site shown in the Files panel is returned.

But what if you need to get the root folder for the site that is displayed so that you can open, copy, or create files based upon user input in one of your extensions and save them into the selected site? Well, if all the documents are closed, then you can do this using the API calls mentioned above, but you have to take into account that your users will likely be working on a document at the time that they invoke your extension.

Forunately, there is an undocumented API called site.getLocalRootURL(siteName) that does return the file:/// path to the specified site's folder. As long as you can grab the site name, you're off and running. So the code that you need is:

var siteName = site.getCurrentSite();
var siteRoot = site.getLocalRootURL(siteName);

An undocumented Dreamweaver extensibility API call was brought to my attention a while ago by the amazing Paul Boon. dw.getUserConfigurationPath() can be used, as its name so capably implies, to grab a file path to the user's Configuration folder for Dreamweaver, rather than the application's install Configuration folder.

Note: dw.getConfigurationPath() returns a path without a trailing slash, and dw.getUserConfigurationPath() returns a path with a trailing slash. For example:

alert(dw.getConfigurationPath);
// file:///C|/Program Files/Macromedia/Dreamweaver MX 2004/Configuration

alert(dw.getUserConfigurationPath());
// file:///C|/Documents and Settings/username/Application Data/Macromedia/Dreamweaver MX 2004/Configuration/

When might this be an issue? Well, in the Edit Document Templates extension that I wrote, I needed to check first if the selected template for editing was in the user's configuration folder (which would happen if the user installed an extension that added a new document template to Dreamweaver), and open that one, and if not, then open the template that is in the application install folder.

There comes a time when you will need to open an external application, whether it be to just have that app open for the user to work with, as is the case with my Open Studio Apps toolbar, or to have processing on files done by the external app. For such a task, I've been using dreamweaver.openWithApp(), or more accurately, the shortcut, dw.openWithApp().

This function accepts two parameters, a file path for the file to open in the external app, and the file path to the external app. While the docs say that you must pass in a file:/// URL, you can actually get away with using a "regular" file path, as long as you escape the \s properly because you're passing a string.

For example, the following two snippets of code work the same:

Snippet 1:
var myFilePath = 'file:///C|/Danilo.jpg';
var appPath = 'file:///C|/Program Files/Macromedia/Fireworks MX 2004/Fireworks.exe';

dw.openWithApp(myFilePath,appPath);

Snippet 2:
var myFilePath = 'C:\\Danilo.jpg';
var appPath = 'C:\\Program Files\\Macromedia\\Fireworks MX 2004\\Fireworks.exe';

dw.openWithApp(myFilePath,appPath);

Depending on the application, you can even pass in an empty string, to open your app without a starting file. As in the snippet below:

Snippet 3:
var appPath = 'C:\\Program Files\\Macromedia\\Fireworks MX 2004\\Fireworks.exe';

dw.openWithApp("",appPath);