The Floating panel API

All the custom functions in the Floating panel API are optional.

Some of the functions in this section operate only on the Windows operating system. The description of the function indicates whether this is the case.

displayHelp()

Description

If this function is defined, a Help button appears below the OK and Cancel buttons in your dialog box. This function is called when the user clicks the Help button.

Arguments

None.

Returns

Dreamweaver expects nothing.

Example

 // the following instance of displayHelp() opens // in a browser a file that explains how to use // the extension. function displayHelp(){   var myHelpFile = dw.getConfigurationPath() +     '/ExtensionsHelp/superDuperHelp.htm';   dw.browseDocument(myHelpFile); } 

documentEdited()

Description

This function is called when the floating panel becomes visible and after the current series of edits is complete; that is, multiple edits might occur before this function is called. This function should be defined only if the floating panel must track edits to the document.

NOTE

Define the documentEdited() function only if you require it because its existence impacts performance.

Arguments

None.

Returns

Dreamweaver expects nothing.

Example

The following example of the documentEdited() function scans the document for layers and updates a text field that displays the number of layers in the document:

 function documentEdited(){   /* create a list of all the layers in the document */   var theDOM = dw.getDocumentDOM();   var layersInDoc = theDOM.getElementsByTagName("layer");   var layerCount = layersInDoc.length;   /* update the numOfLayers field with the new layer count */   document.theForm.numOfLayers.value = layerCount; } 

getDockingSide()

Availability

Dreamweaver MX.

Description

Specifies the locations at which a floating panel can dock. The function returns a string that contains some combination of the words "left", "right", "top", and "bottom". If the label is in the string, you can dock a floating panel to that side. If the function is missing, you cannot dock a floating panel to any side.

You can use this function to prevent certain panels from docking on a certain side of the Dreamweaver workspace or to each other.

Arguments

None.

Returns

Dreamweaver expects a string containing the words "left", "right", "top", and "bottom", or a combination of them, that specifies where Dreamweaver can dock the floating panel.

Example

 getDockingSide() {   return dock_side = "left top"; } 

initialPosition()

Description

Determines the initial position of the floating panel the first time it is called. If this function is not defined, the default position is the center of the screen.

Arguments

 platform 

• The platform argument has a value of either "Mac" or "Win", depending on the user's platform.

Returns

Dreamweaver expects a string of the form "leftPosInPixels,topPosInPixels".

Example

The following example of the initialPosition() function specifies that the first time the floating panel appears, it should be 420 pixels from the left and 20 pixels from the top in Windows, and 390 pixels from the left side of the screen and 20 pixels from the top of the screen on the Macintosh:

 function initialPosition(platform){   var initPos = "420,20";   if (platform == "macintosh"){     initPos = "390,20";   }   return initPos; } 

initialTabs()

Description

Determines which other floating panels are tabbed together the first time that this floating panel appears. If any listed floating panel has appeared previously, it is not included in the tab group. To ensure that two custom floating panels are tabbed together, each panel should reference the other with the initialTabs() function.

Arguments

None.

Returns

Dreamweaver expects a string of the form "floaterName1,floaterName2,...floaterNameN".

Example

The following example of the initialTabs() function specifies that the first time the floating panel appears, it should be tabbed with the scriptEditor floating panel:

 function initialTabs(){   return "scriptEditor"; } 

isATarget()

Availability

Dreamweaver MX (Windows only).

Description

Specifies whether other panels can dock to this floating panel. If the isATarget() function is not specified, Dreamweaver prevents other panels from docking to this one. Dreamweaver calls this function when the user tries to combine this panel with others.

Arguments

None.

Returns

Dreamweaver expects a Boolean value: TRue if other floating panels can dock to this one; false otherwise.

Example

 IsATarget() {   return true; } 

isAvailableInCodeView()

Description

Determines whether the floating panel should be enabled when Code view is selected. If this function is not defined, the floating panel is disabled in the Code view.

Arguments

None.

Returns

Dreamweaver expects a Boolean value: true if the floating panel should be enabled in Code view; false otherwise.

isResizable()

Availability

Dreamweaver 4.

Description

Determines whether a user can resize a floating panel. If the function is not defined or returns a true value, the user can resize the floating panel. If the function returns a false value, the user cannot resize the floating panel.

Arguments

None.

Returns

Dreamweaver expects a Boolean value: true if the user can resize the floating panel; false otherwise.

Example

The following example prevents the user from resizing the floating panel:

 function isResizable() {   return false; } 

selectionChanged()

Description

Called when the floating panel becomes visible and when the selection changes (when focus switches to a new document or when the insertion pointer moves to a new location in the current document). This function should be defined only if the floating panel must track the selection.

NOTE

Define selectionChanged() only if you absolutely require it because its existence impacts performance.

Arguments

None.

Returns

Dreamweaver expects nothing.

Example

The following example of selectionChanged() shows a different layer in the floating panel, depending on whether the selection is a script marker. If the selection is a script marker, Dreamweaver makes the script layer visible. Otherwise, Dreamweaver makes the blank layer visible.

 function selectionChanged(){    /* get the selected node */    var theDOM = dw.getDocumentDOM();    var theNode = theDOM.getSelectedNode();    /* check to see if the node is a script marker */    if (theNode.nodeType == Node.ELEMENT_NODE && theNode.tagName == "SCRIPT"){     document.layers['blanklayer'].visibility = 'hidden';     document.layers['scriptlayer'].visibility = 'visible';}   else{     document.layers['scriptlayer'].visibility = 'hidden';     document.layers['blanklayer'].visibility = 'visible';    } } 

About performance

Declaring the selectionChanged() or documentEdited() function in your custom floating panels can impact Dreamweaver performance adversely. Consider that the documentEdited() and selectionChanged() functions are called after every keystroke and mouse click when Dreamweaver is idle for more than one-tenth of a second. It's important to use different scenarios to test your floating panel, using large documents (100K or more of HTML) whenever possible, to test performance impact.

To help avoid performance penalties, the setTimeout() function was implemented as a global method in Dreamweaver 3. As in the browsers, the setTimeout() function takes two arguments: the JavaScript to be called and the amount of time in milliseconds to wait before calling it.

The setTimeout() method lets you build pauses into your processing. These pauses let the user continue interacting with the application. You must build in these pauses explicitly because the screen freezes while scripts process, which prevents the user from performing further edits. The pauses also prevent you from updating the interface or the floating panel.

The following example is from a floating panel that displays information about every layer in the document. It uses the setTimeout() method to pause for a half second after processing each layer.

 /* create a flag that specifies whether an edit is being processed, and set it to false. */ document.running = false; /* this function called when document is edited */ function documentEdited(){   /* create a list of all the layers to be processed */   var dom = dw.getDocumentDOM();   document.layers = dom.getElementsByTagName("layer");   document.numLayers = document.layers.length;   document.numProcessed = 0;   /* set a timer to call processLayer(); if we didn't get    * to finish processing the previous edit, then the timer    * is already set. */   if (document.running = false){     setTimeout("processLayer()", 500);   }   /* set the processing flag to true */   document.running = true; } /* process one layer */ function processLayer(){   /* display information for the next unprocessed layer.       displayLayer() is a function you would write to       perform the "magic".  */    displayLayer(document.layers[document.numProcessed]);   /* if there's more work to do, set a timeout to process    * the next layer.  If we're finished, set the document.running    * flag to false. */   document.numProcessed = document.numProcessed + 1;   if (document.numProcessed < document.numLayers){     setTimeout("processLayer()", 500);   }else{     document.running = false;   } }