Global document functions

Global document functions act on an entire document. They check spelling, check target browsers, set page properties, and determine correct object references for elements in the document.

dom.checkSpelling()

Availability

Dreamweaver 3.

Description

Checks the spelling in the document, opening the Check Spelling dialog box if necessary, and notifies the user when the check is complete.

Arguments

None.

Returns

Nothing.

dom.checkTargetBrowsers()

Availability

Dreamweaver 3.

Description

Runs a target browser check on the document. To run a target browser check on a folder or group of files, see "site.checkTargetBrowsers()" on page 770.

Arguments

None.

Returns

Nothing.

dom.getParseMode()

Availability

Dreamweaver MX 2004

Description

Gets the current parsing mode of the document, which controls how the document is validated and whether it shows up in the main document window as HTML.

Arguments

None.

Returns

A string that specifies the current parsing mode: "html", "xml", "css", or "text".

dom.hideInfoMessagePopup()

Availability

Dreamweaver MX 2004.

Description

Hides the tooltip-like message, if it is visible, for the document window.

Arguments

None.

Returns

Nothing.

See also

"dom.showInfoMessagePopup()" on page 828.

dom.runValidation()

Availability

Dreamweaver MX, optional arguments added in Dreamweaver MX 2004.

Description

Runs the Validator on a single specified document (this function is similar to site.runValidation()). The Validator checks the document for conformance with the language specified in the document doctype (such as HTML 4.0 or HTML 3.2) and the language specified by the server model (such as ColdFusion or ASP). If the document has no doctype, then the Validator uses the language setting specified in the Validator section of the Preferences dialog box.

Arguments

 {controlString}, {bOpenResultsWindow}, {bShowInfoMessage} 

• The controlString argument is an optional string with four possible values: an empty string, "xml", "auto-explicit", or "auto-implicit".

  • If the argument is an empty string, the Validator performs a default validation. If the argument is "xml", the Validator validates the document as XML.

  • If the argument is "auto-explicit" or "auto-implicit", Dreamweaver performs an automatic validation (also known as an inline validation), which underlines errors in the Code view instead of opening the Validation results window (see "dom.source.getValidationErrorsForOffset()" on page 1037 and "dom.getAutoValidationCount()" on page 1029).

  • If the controlString argument is "auto-explicit", Dreamweaver will prompt the user to save an unsaved document before running the validation.

  • If the controlString argument is "auto-implicit", the validation will fail without notifying the user that the current document is unsaved.

  NOTE

  An automatic validation (defined by the controlString value "auto-explicit" or "auto-implicit") is currently available only for a Target Browser Check.

  
  

• The bOpenResultsWindow argument is an optional Boolean value: true opens the Validation results window; false otherwise. The default value is true.

• The bShowInfoMessage argument is used only when the controlString argument is defined as "auto-explicit" or "auto-implicit". The bShowInfoMessage argument is a Boolean value: true shows an informational message under the toolbar item, DW_ValidatorErrors, with the number of errors found; false displays nothing. The default value is false.

Returns

The Validation results window object.

Example

The following example runs a regular validation when the user selects the File > Check Page > Validate Markup menu option (or Validate Current Document in the Validation panel):

 dw.getDocumentDOM().runValidation(''); 

The following example prompts the user to save an unsaved document, runs an automatic validation, does not open the Validation results window, but does show the total number of errors over the document toolbar button for DW_ValidatorErrors:

 dw.getDocumentDOM().runValidation('auto-explicit', false, true); 

The following example does not prompt the user to save an unsaved document. If the document has not been saved, the validation will not start. If the document has been saved, Dreamweaver runs an automatic validation, does not open the Validation results window, and does not indicate the total number of errors encountered on the document toolbar:

 dw.getDocumentDOM().runValidation('auto-implicit', false); 

dom.showInfoMessagePopup()

Availability

Dreamweaver MX 2004.

Description

Shows a tooltip-like message in the document window or under a toolbar item.

Arguments

 location, message, timeout 

