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()

Description

This function is similar to the convertToXHTML() function, but it cleans up an existing XHTML document. This function can run on a selection within the 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. If the value is true, the cleanupXHTML() function cleans up the entire document; otherwise, this function cleans up only the selection.

Returns

An array of six integers that quantify the number of the following elements:

  • XHTML errors that Dreamweaver fixed

  • The map elements that do not have an id attribute and cannot be fixed

  • The script elements that do not have a type attribute and cannot be fixed

  • The style elements that do not have a type attribute and cannot be fixed

  • The img elements that do not have an alt attribute and cannot be fixed

  • The area elements that do not have an alt attribute and cannot be fixed

dom.convertToXHTML()

Description

Parses the HTML into a DOM tree, inserts missing items that are required for XHTML, cleans up the tree, and then writes the tree as clean XHTML. The missing directives, declarations, elements, and attributes that the convertToXHTML() function adds to the DOM tree, as necessary, include the following items:

  • An XML directive

  • A doctype declaration

  • The xmlns attribute in the html element

  • A head section

  • A title element

  • A body section

During the conversion, the dom.convertToXHTML() function converts pure HTML tags and attributes to lowercase, writes HTML tags and attributes with correct XHTML syntax, and adds missing HTML attributes where it can. This function treats third-party tags and attributes according to the settings in the Preferences dialog box.

If the document is a template, the dom.convertToXHTML() function alerts the user but does not perform the conversion.

Arguments

None.

Returns

An array of six integers that quantify the following items:

  • XHTML errors that Dreamweaver fixed

  • The map elements that do not have an id attribute and cannot be fixed

  • The script elements that do not have a type attribute and cannot be fixed

  • The style elements that do not have a type attribute and cannot be fixed

  • The img elements that do not have an alt attribute and cannot be fixed

  • The area elements that do not have an alt attribute and cannot be fixed

Example

In normal use, an extension first calls the dreamweaver.openDocument() or dreamweaver.getDocumentDOM() functions to get a reference to the document. The extension then calls the dom.getIsXHTMLDocument() function to determine whether the document is already in XHTML form. If it is not, the extension calls the dom.convertToXHTML() function to convert the document into XHTML. Then the extension calls the dreamweaver.saveDocument() function to save the converted file with a new filename.

dom.getIsXHTMLDocument()

Description

Checks a document (specifically, the <!DOCTYPE> declaration) to see whether it is XHTML.

Arguments

None.

Returns

A true value if the document is XHTML; false otherwise.

dreamweaver.browseForFileURL()

Description

Opens the specified type of dialog box with the specified label in the title bar.

Arguments

openSelectOrSave, {titleBarLabel}, {bShowPreviewPane}, {bSupressSiteRootWarnings}, {arrayOfExtensions}, {startFolder}, {allowDynamic}, {fileToLocate}

  • The openSelectOrSave argument is a string that indicates the type of dialog box as open, select, or save.

  • The titleBarLabel argument is the label that appears in the title bar of the dialog box. If this argument is omitted, Dreamweaver uses the default label that the operating system supplies.

  • The bShowPreviewPane argument is a Boolean value that indicates whether to display the Image Preview Pane in the dialog box. If the value of this argument is true, the dialog box filters for image files; if omitted, it defaults to false.

  • The bSupressSiteRootWarnings argument is a Boolean value that indicates whether to suppress warnings when the selected file is outside the site root. If this argument is omitted, it defaults to false.

  • The arrayOfExtensions argument is an array of strings. It specifies the default content for the Files of type list menu, which appears at the bottom of the dialog box. The syntax for this argument is menuEntryText|.xxx[;.yyy;.zzz]|CCCC|, where:

    • menuEntryText is the name of the file type.

    • You can specify the extensions as .xxx[;.yyy;.zzz] or CCCC:

      • .xxx specifies the filename extension for the file type. Use .yyy and .zzz to specify multiple filename extensions.

      • CCCC is the four-character file type constant for Macintosh.

       

     

    The following example provides two filters in your Select dialog, one for mp3 files and one for All Files:dw.browseForFileURL("select", "Please select an mp3",false, true, new Array("mp3 Files (*.MP3)|*.mp3||","All Files (*.*)|*.*||"));

  • The startFolder argument is a string value that can be used to specify the file URL of the folder in which the search begins. If this argument is not specified, then the search begins from the last directory that was used. This argument is optional.

  • The allowDynamic argument is a Boolean value that indicates whether to allow dynamic URLs or parameters. If the value of this argument is true, it indicates that dynamic URLs or parameters are allowed. This argument is optional.

 

  • The fileToLocate argument is a string value that is used to specify the file URL of the file you want to locate. This argument is optional.
  • The returnURL argument is a Boolean value that indicates whether to return OS specific path for Mac and Windows. This argument is optional and is set to true by default.

 

