Detailed instructions for use are in the User's Guide.
[. . . ] Dreamweaver API Reference
Trademarks 1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally. [. . . ] If fileURL is an empty string, Dreamweaver prompts the user to select an XML file to import.
Returns
A Boolean value: true if the named XML file exists and if the site is created successfully; false otherwise.
280
Site
site. invertSelection()
Availability
Dreamweaver 3.
Description
Inverts the selection in the site map.
Arguments
None.
Returns
Nothing.
site. isCloaked()
Availability
Dreamweaver MX.
Description
Determines whether the current selection in the Site panel or the specified folder is cloaked.
Arguments
siteOrURL
The siteOrURL argument must contain one of the following two values:
The keyword "site", which indicates that the isCloaked() function should test the selection in the Site panel The file URL of a particular folder, which indicates that isCloaked() should test the specified folder
Returns
A Boolean value: true if the specified object is cloaked; false otherwise.
Site functions
281
site. locateInSite()
Availability
Dreamweaver 3.
Description
Locates the specified file (or files) in the specified pane of the Site panel and selects the files.
Arguments
localOrRemote, siteOrURL
The localOrRemote argument must be either "local" or "remote". The siteOrURL argument must be the keyword "site", which indicates that the function should act on the selection in the Site panel or the URL for a single file.
Returns
Nothing.
Enabler
See "site. canLocateInSite()" on page 591.
site. makeEditable()
Availability
Dreamweaver 3.
Description
Turns off the read-only flag on the selected files.
Arguments
None.
Returns
Nothing.
Enabler
See "site. canMakeEditable()" on page 591.
282
Site
site. makeNewDreamweaverFile()
Availability
Dreamweaver 3.
Description
Creates a new Dreamweaver file in the Site panel in the same folder as the first selected file or folder.
Arguments
None.
Returns
Nothing.
Enabler
See "site. canMakeNewFileOrFolder()" on page 592.
site. makeNewFolder()
Availability
Dreamweaver 3.
Description
Creates a new folder in the Site panel in the same folder as the first selected file or folder.
Arguments
None.
Returns
Nothing.
Enabler
See "site. canMakeNewFileOrFolder()" on page 592.
Site functions
283
site. newHomePage()
Availability
Dreamweaver 3.
Description
Opens the New Home Page dialog box to let the user create a new home page.
This function operates only on files in the Site Map view.
NO T E 284
Arguments
None.
Returns
Nothing.
site. newSite()
Availability
Dreamweaver 3.
Description
Opens the Site Definition dialog box for a new, unnamed site.
Arguments
None.
Returns
Nothing.
site. open()
Availability
Dreamweaver 3.
Description
Opens the files that are currently selected in the Site panel. If any folders are selected, they are expanded in the Site Files view.
Site
Arguments
None.
Returns
Nothing.
Enabler
See "site. canOpen()" on page 592.
site. put()
Availability
Dreamweaver 3.
Description
Puts the selected files and handles dependent files in one of the following ways:
If the user selects Prompt on Put/Check In in the Site FTP preferences, the Dependent Files dialog box appears. If the user previously selected the Don't Show Me Again option in the Dependent Files dialog box and clicked Yes, dependent files are uploaded and no dialog box appears. If the user previously selected the Don't Show Me Again option in the Dependent Files dialog box and clicked No, dependent files are not uploaded and no dialog box appears.
Arguments
siteOrURL
The siteOrURL argument must be the keyword "site", which indicates that the function should act on the selection in the Site panel or the URL for a single file.
Returns
Nothing.
Enabler
See "site. canPut()" on page 593.
Site functions
285
site. recreateCache()
Availability
Dreamweaver 3.
Description
Re-creates the cache for the current site.
Arguments
None.
Returns
Nothing.
Enabler
See "site. canRecreateCache()" on page 593.
site. refresh()
Availability
Dreamweaver 3.
Description
Refreshes the file listing on the specified side of the Site panel.
Arguments
whichSide
The whichSide argument must be "local", or "remote". If the site map has focus and whichSide is "local", the site map refreshes.
Returns
Nothing.
Enabler
See "site. canRefresh()" on page 594.
286
Site
site. remoteIsValid()
Availability
Dreamweaver 3.
Description
Determines whether the remote site is valid.
Arguments
None.
Returns
A Boolean value that indicates whether a remote site has been defined and, if the server type is Local/Network, whether the drive is mounted.
site. removeLink()
Availability
Dreamweaver 3.
Description
Removes the selected link from the document above it in the site map.
Arguments
None.
Returns
Nothing.
Enabler
See "site. canRemoveLink()" on page 594.
site. renameSelection()
Availability
Dreamweaver 3.
Description
Turns the name of the selected file into an text field, so the user can rename the file. If more than one file is selected, this function acts on the last selected file.
Site functions 287
Arguments
None.
Returns
Nothing.
site. runValidation()
Availability
Dreamweaver MX.
Description
Runs the Validator on the entire site or only highlighted items.
Arguments
selection
The selection argument is the parameter that specifies that the Validator should check only the highlighted items; otherwise, the Validator checks the entire current site.
Returns
Nothing.
site. saveAsImage()
Availability
Dreamweaver 3.
Description
Opens the Save As dialog box to let the user save the site map as an image.
Arguments
fileType
The fileType argument is the type of image that should be saved. Valid values for Windows are "bmp" and "png"; valid values for the Macintosh are "pict" and "jpeg". If the argument is omitted, or if the value is not valid on the current platform, the default is "bmp" in Windows and "pict" on the Macintosh.
Returns
Nothing.
288
Site
site. selectAll()
Availability
Dreamweaver 3.
Description
Selects all files in the active view (either the site map or the site files).
Arguments
None.
Returns
Nothing.
site. selectHomePage()
Availability
Dreamweaver 3.
Description
Opens the Open File dialog box to let the user select a new home page.
This function operates only on files in the Site Map view.
NO T E
Arguments
None.
Returns
Nothing.
site. selectNewer()
Availability
Dreamweaver 3.
Description
Selects all files that are newer on the specified side of the Site panel.
Site functions
289
Arguments
whichSide
The whichSide argument must be either "local" or "remote".
Returns
Nothing.
Enabler
See "site. canSelectNewer()" on page 595.
site. serverActivity()
Availability
Dreamweaver 8.
Description
This function determines whether Dreamweaver is currently interacting with a server. Because Dreamweaver cannot do more than one server activity at a time, this function lets you determine whether to disable functionality that requires server interaction.
Arguments
None.
Returns
A Boolean value that indicates whether Dreamweaver is currently interacting with a server.
Example
The following example, from the menus. xml file, displays a menu item if there is no server activity (and if there is a current site specified in Dreamweaver):
<menuitem name="Remove Connection Scripts" enabled="!site. serverActivity() && site. getCurrentSite() != ''" command="alert(MMDB. removeConnectionScripts())" id="SiteOptionsSiteMenu_RemoveConnectionScripts" />
290
Site
site. setAsHomePage()
Availability
Dreamweaver 3.
Description
Designates the file that is selected in the Site Files view as the home page for the site.
Arguments
None.
Returns
Nothing.
site. setCloakingEnabled()
Availability
Dreamweaver MX.
Description
Determines whether cloaking should be enabled for the current site.
Arguments
enable
The enable argument is a Boolean value that indicates whether cloaking should be enabled. A value of true enables cloaking for the current site; a value of false disables cloaking for the current site.
Returns
None.
site. setConnectionState()
Availability
Dreamweaver 3.
Description
Sets the connection state of the current site.
Site functions
291
Arguments
bConnected
The bConnected argument is a Boolean value that indicates if there is a connection (true) or not (false) to the current site.
Returns
Nothing.
site. setCurrentSite()
Availability
Dreamweaver 3.
Description
Opens the specified site in the local pane of the Site panel.
Arguments
whichSite
The whichSite argument is the name of a defined site (as it appears in the Current Sites list in the Site panel or the Edit Sites dialog box).
Returns
Nothing.
Example
If three sites are defined (for example, avocado8, dreamcentral, and testsite), a call to site. setCurrentSite("dreamcentral"); makes dreamcentral the current site.
site. setFocus()
Availability
Dreamweaver 3.
Description
Gives focus to a specified pane in the Site panel. If the specified pane is not showing, this function displays the pane and gives it focus.
Arguments
whichPane
292
Site
The whichPane argument must be one of the following strings: "local", "remote", or
"site map".
Returns
Nothing.
site. setLayout()
Availability
Dreamweaver 3.
Description
Opens the Site Map Layout pane in the Site Definition dialog box.
Arguments
None.
Returns
Nothing.
Enabler
See "site. canSetLayout()" on page 595.
site. setLinkVisibility()
Availability
Dreamweaver 3.
Description
Shows or hides the current link.
Arguments
bShow
The bShow argument is a Boolean value that indicates whether to remove the Hidden designation from the current link.
Returns
Nothing.
Site functions
293
site. setSelection()
Availability
Dreamweaver 3.
Description
Selects files or folders in the active pane in the Site panel.
Arguments
arrayOfURLs
The arrayOfURLs argument is an array of strings where each string is a path to a file or folder in the current site, which is expressed as a file:// URL.
Omit the trailing slash (/) when specifying folder paths.
N OT E
Returns
Nothing.
site. siteRelativeToLocalPath()
Availability
Dreamweaver 8.
Description
Converts a site-relative URI reference to a local file path.
Arguments
siteRelativeURI
The siteRelativeURI attribute, which is required, is a string that contains the siterelative URI.
Returns
A string, which specifies the path to a local file on your local computer.
Example
The following example
var filePath = site. siteRelativeToLocalPath("/myWebApp/myFile. xlml");
returns "C:\Inetpub\wwwroot\siteA\myFile. xml" based on your site mappings and HTTP address specified in the Local info of the Site Definition dialog box.
294 Site
site. synchronize()
Availability
Dreamweaver 3.
Description
Opens the Synchronize Files dialog box.
Arguments
None.
Returns
Nothing.
Enabler
See "site. canSynchronize()" on page 596.
site. uncloak()
Availability
Dreamweaver MX.
Description
Uncloaks the current selection in the Site panel or the specified folder.
Arguments
siteOrURL
The siteOrURL argument must contain one of the following values:
The keyword "site", which indicates that the unCloak() function should act on the selection in the Site panel The URL of a particular folder, which indicates that the unCloak() function should act on the specified folder and all its contents
Returns
Nothing.
Enabler
See "site. canUncloak()" on page 597.
Site functions
295
site. uncloakAll()
Availability
Dreamweaver MX.
Description
Uncloaks all folders in the current site and deselects the Cloak Files Ending With: checkbox in the Cloaking settings.
Arguments
Nothing.
Returns
Nothing.
Enabler
See "site. canUncloak()" on page 597.
site. undoCheckOut()
Availability
Dreamweaver 3.
Description
Removes the lock files that are associated with the specified files from the local and remote sites, and replaces the local copy of the specified files with the remote copy.
Arguments
siteOrURL
The siteOrURL argument must be the keyword "site", which indicates that the function should act on the selection in the Site panel or the URL for a single file.
Returns
Nothing.
Enabler
See "site. canUndoCheckOut()" on page 597.
296
Site
site. viewAsRoot()
Availability
Dreamweaver 3.
Description
Temporarily moves the selected file to the top position in the site map.
Arguments
None.
Returns
Nothing.
Enabler
See "site. canViewAsRoot()" on page 598.
Site functions
297
298
Site
CHAPTER 13
Document
The Document functions in Macromedia Dreamweaver 8 perform operations that affect the document on which the user is working. These functions perform tasks that convert tables to layers, run a command in the Configuration/Commands folder, browse for a file URL, check spelling or set page properties, convert a relative URL to an absolute URL, get the currently selected node, perform URL encoding on a string, or run a translator on the document.
13
Conversion functions
Conversion functions convert tables to layers, layers to tables, and cascading style sheets (CSS) to HTML markup. Each function exactly duplicates the behavior of one of the conversion commands in the File or Modify menu.
dom. convertLayersToTable()
Availability
Dreamweaver 3.
Description
Opens the Convert Layers to Table dialog box.
Arguments
None.
Returns
Nothing.
Enabler
See "dom. canConvertLayersToTable()" on page 554.
299
dom. convertTablesToLayers()
Availability
Dreamweaver 3.
Description
Opens the Convert Tables to Layers dialog box.
Arguments
None.
Returns
Nothing.
Enabler
See "dom. canConvertTablesToLayers()" on page 554.
Command functions
Command functions help you make the most of the files in the Configuration/Commands folder. They manage the Command menu and call commands from other types of extension files.
dreamweaver. editCommandList()
Availability
Dreamweaver 3.
Description
Opens the Edit Command List dialog box.
Arguments
None.
Returns
Nothing.
300
Document
dreamweaver. popupCommand() (deprecated)
Availability
Dreamweaver 2; deprecated in 3 in favor of dreamweaver. runCommand().
Description
This function executes the specified command. To the user, the effect is the same as selecting the command from a menu; if a dialog box is associated with the command, it appears. This function provides the ability to call a command from another extension file. It blocks other edits until the user closes the dialog box.
This function can be called within the objectTag() function, from any script in a command file, or from the Property inspector file.
NO T E
Arguments
commandFile
The commandFile argument is the name of a command file within the Configuration/ Commands folder (for example, "Format Table. htm").
Returns
Nothing.
dreamweaver. runCommand()
Availability
Dreamweaver 3.
Description
Executes the specified command; it works the same as selecting the command from a menu. If a dialog box is associated with the command, it appears and the command script blocks other edits until the user closes the dialog box. This function provides the ability to call a command from another extension file.
This function can be called within the objectTag() function, from any script in a command file, or from the Property inspector file.
N OT E
Arguments
commandFile, {commandArg1}, {commandArg2}, . . . {commandArgN}
The commandFile argument is a filename in the Configuration/Commands folder.
Command functions
301
The remaining arguments, commandArg1, commandArg2, and so on, which are optional, pass to the receiveArguments() function in the commandFile argument.
Returns
Nothing.
Example
You can write a custom Property inspector for tables that lets users get to the Format Table command from a button on the inspector by calling the following function from the button's onClick event handler:
function callFormatTable(){ dreamweaver. runCommand('Format Table. htm'); }
File manipulation functions
File manipulation functions handle creating, opening, and saving documents (including XML and XHTML), converting existing HTML documents into XHTML, and exporting CSS to external files. These functions accomplish such tasks as browsing for files or folders, creating files based on templates, closing documents, and getting information about recently opened files.
dom. cleanupXHTML()
Availability
Dreamweaver MX.
Description
This function is similar to the convertToXHTML() function, but it cleans up an existing XHTML document. You can run the cleanupXHTML() function to clean up the syntax in an entire XHTML document or in the current selection of a document.
Arguments
bWholeDoc
The bWholeDoc argument holds a Boolean value. [. . . ] Possible values are "stylelist", which is the list of styles in "All" mode; "cascade", which is the list of applicable, relevant rules in "Current" mode; "summary", which is the list of properties for the current selection in "Current" mode; and "ruleInspector", which is the editable list or grid of properties in "Current" mode. The default value is "stylelist".
Returns
A Boolean value: true if the selected style has a class selector; false otherwise.
dreamweaver. cssStylePalette. canDeleteSelectedStyle()
Availability
Dreamweaver MX.
Description
Checks the current selection to determine whether the selected style can be deleted.
Enablers
575
Arguments
{ pane }
The pane argument, which is optional, is a string that specifies the pane of the Styles Panel to which this function applies. Possible values are "stylelist", which is the list of styles in "All" mode; "cascade", which is the list of applicable, relevant rules in "Current" mode; "summary", which is the list of properties for the current selection in "Current" mode; and "ruleInspector", which is the editable list or grid of properties in "Current" mode. The default value is "stylelist".
Returns
A Boolean value: true if the selection can be deleted; false otherwise.
dreamweaver. cssStylePalette. canDuplicateSelected Style()
Availability
Dreamweaver MX.
Description
Checks the current active document to see whether the selected style can be duplicated.
Arguments
{ pane }
The pane argument, which is optional, is a string that specifies the pane of the Styles Panel to which this function applies. [. . . ]