• The location argument is a string that specifies a toolbar item, or is an empty string, or is one of the following keywords: "top", "topright", "right", "bottomright", "bottom", "bottomleft", "left", or "topleft". The tooltip is placed against the specified edge or corner and is centered. An empty string causes it to be centered in the document. To specify a toolbar item, use "toolbar:toolbarID:itemID", where the toolbar ID and toolbar item ID match the IDs in the toolbars.xml file.

• The message argument is a string that contains the message.

• The timeout argument is a number that specifies the milliseconds for which to display the message. The default is 0. If the value is 0, the message stays indefinitely. Dreamweaver automatically dismisses it if the user clicks it or switches documents, or if the time out expires.

Returns

Nothing.

Example

The following example displays two tooltip messages. The first line of code displays the message "This message is in the center" in the center of the document. The second call to showInfoMessagePopup() displays the tooltip message "Don't forget the title for the Window" for the Title text edit box, which has the ID DW_SetTitle, on the toolbar with the ID DW_Toolbar_Main.

 dw.getDocumentDOM.showInfoMessagePopup('', 'This message is in the center', 5000); dw.getDocumentDOM.showInfoMessagePopup('toolbar:DW_Toolbar_Main:DW_SetTitle', 'Don't  forget the title for the window', 5000); 

See also

"dom.hideInfoMessagePopup()" on page 826.

dom.showPagePropertiesDialog()

Availability

Dreamweaver 3.

Description

Opens the Page Properties dialog box.

Arguments

None.

Returns

Nothing.

dreamweaver.doURLDecoding()

Availability

Dreamweaver MX.

Description

Uses the internal Dreamweaver URL decoding mechanism to decode special characters and symbols in URL strings. For example, this function decodes %20 to a space character and the name &quot to ".

Arguments

 inStr 

• The inStr argument is the string to decode.

Returns

A string that contains the decoded URL.

Example

The following example calls dw.doURLDecoding() to decode the special characters in its argument and store the resulting string in outstr:

 outStr = dreamweaver.doURLDecoding("http://maps.yahoo.com/py/ddResults .py?Pyt=Tmap&tarname=&tardesc=&newname=&newdesc=&newHash=&newTHash=&newSts=&newTSts=&tlt=&tln=&slt=&sln=&newFL=Use+Address+Below&newaddr=2000+Shamrock+Rd&newcsz=Metroo+Park%2C+CA&newcountry=us&newTFL=Use+Address+Below&newtaddr=500+El+Camino&newtcsz=Santa+Clara%2C+CA&newtcountry=us&Submit=Get+Directions") 

dreamweaver.getElementRef()

Availability

Dreamweaver 2.

Description

Gets the Netscape Navigator or Internet Explorer object reference for a specific tag object in the DOM tree.

Arguments

 NSorIE, tagObject 

• The NSorIE argument must be either "NS 4.0" or "IE 4.0". The DOM and rules for nested references differ in Netscape Navigator 4.0 and Internet Explorer 4.0. This argument specifies for which browser to return a valid reference.

• The tagObject argument is a tag object in the DOM tree.

Returns

A string that represents a valid JavaScript reference to the object, such as document.layers['myLayer']. The string is subject to the following conditions:

• Dreamweaver returns correct references for Internet Explorer for A, AREA, APPLET, EMBED, DIV, SPAN, INPUT, SELECT, OPTION, TEXTAREA, OBJECT, and IMG tags.

• Dreamweaver returns correct references for Netscape Navigator for A, AREA, APPLET, EMBED, LAYER, ILAYER, SELECT, OPTION, TEXTAREA, OBJECT, and IMG tags, and for absolutely positioned DIV and SPAN tags. For DIV and SPAN tags that are not absolutely positioned, Dreamweaver returns "cannot reference <tag>".

• Dreamweaver does not return references for unnamed objects. If an object does not contain either a NAME or an ID attribute, Dreamweaver returns "unnamed <tag>". If the browser does not support a reference by name, Dreamweaver references the object by index (for example, document.myform.applets[3]).

• Dreamweaver returns references for named objects that are contained in unnamed forms and layers (for example, document.forms[2].myCheckbox).

dreamweaver.getObjectRefs() (deprecated)

Availability

Dreamweaver 1; deprecated in 3.

Description

This function scans the specified document for instances of the specified tags or, if no tags are specified, for all tags in the document and formulates browser-specific references to those tags. This function is equivalent to calling getElementsByTagName() and then calling dreamweaver.getElementRef() for each tag in the nodelist.

Arguments

 NSorIE, sourceDoc, {tag1}, {tag2},...{tagN} 

• The NSorIE argument must be either "NS 4.0" or "IE 4.0". The DOM and rules for nested references differ in Netscape Navigator 4.0 and Internet Explorer 4.0. This argument specifies for which browser to return a valid reference.

• The sourceDoc argument must be "document", "parent", "parent.frames[number]", "parent.frames['frameName']", or a URL. The document value specifies the document that has the focus and contains the current selection. The parent value specifies the parent frameset (if the currently selected document is in a frame), and parent.frames[number] and parent.frames['frameName'] 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.

• The third and subsequent arguments, if supplied, are the names of tags (for example, "IMG", "FORM", or "hr").

Returns

An array of strings where each array is a valid JavaScript reference to a named instance of the requested tag type in the specified document (for example, "document.myLayer.document.myImage") for the specified browser:

• Dreamweaver returns correct references for Internet Explorer for A, AREA, APPLET, EMBED, DIV, SPAN, INPUT, SELECT, OPTION, TEXTAREA, OBJECT, and IMG tags.

• Dreamweaver returns correct references for Netscape Navigator for A, AREA, APPLET, EMBED, LAYER, ILAYER, SELECT, OPTION, TEXTAREA, OBJECT, and IMG tags, and for absolutely positioned DIV and SPAN tags. For DIV and SPAN tags that are not absolutely positioned, Dreamweaver returns "cannot reference <tag>".

• Dreamweaver does not return references for unnamed objects. If an object does not contain either a NAME or an ID attribute, Dreamweaver returns "unnamed <tag>". If the browser does not support a reference by name, Dreamweaver references the object by index (for example, document.myform.applets[3]).

• Dreamweaver does return references for named objects that are contained in unnamed forms and layers (for example, document.forms[2].myCheckbox).

When the same list of arguments passes to getObjectTags(), the two functions return arrays of the same length and with parallel content.

dreamweaver.getObjectTags() (deprecated)

Availability

Dreamweaver1; deprecated in 3.

Description

This function scans the specified document for instances of the specified tags or, if no tags are specified, for all tags in the document. This function is equivalent to calling getElementsByTagName() and then getting outerHTML for each element in the nodelist.

Arguments

 sourceDoc, {tag1}, {tag2},...{tagN} 

• The sourceDoc argument must be "document", "parent", "parent.frames[number]", "parent.frames['frameName']", or a URL. The document value specifies the document that has the focus and contains the current selection. The parent value specifies the parent frameset (if the currently selected document is in a frame), and parent.frames[number] and parent.frames['frameName'] 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.

• The second and subsequent arguments, if supplied, are the names of tags (for example, "IMG", "FORM", "HR").

Returns

An array of strings where each array is the source code for an instance of the requested tag type in the specified document.

• If one of the tag arguments is LAYER, the function returns all LAYER and ILAYER tags and all absolutely positioned DIV and SPAN tags.

• If one of the tag arguments is INPUT, the function returns all form elements. To get a particular type of form element, specify INPUT/TYPE, where TYPE is button, text, radio, checkbox, password, textarea, select, hidden, reset, or submit.

When the same list of arguments passes to getObjectRefs(), the two functions return arrays of the same length.

Example

dreamweaver.getObjectTags("document", "IMG"), depending on the contents of the active document, might return an array with the following items:

• "<IMG src="/books/4/533/1/html/2//images/dot.gif" WIDTH="10" HEIGHT="10" NAME="bullet">"

• "<IMG src="/books/4/533/1/html/2/header.gif" WIDTH="400" HEIGHT="32" NAME="header">"

• "<IMG src="/books/4/533/1/html/2/971208_nj.jpg" WIDTH="119" HEIGHT="119" NAME="headshot">"

dreamweaver.getPreferenceInt()

Availability

Dreamweaver MX.

Description

Lets you retrieve an integer preference setting for an extension.

Arguments

 section, key, default_value 

• The section argument is a string that specifies the preferences section that contains the entry.

• The key argument is a string that specifies the entry of the value to retrieve.

• The default_value argument is the default value that Dreamweaver returns if it cannot find the entry. This value must be an unsigned integer in the range 0 through 65,535 or a signed integer in the range -32,768 through 32,767.

Returns

Integer value of the specified entry in the specified section or the default value if the function does not find the entry. Returns 0 if the value of the specified entry is not an integer.

Example

The following example returns the integer value of the Snap Distance setting in the My Extension section of Preferences. If there is no MyExtension section or no Snap Distance entry, the function returns the specified default value of 0.

 var snapDist; //default value if entry not found snapDist = dreamweaver.getPreferenceInt("My Extension", "Snap Distance", 0); 

dreamweaver.getPreferenceString()

Availability

Dreamweaver MX.

NOTE

To access the preferences for sites, you must have version 7.0.1. Check dw.appVersion for the correct version before accessing site information.

Description

Lets you retrieve a string preference setting that you stored for an extension.

Arguments

 section, key, default_value 

• The section argument is a string that specifies the preferences section that contains the entry.

• The key argument is a string that specifies the value to retrieve.

• The default_value argument is the default string value that Dreamweaver returns if it cannot find the entry.

Returns

The requested preference string, or if the string cannot be found, the default value.

Example

The following example returns the String value of the Text Editor setting in the My Extension section of Preferences. If there is no MyExtension section or no Text Editor entry, the function returns the default value specified by the variable txtEditor.

 var txtEditor = getExternalTextEditor(); //set default text Editor value txtEditor = dreamweaver.getPreferenceString("My Extension", "Text Editor", txtEditor); 

dreamweaver.setPreferenceInt()

Availability

Dreamweaver MX.

Description

Lets you set an integer preference setting for an extension. This setting is stored with Dreamweaver preferences when Dreamweaver is not running.

Arguments

 section, key, new_value 

• The section argument is a string that specifies the preferences category in which the option is set. If the category does not exist, Dreamweaver creates it.

• The key argument is a string that specifies the category option that the function sets. If the option does not exist, Dreamweaver creates it.

• The new_value argument is an integer that specifies the value of the category option.

Returns

A TRue value if successful; false otherwise.

Example

The following example sets the Snap Distance entry to the value of the variable snapDist in the My Extension category of Preferences:

 var snapDist = getSnapDistance(); if(snapDist > 0) {   dreamweaver.setPreferenceInt("My Extension", "Snap Distance", snapDist); } 

dreamweaver.setPreferenceString()

Availability

Dreamweaver MX.

NOTE

To access the preferences for sites, you must have version 7.0.1. Check dw.appVersion for the correct version before accessing site information.

Description

Lets you write a string preference setting for an extension. This setting is stored with Dreamweaver preferences when Dreamweaver is not running.

Arguments

 section, key, new_value 

• The section argument is a string that specifies the Preferences category in which the option is set. If the category does not exist, Dreamweaver creates it.

• The key argument is a string that specifies the category option that the functions sets. If the category option does not exist, Dreamweaver creates it.

• The new_value argument is a string that specifies the value of the category option.

Returns

A true value if successful; false otherwise.

Example

 var txtEditor = getExternalTextEditor(); dreamweaver.setPreferenceString("My Extension", "Text Editor", txtEditor); 

dreamweaver.showTargetBrowsersDialog()

Availability

Dreamweaver MX 2004.

Description

Opens the Target Browsers dialog box. The Target Browsers dialog box lets a user specify which browser versions the Browser Target Check feature should use for checking the current page's browser compatibility issues.

Arguments

None.

Returns

Nothing.