Returns

A string that contains the name of the file expressed as a file://URL.

dreamweaver.browseForFolderURL()

Description

Opens the Choose Folder dialog box with the specified label in the title bar.

Arguments

{titleBarLabel}, {directoryToStartIn}

  • The titleBarLabel argument is the label that should appear in the title bar of the dialog box. If it is omitted, the titleBarLabel argument defaults to Choose Folder.

  • The directoryToStartIn argument is the path where the folder should open, which is expressed as a file:// URL.

Returns

A string that contains the name of the folder, which is expressed as a file:// URL.

Example

The following code returns the URL of a folder:

 return dreamweaver.browseForFolderURL('Select a Folder', ¬ 
dreamweaver.getSiteRoot());

dreamweaver.closeDocument()

Description

Closes the specified document.

Arguments

documentObject

  • The documentObject argument is the object at the root of a document’s DOM tree (the value that the dreamweaver.getDocumentDOM() function returns). If the documentObject argument refers to the active document, the Document window might not close until the script that calls this function finishes executing.

Returns

Nothing.

dreamweaver.createDocument()

Description

Depending on the argument that you pass to this function, it opens a new document either in the same window or in a new window. The new document becomes the active document.

Note:

This function can be called only from the menus.xml file, a command, or the Property inspector file. If a behavior action or object tries to call this function, Dreamweaver displays an error message.

Arguments

{bOpenInSameWindow}, {type}

  • The bOpenInSameWindow argument is a Boolean value that indicates whether to open the new document in the current window. If the bOpenInSameWindow argument is a value of false, if it is omitted, or if the function is called on the Macintosh, the new document opens in a separate window.

  • The type argument specifies the type of document to create, as declared in the Dreamweaver Configuration/DocumentTypes/MMDocumentTypes.xml file as the id attribute of the documenttype tag. For example, the type argument could be "HTML", "ASP-JS", "ASP-VB", "ColdFusion", "CFC", "JSP", "ASP.NET_VB", and so on. For a complete list of possible types, see the MMDocumentTypes.xml file. If you do not specify type, the value defaults to "HTML".

Note:

You can extend the MMDocumentTypes file by adding your own document types. For information on extending document types, see Extending Dreamweaver.

Returns

The document object for the newly created document. This is the same value that the dreamweaver.getDocumentDOM()function returns.

dreamweaver.createXHTMLDocument()

Availability

Description

Depending on the argument that you pass to this function, it opens a new XHTML document either in the same window or in a new window. The new document becomes the active document. It is similar to the dreamweaver.createDocument() function.

When Dreamweaver creates a new XHTML document, it reads a file named default.xhtml, which is located in the Configuration/Templates folder, and, using the content of that file, creates an output file that contains the following skeleton declarations:

 <?xml version="1.0"> 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
 
<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
<title>Untitled Document</title> 
<meta http-equiv="Content-Type" content="text/html; charset=" /> 
</head> 
 
<body bgcolor="#FFFFFF" text="#000000"> 
 
</body> 
</html>

The default document type definition (DTD) declaration is XHTML 1.0 Transitional, rather than Strict. If the user adds a frameset to the document, Dreamweaver switches the DTD to XHTML 1.0 Frameset. Content-Type is text/html, and charset is intentionally left out of the default.xhtml file but is filled in before the user views the new document. The ?xml directive is not required if the document uses UTF-8 or UTF-16 character encoding; if it is present, it might be rendered by some older browsers. However, because this directive should be in an XHTML document, by default, Dreamweaver uses it (for both new and converted documents). Users can manually delete the directive. The ?xml directive includes the encoding attribute, which matches the charset in the Content-Type attribute.

Arguments

{bOpenInSameWindow}

  • The bOpenInSameWindow argument is a Boolean value that indicates whether to open the new document in the current window. If this value is false or omitted, or if the function is called on the Macintosh, the new document opens in a separate window.

Returns

The document object for the newly created document, which is the same value that the dreamweaver.getDocumentDOM() function returns.

dreamweaver.createXMLDocument()

Description

Creates and opens a new XML file, which is empty except for the XML directive.

Arguments

None.

Returns

The DOM of the new XML file.

Example

The following example creates a new document, which is empty except for the XML directive:

 var theDOM = dreamweaver.createXMLDocument("document");

dreamweaver.exportTemplateDataAsXML()

Description

Exports the current document to the specified file as XML. This function operates on the document that has focus, which must be a template. If you do not specify a filename argument, Dreamweaver MX opens a dialog box to request the export file string.

Arguments

{filePath}

  • The filePath argument, which is optional, is a string that specifies the filename to which Dreamweaver exports the template. Express the filePath argument as a URL file string, such as "file:///c|/temp/mydata.txt".

Returns

Nothing.

Enabler

Example

 if(dreamweaver.canExportTemplateDataAsXML()) 
{ 
    dreamweaver.exportTemplateDataAsXML("file:///c|/dw_temps/mytemplate.txt") 
}

dreamweaver.getDocumentDOM()

Description

Provides access to the objects tree for the specified document. After the tree of objects returns to the caller, the caller can edit the tree to change the contents of the document.

Arguments

{sourceDoc}

  • The sourceDoc argument must be "document", "parent", "parent.frames[number]", "parent.frames['frameName']", or a URL. The sourceDoc value defaults to "document" if you do not supply a value. These argument values have the following meanings:

    • The document value specifies the document that has focus and contains the current selection.

    • The parent value specifies the parent frameset (if the currently selected document is in a frame).

    • The parent.frames[number] and parent.frames['frameName'] values specify a document that is in a particular frame within the frameset that contains the current document.

  • If the argument is a relative URL, it is relative to the extension file.

Note:

If the argument is "document", the calling function must be the applyBehavior(), deleteBehavior(), objectTag() functions, or any function in a command or Property inspector file that can perform edits to the document.

Returns

The JavaScript document object at the root of the tree.

Examples

The following example uses the dreamweaver.getDocumentDOM() function to access the current document:

 var theDOM = dreamweaver.getDocumentDOM("document");

In the following example, the current document DOM identifies a selection and pastes it at the end of another document:

 var currentDOM = dreamweaver.getDocumentDOM('document'); 
currentDOM.setSelection(100,200); 
currentDOM.clipCopy(); 
var otherDOM = dreamweaver.openDocument(dreamweaver.¬ 
getSiteRoot() + "html/foo.htm"); 
otherDOM.endOfDocument(); 
otherDOM.clipPaste();

Note:

The openDocument() argument is used because DOM methods normally operate only on open documents. Running a function on a document that isn’t open causes a Dreamweaver error. The DOM methods that can operate only on the active document or on closed documents indicate this fact in their descriptions.

dreamweaver.getNewDocumentDOM()

Description

Provides access to the editable tree for a new, empty document. This function works in the same way as the getDocumetDOM() function, except that it points to a new document, not an existing one, and does not open the document.

Arguments

{documentType}

  • The documentType argument is a string. Its value must be a document type specified in the DocumentTypes.xml file.

Returns

A pointer to a new, empty document.

Example

The following code returns the DOM for a new, empty document:

 var theDOM = dreamweaver.getNewDocumentDOM();

dreamweaver.getRecentFileList()

Description

Gets a list of all the files in the recent files list at the bottom of the File menu.

Arguments

None.

Returns

An array of strings that represents the paths of the most recently accessed files. Each path is expressed as a file:// URL. If there are no recent files, the function returns nothing.

dreamweaver.importXMLIntoTemplate()

Description

Imports an XML text file into the current template document. This function operates on the document that has focus, which must be a template. If you do not specify a filename argument, Dreamweaver opens a dialog box to request the import file string.

Arguments

{filePath}

  • The filePath argument, which is optional, is a string that specifies the filename to which Dreamweaver imports the template. Express the filePath argument as a URL file string, such as "file:///c/temp/mydata.txt".

Returns

Nothing.

dreamweaver.newDocument()

Description

Opens a document in the current site and starts the New Document dialog box.

Arguments

{bopenWithCurSiteAndShowDialog}

  • The bopenWithCurSiteAndShowDialog argument, which is optional, has a value of true or false. Specify true to open a document with the current site and to cause the New Document dialog box to appear; false otherwise.

Returns

Nothing.

dreamweaver.newFromTemplate()

Description

Creates a new document from the specified template. If no argument is supplied, the Select Template dialog box appears.

Arguments

{templateURL}, bMaintain

  • The templateURL argument is the path to a template in the current site, which is expressed as a file:// URL.

  • The bMaintain argument is a Boolean value, true or false, that indicates whether to maintain the link to the original template.

Returns

Nothing.

dreamweaver.openDocument()

Description

Opens a document for editing in a new Dreamweaver window and gives it the focus. For a user, the effect is the same as selecting File > Open and selecting a file. If the specified file is already open, the window that contains the document comes to the front. The window that contains the specified file becomes the currently selected document. In Dreamweaver 2, if Check In/Check Out is enabled, the file is checked out before it opens. In Dreamweaver 3 and later, you must use dreamweaver.openDocumentFromSite() to get this behavior.

Note:

This function will cause an error if called from Behavior action or object files.

Arguments

fileName

  • The fileName argument is the name of the file to open, which is expressed as a URL. If the URL is relative, it is relative to the file that contains the script that called this function.

Returns

The document object for the specified file, which is the same value that the dreamweaver.getDocumentDOM() function returns.

dreamweaver.openDocumentFromSite()

Description

Opens a document for editing in a new Dreamweaver window and gives it the focus. For a user, the effect is the same as double-clicking a file in the Site panel. If the specified file is already open, the window that contains the document comes to the front. The window that contains the specified file becomes the currently selected document.

Note:

This function cannot be called from Behavior action or object files because it causes an error.

Arguments

fileName

  • The fileName argument is the file to open, which is expressed as a URL. If the URL is relative, it is relative to the file that contains the script that called this function.

Returns

The document object for the specified file, which is the same value that the dreamweaver.getDocumentDOM() function returns.

dreamweaver.openInFrame()

Description

Opens the Open In Frame dialog box. When the user selects a document, it opens into the active frame.

Arguments

None.

Returns

Nothing.

Enabler

dreamweaver.releaseDocument()

Description

Explicitly releases a previously referenced document from memory.

Documents that are referenced by the dreamweaver.getObjectTags(), dreamweaver.getObjectRefs(), dreamweaver.getDocumentPath(), or dreamweaver.getDocumentDOM() functions are automatically released when the script that contains the call finishes executing. If the script opens many documents, you must use this function to explicitly release documents before finishing the script to avoid running out of memory.

Note:

This function is relevant only for documents that were referenced by a URL, are not currently open in a frame or document window, and are not extension files. Extension files are loaded into memory at startup and are not released until you quit Dreamweaver.

Arguments

documentObject

  • The documentObject argument is the object at the root of a document’s DOM tree, which is the value that the dreamweaver.getDocumentDOM() function returns.

Returns

Nothing.

dreamweaver.revertDocument()

Description

Reverts the specified document to the previously saved version.

Arguments

documentObject, warn

  • The documentObject argument is the object at the root of the DOM tree of the document, which is the value that the dreamweaver.getDocumentDOM() function returns.

  • The warn argument is a Boolean value that specifies whether to warn the users that unsaved changes will be discarded. If not supplied, this value defaults to true.

Returns

A Boolean value: true if Dreamweaver must warn the user; false otherwise.

Enabler

dreamweaver.saveAll()

Description

Saves all open documents, opening theSave As dialog box for any documents that have not been saved previously.

Arguments

None.

Returns

Nothing.

Enabler

dreamweaver.saveDocument()

Description

Saves the specified file on a local computer.

Note:

In Dreamweaver 2, if the file is read-only, Dreamweaver tries to check it out. If the document is still read-only after this attempt, or if it cannot be created, an error message appears.

Arguments

documentObject, {fileURL}

  • The documentObject argument is the object at the root of a document’s DOM tree, which is the value that the dreamweaver.getDocumentDOM() function returns.

  • The fileURL argument, which is optional, is a URL that represents a location on a local computer. If the URL is relative, it is relative to the extension file. In Dreamweaver 2, this argument is required. If the fileURL argument is omitted in Dreamweaver 4, the file is saved to its current location if it has been previously saved; otherwise, a Save dialog box appears.

Returns

A Boolean value that indicates success (true) or failure (false).

Enabler

dreamweaver.saveDocumentAs()

Description

Opens the Save As dialog box.

Arguments

documentObject

  • The documentObject argument is the object at the root of a document’s DOM tree, which is the value that the dreamweaver.getDocumentDOM() function returns.

Returns

Nothing.

dreamweaver.saveDocumentAsTemplate()

Description

Opens the Save As Template dialog box.

Arguments

documentObject, {fileName}

  • The documentObject argument is the object at the root of a document’s DOM tree, which is the value that dreamweaver.getDocumentDOM() returns.

  • The fileName argument, which is optional, is the name of the file to open, expressed as an absolute URL.

Returns

Nothing.

Enabler

dreamweaver.saveFrameset()

Description

Saves the specified frameset or opens the Save As dialog box if the frameset has not previously been saved.

Arguments

documentObject

  • The documentObject argument is the object at the root of a document’s DOM tree, which is the value that the dreamweaver.getDocumentDOM() function returns.

Returns

Nothing.

Enabler

dreamweaver.saveFramesetAs()

Description

Opens the Save As dialog box for the frameset file that includes the specified DOM.

Arguments

documentObject

  • The documentObject argument is the object at the root of a document’s DOM tree, which is the value that the dreamweaver.getDocumentDOM() function returns.

Returns

Nothing.

Enabler

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy