This reference covers the objects, properties, and methods (functions) in the Expression Web 4 JavaScript API. To avoid any confusion as you are using this reference, the following conventions are followed.
Each object in the JavaScript API has its own heading that identifies the object name. Even though all objects in the Expression Web JavaScript API share the xweb
root namespace, the xweb
namespace is included in code samples to avoid any confusion with objects in the browser’s DOM.
Properties and methods of each object are documented in subheadings of each object. When code samples are given, the following syntax is used.
• Samples of method calls use the syntax object.method(param)
. Optional parameters appear in square brackets as in object.method(param1, [param2])
.
• When a parameter has more than one possible explicit value, each possible value is separated by a vertical bar as in value1|value2
.
Properties contain syntax, return types, and often an Information section with more information about the property. Methods contain syntax, parameters (if applicable), return value, and often contain an Information section with more information about the method.
Properties of an object are listed first, followed by methods. Properties and methods appear in alphabetical order.
As with the other chapters of this book, the reference contains numerous notes and tips. Cautions are also included when warranted.
This reference does not include material on the DOM’s window
or document
objects. For information on the browser’s DOM, see Microsoft’s Scripting Internet Explorer guide located at http://msdn.microsoft.com/en-us/library/dd464669(v=VS.85).aspx.
Code examples in this chapter will often refer to explicit files names. This was done for clarify of the examples, but in most cases, your add-in will get file names from user input or from programmatically accessing the current site.
XWEB.APPLICATION
ObjectThe xweb.application
object refers to the Expression Web application itself. In addition to being used for manipulating files and common dialogs within the Expression Web application, it is also used when opening and closing modal add-in dialogs.
xweb.application.version
PropertyThe version
property returns a string that identifies the version of Expression Web.
xweb.application.version;
The full version number is returned as a string.
The version
property is read-only.
The following code example checks the version of Expression Web. If the version of Expression Web isn’t what’s required for the add-in, an alert is displayed notifying the user to download and install the latest service pack.
xweb.application.chooseFile
MethodThe chooseFile
method displays a Browse dialog (commonly referred to as a file picker).
xweb.application.chooseFile(label, [filter]);
The label
parameter is a string that specifies the text to display on the filter drop-down in the Browse dialog. The filter
parameter allows you to specify which file types are displayed in the browse dialog.
The full path and filename of the file that is selected in the dialog as a string. If no file is selected or if Cancel is clicked in the Browse dialog, returns null
.
The syntax for the filter
parameter is *.ext
, and multiple filters can be applied by separating each with a comma.
The following example displays a Browse dialog configured for selecting a web file.
Figure 39.1 shows the appearance of the Browse dialog that is launched by this code. Notice that the label on the filter drop-down reflects the value of the label
parameter.
Figure 39.1. The Browse dialog shown here was launched using the chooseFile
method.
The first time that chooseFile
is called during an Expression Web session, it opens at an initial location of %windir%System32
. Thereafter, it opens in the same directory that was displayed when it was last closed until Expression Web is closed and reopened.
There is no way to specify the initial directory displayed in the Browse dialog when using the chooseFile
method.
xweb.application.endDialog
MethodThe endDialog
method closes a modal dialog that was opened using the showModalDialog
method.
xweb.application.endDialog(boolValue);
The boolValue
parameter is passed back to the showModalDialog
method that launched the dialog and is set as the return value of that method. It can either be a Boolean (true
or false
) or a numeric value. Numeric values will be implicitly converted to a Boolean. A value of 0
represents false
, and any other number (including negative numbers) represents true
.
Nothing.
If no value is provided for the boolValue
parameter, an invalid procedure call error occurs.
In the example, the call to showModalDialog
returns false
if the user clicks OK and true
if the user clicks Cancel. See the code example for showModalDialog
for more information.
xweb.application.handleEvent
MethodThe handleEvent
method tells the Expression Web application to handle the event that is passed to it. This method is commonly used with add-ins that provide hotkey functionality in order to hand off the handling of the keydown
event to Expression Web.
xweb.application.handleEvent(event);
The event
parameter is a JavaScript event (IHTMLEventObj
) object.
Returns true
if the event is handled by Expression Web. Otherwise, false
.
The handleEvent
method only handles the keydown
event.
In the example code, the HandleEvent
function executes when a key is pressed while inside the text box. The HandleEvent
checks to see whether the Ctrl key is pressed and then handles the event based on which key was pressed. If the key that was pressed is not a hotkey handled by the add-in, the event is passed to Expression Web so that it can handle it. Without the call to xweb.application.handleEvent
, the add-in would have swallowed the event without Expression Web having an opportunity to handle it.
xweb.application.newDocument
MethodThe newDocument
method performs the same action as clicking the New Document button in the Expression Web interface. However, you can specify a particular Doctype declaration by passing in an optional parameter.
The newDocument
method sets the focus to the newly created document.
xweb.application.newDocument([doctype]);
The optional doctype
parameter is a string that specifies the doctype for the new document.
Returns an xweb.document
object representing the newly created page.
The value of the doctype
parameter can be one of the following:
• HTML 4.01 Strict
• HTML 4.01 Transitional
• XHTML 1.0 Frameset
• XHTML 1.0 Strict
• XHTML 1.0 Transitional
• XHTML 1.1
If you don’t specify a doctype
parameter, Expression Web creates the page using the Document Type Declaration setting on the Authoring tab of the Page Editor Options dialog.
Microsoft’s documentation on the newDocument
method states that all the Doctype values that appear on the Authoring tab of the Page Editor Options dialog are valid for the doctype
parameter. However, this is not true. You must use one of the values previously stated.
If the value that you specify for doctype
is not one of the values previously stated, document creation fails and newDocument
returns null
.
For more information on the xweb.document object, see “xweb.document
Object,” p. 715, in this chapter.
The following code creates a new file with an XHTML 1.0 Transitional doctype. Before it does so, it determines the root-relative path of the active document and uses that path to reactivate the document after the new file is created.
This code relies on the fact that when openDocument
is called on a document that is already open, the document is activated.
xweb.application.openDocument
MethodThe openDocument
method opens a web page.
xweb.application.openDocument(URI);
The URI
parameter is the URI of the document to be opened.
Returns an xweb.document
object.
The URI
parameter must be preceded with site:
. If the URI
parameter points to a file that is not a web page (for example, a .css
, .xml
, .txt
file and so forth), a valid xweb.document
will not be returned. However, the open operation will succeed. Therefore, an add-in should not assume a valid xweb.document
object has been returned by openDocument
.
The following example illustrates the recommended way to use the openDocument
method.
If the fileURI
refers to a file that is already open in Expression Web, the tab for the already opened file will be activated.
The following example opens a file and checks to ensure that the file is a web page.
In the preceding example, if fileURI
contains a URI to a file that is not a web page, doc.name
returns null
. In such a case, even though the file will be opened in Expression Web, the doc
variable will not contain a valid xweb.document
object.
xweb.application.refreshFileListing
MethodThe refreshFileListing
method refreshes the Folder List in Expression Web.
xweb.application.refreshFileListing();
None.
If successful in refreshing the Folder List, refreshFileListing
returns true
. Otherwise, it returns false
.
The refreshFileListing
method only works correctly if the Folder List has the focus when it is called. Therefore, the recommended way of refreshing the Folder List using an add-in is to enable legacy mode in the add-in’s manifest and call xweb.legacyapp.ActiveWeb.Refresh(true)
.
The following example refreshes the Folder List. Note that the first example only works when the Folder List has focus, so you’ll likely use the second example in most cases.
xweb.application.setActiveDocument
MethodThe setActiveDocument
method activates the xweb.document
that is passed to it.
xweb.application.setActiveDocument(doc);
The doc
parameter is the xweb.document
object to activate.
Returns true
if the document is activated. Otherwise, returns false
.
The following example opens two documents. It then activates the first document that was opened.
xweb.application.setPanelVisibility
MethodThe setPanelVisibility
method allows you to show or hide panels within the Expression Web interface.
xweb.application.setPanelVisibility(panel, "hidden"|"visible");
The panel
parameter is a case-sensitive string that specifies the ID of the panel that is being shown or hidden. The second parameter sets the visibility of the panel and is either "hidden"
or "visible"
.
Returns true
if the panel was found. Otherwise, returns false
.
An add-in’s panel ID is defined in the add-in’s manifest. Table 39.1 lists the IDs of Expression Web’s built-in panels.
Table 39.1. Panel IDs for Built-In Panels
The following example sets the visibility of the Manage Styles panel.
xweb.application.setPanelVisibility("TaskPane_ManageStyles", "visible");
The setPanelVisibility
method does not affect the focus of a panel. If the panel indicated by the panel
parameter is docked with other panels but is not the active panel, making the panel visible with setPanelVisibility
will not activate the panel’s tab.
When docked panels are shown using the setPanelVisibility
method, they appear in the same position they were in before being hidden.
The return value of setPanelVisibility
does not reflect the state of the panel. If a panel is already visible and setPanelVisibility
makes the panel visible, it still returns true
even though visibility wasn’t changed.
If more than one panel shares the same ID, setPanelVisibility
sets the visibility of the first panel encountered with the specified ID.
xweb.application.showModalDialog
MethodThe showModalDialog
method opens a modal dialog.
xweb.application.showModalDialog(dialogURI, dialogTitle, [dialogOptions];
The dialogURI
parameter refers to the web page to be displayed in the dialog and is relative to the root of the add-in’s folder. The dialogTitle
parameter is a string displayed in the title bar of the dialog. dialogOptions
is an optional parameter that defines the features of the dialog window.
You can also set the visibility of a panel added by an add-in. You’ll need to check the manifest of the add-in to determine the panel’s ID.
A Boolean. The return value for showModalDialog
is set by the endDialog
method.
It is not necessary to precede dialogURI
with addin:
.
The dialogTitle
parameter is not optional, but you may specify either an empty string or null
, in which case the title bar of the dialog will be blank.
The dialogOptions
parameter includes an optional list of semicolon-delimited options for the dialog in the format option:value
. The following options are available:
• dialogHeight
—The height of the dialog as a numeric value in pixels. Do not include a unit of measure.
• dialogWidth
—The width of the dialog as a numeric value in pixels. Do not include a unit of measure.
• resizable
—Determines whether the dialog can be resized by dragging the edges of the window. To make the dialog resizable, valid values are yes
, 1
, true
, or on
. To prevent the window from being resized, valid values are no
, 0
, false
, or off
. Dialogs are not resizable by default.
• scroll
—Specifies whether the dialog should have scrollbars. Valid values are yes
, 1
, true
, or on
to enable scrollbars and no
, 0
, false
, or off
to disable scrollbars. Scrollbars are enabled by default.
Vertical scrollbars are always visible. Horizontal scrollbars are only visible when the width of the dialog’s content exceeds the width of the dialog.
The following example opens a modal dialog displaying the content of dialog.htm
. The dialog has a title of Options Dialog
, is 200 pixels high, is 400 pixels wide, and has no scroll bars.
var ret = xweb.application.showModalDialog("dialog.htm", "Options Dialog",
"dialogHeight:200;dialogWidth:400;scroll:no");
XWEB.APPLICATION.SETTINGS
ObjectThe settings
object is used to store and retrieve user-specific settings for an add-in. Settings are stored in a user.config
file located inside the add-in’s folder.
xweb.application.settings.read
MethodThe read
method reads a setting.
xweb.application.settings.read(setting);
The setting
parameter is a string that identifies the setting to be retrieved.
Returns the value of the specified setting.
If the setting you attempt to read does not exist, the read
method returns undefined
.
The following example reads a setting called ConfirmOnClose
. If the setting is true, a confirmation message is displayed before a document is closed. Otherwise, the document is closed without a prompt.
xweb.application.settings.write
MethodThe write
method stores a setting and value.
xweb.application.settings.write(setting, value);
The setting
parameter is a string that identifies the setting. The value
parameter is the value to be stored.
Nothing.
The value
parameter must be a primitive data type such as a number, a Boolean value, or a string.
The write
method has no return value. Therefore, if you want to ensure that the value was written, use the read
method to check the value.
If the setting specified by the setting
parameter already exists, the existing value is overridden by the new value.
The following example writes a setting called ConfirmOnClose
and sets it based on a checkbox called chkConfirm
.
XWEB.DEVELOPER
ObjectThe xweb.developer
object contains methods that write information to the debug console for add-ins.
For methods of the developer
object to succeed, you must set the developer
attribute of the addin
element in the add-in manifest to yes
.
xweb.developer.write
MethodThe write
method writes a value to the debug console for an add-in.
xweb.developer.write(value);
The value
parameter is the value to be written to the debug console.
Undefined.
Subsequent calls to the write
method append new values to the existing value. If a line break is desired between values, use the writeLine
method instead.
The debug console can be accessed from the Panels menu. A debug console is available for each add-in running in developer mode. The name of the debug console panel reflects the name of the add-in’s folder and not the name of the add-in.
The following example uses the xweb.developer.write
method to log output to the debug console.
xweb.developer.writeLine
MethodThe writeLine
method is equivalent to the write
method except that a line break is added after each value.
xweb.developer.writeLine(value);
The value
parameter is written to the debug console, followed by a line break.
Undefined.
XWEB.DOCUMENT
ObjectThe xweb.document
object represents a web page in Expression Web. The properties and methods of the xweb.document
object provide the capability to get information about the associated page and to manipulate its content.
The xweb.document
object refers to a web page with a valid DOM. Other files types (such as .css
, .xml
, and so forth) do not have a valid xweb.document
object associated with them.
Don’t confuse xweb.document
with window.document
. The xweb.document
object represents a web page open in Expression Web. The window.document
object represents the document in an add-in’s panel or dialog.
For more information on the xweb.document.synchronizeViews
method, see “xweb.document.synchronizeViews
Method,” p. 733, in this chapter.
When used without explicitly specifying the xweb
namespace, the document
object refers to window.document
.
Properties and methods of the xweb.document
object may fail or return incorrect values if the document contains unsaved changes. To prevent this, always call synchronizeViews
on the document
object prior to accessing properties and methods of the xweb.document
object.
The xweb.document
object refers to the active document in Expression Web. However, an xweb.document
object can also be referenced by a variable. It is possible to access properties and methods of the xweb.document
object without that xweb.document
being the active page in Expression Web. The code in Listing 39.1 uses two variables, each of which contains an xweb.document
object, and code is modified in the document that is not active in Expression Web.
Listing 39.1. Example of xweb.document
Usage
When the code in Listing 39.1 runs, the news.htm
file is modified by adding a new script reference. However, the faq.htm
file remains the active document in Expression Web. In other words, it’s not necessary to activate a document to manipulate it using the properties and methods of the xweb.document
object. The xweb.document
object references the active document in memory. If anything causes the active document in Expression Web to change, the xweb.document
object reference will change as well. The following example illustrates this concept.
xweb.document.anchors
PropertyThe anchors
property locates all anchors on the document.
xweb.document.anchors;
An array of xweb.document.htmlElement
objects is returned. If no anchors are defined in the page, the anchors
property returns null
.
The anchors
property is read-only.
The following example gets a reference to the first anchor in the active document and displays the name
attribute of that anchor in an alert.
xweb.document.applets
PropertyThe applets
property locates all applet
elements in the document.
xweb.document.applets;
Returns an array of xweb.document.htmlElement
objects, each representing an applet
element in the document. If no applet
elements are present in the document, the applets
property returns null
.
The applets
property is read-only.
xweb.document.embeds
PropertyThe embeds
property locates all embed
elements in the document.
xweb.document.embeds;
Returns an array of xweb.document.htmlElement
objects, each representing an embed
element in the document. If no embed
elements are present in the document, the embeds
property returns null
.
The embeds
property is read-only.
xweb.document.filename
PropertyThe filename
property returns the filename and extension of the document.
xweb.document.filename;
The filename and extension as a string.
The filename
property does not return any part of the path of the document. Only the filename and extension are returned by the filename
property.
If a site is not open in Expression Web, the filename
property returns undefined
.
To obtain a relative path to a document, append the value of filename
to the value returned by the pathFromSiteRoot
property.
The filename
property always returns undefined
when the site open in Expression Web is not a disk-based site.
For more information on the xweb.document.pathFromSiteRoot
property, see “xweb.document.pathFromSiteRoot
Property,” p. 722, in this chapter.
The filename
property is read-only.
The following example determines the relative path of the active document from the root of the site.
var relPath = xweb.document.pathFromSiteRoot + '/' + xweb.document.filename;
xweb.document.forms
PropertyThe forms
property locates all form
elements in the document.
xweb.document.forms;
Returns an array of xweb.document.htmlElement
objects, each representing a form
element in the document. If no form
elements are present in the document, the forms
property returns null
.
The forms
property is read-only.
xweb.document.frames
PropertyThe frames
property locates all frame
elements in the document.
xweb.document.frames;
Returns an array of xweb.document.htmlElement
objects, each representing a frame
element in the document. If no frame
elements are present in the document, the frames
property returns null
.
The frames
property is read-only.
xweb.document.images
PropertyThe images
property locates all img
elements in the document.
xweb.document.images;
Returns an array of xweb.document.htmlElement
objects, each representing an img
element in the document. If no img
elements are present in the document, the images
property returns null
.
The images
property is read-only.
xweb.document.isXHTML
PropertyThe isXHTML
property determines whether the document is an XHTML document.
xweb.document.isXHTML;
Returns a Boolean value indicating whether the document contains an XHTML doctype. If no doctype exists in the document, isXHTML
returns false.
The isXHTML
property is read-only.
You may see this documented as isXhtml
. However, the Expression Web JavaScript API doesn’t pay attention to case, so isXhtml
is equivalent to isXHTML
.
xweb.document.links
PropertyThe links
property locates all hyperlinks in the document.
xweb.document.links;
Returns an array of xweb.document.htmlElement
objects, each representing an a
element with an href
element in the document. If no a
elements with href
attributes are present in the document, the links
property returns null
.
The links
property is read-only.
Don’t confuse anchors with links. If an a
element doesn’t contain an href
attribute, it’s an anchor and is returned by the anchors
property. If it does contain an href
attribute, it’s a link and is returned by the links
property.
xweb.document.location
PropertyThe location
property returns the location of the document.
xweb.document.location;
The absolute file path of the document as a string. If the active site is a disk-based site, location
returns file:///
followed by the path and filename. If the site is a server-based site, the location
property returns the path preceded by http://
or ftp://
depending on the type of site.
The location
property actually returns an IHTMLLocation
object and not a string. Therefore, it’s possible to obtain much more useful information than simply the path of a page using the location
element. For example, location.host
returns the host (for example, www.jimcobooks.com) when the document is part of a server-based site.
For more information on the IHTMLLocation
object, see http://msdn.microsoft.com/en-us/library/aa209080(office.11).aspx.
The location
property is read-only.
The location
property is the easiest way to determine whether a document is an unsaved file. If the document has never been saved, location.protocol
returns unsaved:
. The code example illustrates this.
The following example checks the location
property to determine if the active document is unsaved. If it is, the user is prompted to save the document.
xweb.document.name
PropertyThe name
property returns the name of the document.
xweb.document.name;
The name of the document, along with the file extension, as a string.
This property is identical to the filename
property. The name
property is read-only.
xweb.document.pathFromSiteRoot
PropertyThe pathFromSiteRoot
property is used to determine where the document exists relative to the root of the site.
xweb.document.pathFromSiteRoot;
Returns the relative path from the root of the site to the document as a string. If the document exists in the root of the site, pathFromSiteRoot
returns an empty string.
Use the pathFromSiteRoot
property to construct relative paths to web pages.
The pathFromSiteRoot
property is read-only.
The following example computes the relative path from the site root for the active document.
xweb.document.scripts
PropertyThe scripts
property locates all script
elements in the document.
xweb.document.scripts;
Returns an array of xweb.document.htmlElement
objects, each representing a script
element in the document. If no script
elements are present in the document, the scripts
property returns null
.
The scripts
property is read-only.
xweb.document.selection
PropertyThe selection
property returns whatever is selected in the document.
xweb.document.selection;
A selection
object.
For more information on the selection
object, see “xweb.document.selection
Object,” p. 751, in this chapter.
The selection
property is read-only.
The following example wraps the selection in the active document within a div
element.
The example code uses the legacy ActivePageWindow
object to check for unsaved changes via the IsDirty
property. It also uses the ViewMode
property to work around a problem that prevents programmatic manipulation of code on a dirty page.
xweb.document.appendScriptReference
MethodThe appendScriptReference
method adds a script reference before the closing head
element.
xweb.document.appendScriptReference(path, type);
The path
parameter is a string and uses the syntax addin:script.js
. It can also include a relative path such as addin:scripts/script.js
.
The type
parameter is a string that identifies the MIME type of script that is being referenced. Typical values would be javascript
, ecmascript
, or vbscript
.
Returns true
if the script reference was added successfully and false
otherwise.
The script reference must be a script file that is located within the add-in’s folder. If a script reference is added to a script within the site, the path to the script is added as an absolute path that can cause problems after a site is published.
If you attempt to add a reference to a script that is already referenced, the appendScriptReference
method will not add a reference and will return false
.
The following code adds a script reference immediately before the closing head
element of the active document.
var doc = xweb.document;
doc.appendScriptReference("addin:scripts/jquery.js", "javascript");
After this code runs, the following script reference is added.
<script type="text/javascript" src="jquery.js"></script>
The appendScriptReference
method adds the script reference with an absolute path. When the affected page is saved, Expression Web will display the Save Embedded Files dialog so that the user can specify where to save the embedded script file.
xweb.document.appendStyleReference
MethodThe appendStyleReference
method adds a style sheet reference before the closing head
element.
xweb.document.appendStyleReference(path);
The path
parameter refers to a style sheet in the add-in’s folder and is in the format addin:style.css
. A relative path can also be included as in addin:styles/style.css
.
Returns true
if the style sheet reference was successfully added and false
otherwise.
If you attempt to add a style sheet reference that already exists, nothing will be added and appendStyleReference
will return false
.
The style sheet must exist within the add-in’s folder. Style sheet references are added in the following format.
<style rel="stylesheet" type="text/css" href="style.css" />
The following example links a style sheet called styles.css
to the active document. The styles.css
file is located in the styles
folder within the add-in’s folder.
var doc = xweb.document;
doc.appendStyleReference("addin:styles/styles.css");
The appendStyleReference
method adds the style sheet link with an absolute path. When the affected page is saved, Expression Web will display the Save Embedded Files dialog so that the user can specify where to save the embedded style sheet.
xweb.document.close
MethodThe close
method closes the document.
xweb.document.close();
None.
Returns true
if the document is successfully closed and false
otherwise.
xweb.document.getElementById
MethodThe getElementById
method returns the first element in the DOM of the document that contains an id
attribute that matches the argument passed to it.
xweb.document.getElementById(id);
The id
parameter is the id
attribute of the element you want to return. If more than one element is found with the specified id
, the first element encountered is returned.
The getElementById
method returns an htmlElement
object.
For more information on the htmlElement
object, see “htmlElement
Object,” p. 742, in this chapter.
The following example gets a reference to an element with an id
attribute value of banner
and sets the HTML code inside of the element.
xweb.document.getElementsByAttributeName
MethodThe getElementsByAttributeName
method returns elements that contain the specified attribute.
xweb.document.getElementsByAttributeName(attrib);
The attrib
parameter is a string that specifies the attribute name.
Returns an array of htmlElement
objects, each representing an element with the specified attribute. If no elements are found with the specified attribute, returns an empty array.
The following code returns an array with all elements that have a id
attribute. It then iterates through the array and populates a text area on the page with each ID.
xweb.document.getElementsByTagName
MethodThe getElementsByTagName
method returns elements with a tag name that matches the specified tag name.
xweb.document.getElementsByTagName(tag);
The tag
parameter is a string that specifies an HTML element name.
An array of htmlElement
objects with the specified tag name. If no elements are found with the specified tag name, an empty array is returned.
For an example of using the getElementsByTagName
method, see the code example for the getElementsByAttributeName
method.
xweb.document.getScriptElementByCode
MethodThe getScriptElementByCode
method searches for code within script
blocks in the document and returns the first script
element that contains the specified code.
xweb.document.getScriptElementByCode(code);
The code
parameter is a case-insensitive string that specifies the script code that the getScriptElementByCode
method is to find.
The first script
element with matching code is returned as an htmlElement
object. If no script
elements are found containing the specified code, returns null
.
The following example uses the getScriptElementByCode
method to determine if a specific script has already been inserted onto the page.
xweb.document.getScriptElementByFile
MethodThe getScriptElementByFile
method searches script references in the document for script
elements with an src
attribute that matches a particular pattern.
xweb.document.getScriptElementByFile(pattern);
The pattern
parameter can be any part of the path specified by the src
attribute of the script
element.
The first script
element that matches the pattern is returned as an htmlElement
. If no script
element is found, getScriptElementByFile
returns null
.
If more than one script
element matches the specified pattern, only the first element is returned.
Consider the following script reference:
<script src="scripts/jscript.js" type="text/javascript" />
The following values for the pattern
parameter are examples of patterns that match this script reference:
scripts
jscript
jscript.js
pts/jsc
xweb.document.getStyleElementByCode
MethodThe getStyleElementByCode
method searches style
elements in the document for a specified code pattern.
xweb.document.getStyleElementByCode(pattern);
The pattern
parameter is a case-insensitive string that contains the text for which to search inside style
elements.
The first style
element found that contains the specified string is returned as an htmlElement
object. If no style
elements are found, returns null
.
The following example returns the first style element that defines a first-child
pseudo class.
xweb.document.getStyleElementByFile
MethodThe getStyleElementByFile
method searches for a filename pattern in style sheet links.
xweb.document.getStyleElementByFile(pattern);
The pattern
parameter is a case-insensitive string that contains the pattern to find.
Returns the first link
element that matches the pattern as an htmlElement
object. If no match is found, returns null
.
The getStyleElementByFile
method searches the href
attribute of all link
elements with a rel
attribute set to stylesheet
.
xweb.document.insertBeforeHtml
MethodThe insertBeforeHtml
method inserts text at the top of the document immediately before the opening html
element.
xweb.document.insertBeforeHtml(text);
The text
parameter contains the text to be inserted.
Returns true
if the text was inserted and false
otherwise.
The insertBeforeHtml
method can be used to insert comments, a doctype, ASP.NET or PHP information, or any other information that needs to be inserted before the opening html
element.
The insertBeforeHtml
method does not check to see whether the text you are inserting has already been inserted. If you call it multiple times with the same argument, it adds the same text to the document multiple times.
The following example inserts a copyright block at the top of the active document.
xweb.document.save
MethodThe save
method saves the document. This method is equivalent to selecting File, Save in Expression Web.
xweb.document.save([path]);
The optional path
parameter can be used to save a file under a new name.
Returns true
if the document is successfully saved. Otherwise, it returns false
.
The path must be preceded by site:
and it must be relative to the root of the site.
The following example saves the existing file as newfile.htm
.
xweb.document.save("site:newfile.htm");
xweb.document.saveAs
MethodThe saveAs
method opens the Save As dialog so that the document can be saved under a different name.
xweb.document.saveAs();
None.
Returns true
if the document is successfully saved and false
otherwise.
If you want to programmatically save the document under a new name without user interaction, use the xweb.legacyapp.ActivePageWindow.SaveAs
method.
The following example shows how to save a document under a new name with and without user interaction.
xweb.document.synchronizeViews
MethodThe synchronizeViews
method synchronizes the Code and Design views in Expression Web.
xweb.document.synchronizeViews();
None.
Returns true
if views are successfully synchronized and false
otherwise.
When changes are made to a page programmatically, Expression Web may not recognize that change automatically. Also, changes made while in Code view may not be reflected in Design view.
To ensure that the views in Expression Web are always up to date, call the synchronizeViews
method before and after making any programmatic change to a document.
XWEB.FILE
ObjectThe file
object refers to a file within either a site or within an add-in’s folder. The file
object is used to interact with files that do not have a DOM. To interact with files that have a DOM, use the xweb.document
object.
xweb.file.copy
MethodThe copy
method copies a file from one location to another.
xweb.file.copy(source, dest, overwrite);
The source
parameter specifies the source file’s URI. The source
parameter’s value should be preceded by site:
if the file is in the active site and addin:
if the file is in the add-in’s folder.
The dest
parameter specifies the destination URI. The value of the dest
parameter should be preceded by site:
.
The overwrite
parameter is a Boolean value that specifies whether to overwrite the destination file if it already exists. If the overwrite
parameter is true
, the file will be overwritten if it already exists.
The copy
method returns true
if the file is successfully copied. Otherwise, it returns false
.
You cannot use the copy
method to copy a file to the add-in’s folder.
The Folder List in Expression Web is not automatically refreshed after the copy
method is executed. Therefore, it’s advisable to use the following method call after a call to the copy
method:
xweb.legacyapp.ActiveWeb.Refresh(true);
The preceding code requires that the legacy
attribute be set to true
for the addin
element in your manifest.
The following example copies a style sheet from the add-in folder to the active site.
xweb.file.createFile
MethodThe createFile
method creates a file at the location specified.
xweb.file.createFile(path);
The path
parameter is a string that specifies the location where the file is to be created relative to the root of the site. It must be preceded by site:
and includes the filename and extension. Any extension is valid.
Returns true
unless an error occurs. If an error occurs, returns false
.
If the file specified by the path
parameter already exists, createFile
does nothing, but it still returns true
.
Files created by createFile
are empty. Therefore, it’s best to programmatically add the necessary base code (such as html
, head
, and body
elements) using the xweb.document.insertBeforeHtml
method after creating the file.
If the path specified matches an existing file, the existing file will be replaced with the new file. Therefore, you should always check for an existing file using the xweb.file.exists
method as shown in the code example.
The following example creates a new HTML file and adds the necessary base code.
xweb.file.createFolder
MethodThe createFolder
method creates a folder in the current site at the path specified.
xweb.file.createFolder(path);
The path
parameter is a string specifying the root relative path for the new folder. It must be preceded with site:
.
Returns true
if the folder is successfully created and false
otherwise. If the folder specified by the path
parameter already exists, createFolder
returns false.
The Folder List is not automatically refreshed after the new folder is created, so it’s advised that you programmatically refresh the Folder List after calling this method.
xweb.file.deleteFile
MethodThe deleteFile
method deletes the file that is specified.
xweb.file.deleteFile(file);
The file
parameter is a string specifying the location of the file to delete relative to the root of the current site. It must be preceded by site:
. Any file type is valid.
Returns true
if the file is successfully deleted and false
otherwise.
You cannot delete folders using the deleteFile
method.
It is possible to delete a file that is currently open in Expression Web.
The Folder List is not automatically refreshed after the new folder is created, so it’s advised that you programmatically refresh the Folder List after calling this method.
xweb.file.exists
MethodThe exists
method checks to see whether the specified file exists in the current site.
xweb.file.exists(path);
The path
parameter is a string that specifies the path and name of the file relative to the root of the site. It must be preceded by site:
.
Returns true
if the file exists and false
if it doesn’t.
xweb.file.getAttributes
MethodThe getAttributes
method returns attributes of the specified file or folder.
xweb.file.getAttributes(path);
The path
parameter is a string specifying the path to the file or folder relative to the root of the site. It must be preceded by site:
.
Returns a string indicating the attributes of the file or folder. If the file or folder doesn’t exist, returns null
.
The following is a list of possible attributes that are returned:
• R
—Read-only
• D
—Folder
• H
—Hidden
• S
—System
If the file specified by the path
parameter is hidden and read-only, the following is returned by getAttributes
.
RH
xweb.file.getCreationDate
MethodThe getCreationDate
method returns the date that the specified file was created.
xweb.file.getCreationDate(path);
The path
parameter is a string that specifies the path to the file relative to the root of the site. It must be preceded by site:
.
Returns a JavaScript Date
object. If the specified file is not found, returns undefined
.
Because getCreationDate
returns a Date
object, you can call any of the Date
object’s methods and properties for additional functionality. The code example illustrates this concept.
For a full reference on the JavaScript Date
object, see http://www.w3schools.com/jsref/jsref_obj_date.asp.
The following example uses the getCreationDate
method to obtain time and date information about a file:
xweb.file.getModificationDate
MethodThe getModificationDate
method returns the last modified date of the specified file.
xweb.file.getModificationDate(path);
The path
parameter is a string that specifies the path of the file relative to the root of the site. It must be preceded with site:
.
Returns a JavaScript Date
object. If the specified file is not found, returns undefined
.
See getCreationDate
for more information on the JavaScript Date
object.
xweb.file.getSize
MethodThe getSize
method gets the file size of the specified file.
xweb.file.getSize(path);
The path
parameter is a string that specifies the path to the file relative to the root of the site. It must be preceded with site:
.
Returns an integer representing the size of the specified file in bytes.
The size returned is the size on disk and doesn’t take unsaved modifications into account.
xweb.file.listFolder
MethodThe listFolder
method returns a list of files or folders in the site that match a specified pattern.
xweb.file.listFolder(path, type);
The path
parameter is a string that specifies the path of the file or folder relative to the root of the site. It must be preceded with site:
.
The type
parameter specifies whether to return files or folders that match the path
parameter. The following values are valid for the type
parameter.
• files
—Returns files that match the specified path.
• directories
—Returns folders that match the specified path.
Returns an array of strings containing the name(s) of files or folders that match the specified path.
You can use the following wildcard characters to define a matching pattern for the path
parameter:
• *—Matches one or more instances of any character.
• ?—Matches a single instance of a character.
The listFolder
method is not recursive. Only the files and folders in the folder specified by the path
parameter are returned.
The following example matches all files with an “i” as the second character in the root folder of the site:
xweb.file.listFolder("site:?i*", "files");
xweb.file.read
MethodThe read
method reads the specified file.
xweb.file.read(path);
The path
parameter is a string that specifies the path to the file relative to the root of the site. It must be preceded by site:
.
Returns a string that contains the entire contents of the file.
While the read
method can be used on non-text files (such as binary files), it’s only useful for textual files.
xweb.file.setAttributes
MethodThe setAttributes
method sets attributes on the specified file or folder.
xweb.file.setAttributes(path, attribute);
The path
parameter is a string that specifies the path to the file or folder relative to the site root. It must be preceded by site:
.
The attribute
parameter is a case-sensitive string and must be one of the following:
• R
—Makes the file or folder read-only.
• W
—Makes the file or folder read/write.
• H
—Makes the file or folder hidden.
• V
—Makes the file or folder visible.
• RH
—Makes the file read-only and hidden.
• RV
—Makes the file read-only and visible.
• WH
—Makes the file read/write and hidden.
• WV
—Makes the file read/write and visible.
Returns true
if the attribute was successfully set. Otherwise, returns false
.
The following code example makes the scripts/myscript.js
file read-only and hidden.
xweb.file.setAttributes("site:scripts/myscript.js", "RH");
xweb.file.write
MethodThe write
method writes the specified string to the specified file.
xweb.file.write(path, string);
The path
parameter is a string that specifies the path to the file or folder relative to the site root. It must be preceded by site:
.
The string
parameter is the string to be written to the file.
Returns true
if the string was successfully written to the file. Otherwise, returns false
.
It is possible to use the write
method to write string content to a binary file. However, doing so will almost certainly corrupt the file.
HTMLELEMENT
ObjectThe htmlElement
object represents an HTML element in a document. The properties and methods of the htmlElement
object can be used to examine and manipulate the content in a document.
The properties and methods of the xweb.document
object can be used to obtain a reference to an htmlElement
object.
htmlElement.childNodes
PropertyThe childNodes
property returns an array of an element’s first-level child nodes. If the element has no child nodes, an empty array is returned.
htmlElement.childNodes;
The childNodes
property only returns first-level children of the element.
The childNodes
property is read-only.
In the following example code, only the ul element is returned by the childNodes property. None of the li elements is returned.
htmlElement.className
PropertyThe className
property returns the value of the class
attribute of the element.
htmlElement.className;
Returns the value of the class
attribute as a string. If the element does not have a class
element, className
returns undefined
.
The className
property is read-only.
htmlElement.id
PropertyThe id
property returns the value of the id
attribute of the element.
htmlElement.id;
Returns the value of the id
attribute as a string. If the element does not have an id
attribute, id
returns undefined
.
The id
property is read-only.
htmlElement.innerHtml
PropertyThe innerHtml
property returns or sets the HTML code that is between the start and end tags of the element.
htmlElement.innerHtml;
Returns the HTML code of the element as a string. If the element contains no HTML code, an empty string is returned.
When used to set the inner HTML of an element, innerHtml
returns the newly set HTML as a string.
The innerHtml
property is a read/write property.
The following code example illustrates the use of the innerHtml
property.
When the preceding code runs, the first alert displays the following HTML:
<h1>Welcome</h1>
<p>Welcome to our site.</p>
The innerHtml
property is then set to new HTML. The second alert displays the following:
<h1>Welcome Home</h1>
After this code runs, the p
element is removed from the page, and the text displayed inside the h1
heading is changed.
htmlElement.innerText
PropertyThe innerText
property is similar to the innerHtml
property, but the innerText
property returns text only and not HTML.
htmlElement.innerText;
Returns the inner text of the element as a string. If the element has no inner text, an empty string is returned.
When used to set the inner text of an element, innerText
returns the newly set inner text as a string.
If you use the innerText
property to assign HTML code to an element, the HTML code is encoded and appears as regular text in the document.
The innerText
property is a read/write property.
The following code example illustrates the use of the innerText
property.
In this example, the first alert displays the following:
Welcome
Only the text of the h1
element is returned. The actual HTML is ignored.
After the innerText
property is set to Welcome Home
, an alert is used to display the innerHtml
property of the div
. That alert displays the following.
Welcome Home
By setting the innerText
property of the div
, the h1
element has been removed. The innerText
property does not recognize HTML code.
Next, the innerText
property is set using <h1>Welcome Home</h1>
. The innerText
property of the div
is then displayed in an alert. That alert displays the following:
<h1>Welcome Home</h1>
htmlElement.nextSibling
PropertyThe nextSibling
property returns the next htmlElement
at the same DOM level as the element.
htmlElement.nextSibling;
Returns an htmlElement
representing the next element in the DOM that is at the same level. If there are no other elements at the same level in the DOM, nextSibling
returns undefined
.
Experienced JavaScript developers may have encountered situations where using the nextSibling
property in the DOM outside Expression Web returns whitespace that exists between elements. The htmlElement.nextSibling
property in Expression Web’s JavaScript API does not consider whitespace to be elements.
The nextSibling
property is read-only.
In the following code example, nextSibling
returns the link
element.
htmlElement.outerHtml
PropertyThe outerHtml
property returns or sets the HTML code of the element.
htmlElement.outerHtml;
Returns the HTML code for the element, including the HTML elements that comprise the start and end tags.
When used to set the outer HTML for an element, returns the newly set HTML code as a string.
The outerHtml
property is a read/write property.
The following example illustrates the use of the outerHtml
property.
The first alert from the preceding code example displays the following:
<div id="content">
<h1>Welcome</h1>
<p>Welcome to our site.</p>
</div>
Notice that the outerHtml
property contains the entire HTML content, including the start and end tags. After the outerHtml
property is set to a new value, the complete div
tag is replaced with the new content.
htmlElement.parentNode
PropertyThe parentNode
property returns parent node of the element.
htmlElement.parentNode;
Returns the parent node of the element as an htmlElement
object. If the element has no parent nodes, returns undefined
.
The parentNode
property is read-only.
In the following code example, the parentNode
property returns the div
element.
htmlElement.previousSibling
PropertyThe previousSibling
property returns the previous htmlElement
at the same DOM level as the element. The previousSibling
is used in the same fashion as the nextSibling
method.
htmlElement.previousSibling;
Returns the previous element at the same level in DOM as an htmlElement
object.
If the element has no previous siblings, previousSibling
returns null
.
The previousSibling
property is read-only.
htmlElement.tagName
PropertyThe tagName
property returns the element’s HTML tag name.
htmlElement.tagName;
Returns the name of the element’s tag as a string.
The string that is returned does not contain the opening or closing brackets. Only the tag name is returned. For example, if the element is an anchor element, the tagName
property returns a
.
The tagName
property is read-only.
htmlElement.getAttribute
MethodThe getAttribute
method returns the value of the element’s specified attribute.
htmlElement.getAttribute(attribName);
The attribName
parameter specifies the name of the attribute to return.
Returns the value of the specified attribute as a string. If the specified attribute does not exist, returns undefined
.
When the preceding code example runs, the alert box displays the following:
font-size:.75em
htmlElement.removeAttribute
MethodThe removeAttribute
method removes the specified attribute from the element.
htmlElement.removeAttribute(attribName);
The attribName
parameter specifies the attribute name to remove from the element.
The removeAttribute
method returns true
if the attribute is found and removed and returns false
otherwise.
htmlElement.setAttribute
MethodThe setAttribute
method sets an attribute name and value of the element.
htmlElement.setAttribute(name, value);
The name
parameter specifies the name of the attribute to set. The value
parameter specifies the value for the attribute. The value
parameter can be an empty string or null
.
The setAttribute
returns true
if the attribute is set. Otherwise, it returns false
.
If the specified attribute already exists, the value of the existing attribute will be changed to the value specified by the value
parameter. If the specified attribute doesn’t exist, it will be added to the element.
XWEB.DOCUMENT.SELECTION
ObjectThe selection
object represents a selection within a document. The selection
object exposes properties and methods that allow for interacting and modifying the document.
selection.end
PropertyThe end
property identifies the end of the selection in the document.
selection.end;
Returns an integer that represents the number of characters from the first character in the document to the last character in the selection.
The end
property is read-only.
selection.start
PropertyThe start
property identifies the start of the selection in the document.
selection.start;
Returns an integer that represents the number of characters from the first character in the document to the first character in the selection.
The start
property is read-only.
selection.text
PropertyThe text
property retrieves or sets the text of the selection.
selection.text;
Returns the selected text as a string. If nothing is selected, returns an empty string.
The text
property is read/write.
The following example illustrates the use of the text
property. In the example, the following HTML code is in the document.
<!-- Content Paragraph -->
<p>This is content.</p>
The word “Content” in the HTML comment is selected.
selection.append
MethodThe append
method adds text to the end of the selection.
selection.append(text);
The text
parameter is the text to add to the end of the selection.
Returns true
if the text was successfully added. Otherwise, returns false
.
The append
method can be used to add text, HTML code, JavaScript code, and so on.
selection.insert
MethodThe insert
method inserts text in front of the selection.
selection.insert(text);
The text
parameter represents the string to be inserted at the beginning of the current selection. If nothing is selected, the text is inserted at the insertion point.
Returns true
if the text was successfully inserted. Otherwise, returns false
.
Like the append
method, the insert
method can be used to insert text or code.
selection.set
MethodThe set
method sets the start and end position of the selection.
selection.set(start, end);
The start
parameter is an integer that represents the number of characters from the beginning of the document to the start of the selection.
The end
parameter represents the number of characters from the beginning of the document to the end of the selection.
Returns true
if the selection was successfully set. Otherwise, returns false
.
If the value of the end
parameter is greater than the number of characters in the document, the selection will be set from the character indicated by the start
parameter to the end of the document.
selection.remove
MethodThe remove
method removes the selection from the document.
selection.remove();
None.
Returns true
if the selection was successfully removed. Otherwise, returns false
.
selection.replace
MethodThe replace
method replaces the current selection with the specified text.
selection.replace(text);
The text
parameter is a string that represents the new text for the selection.
Returns true
if the selection was successfully replaced. Otherwise, returns false
.
The replace
method performs the same operation as setting the text
property of the selection.
selection.wrap
MethodThe wrap
method wraps the selection with the specified start and end text.
selection.wrap(startText, endText);
The startText
parameter is the text to be inserted before the selection.
The endText
parameter is the text to be inserted after the selection.
Returns true
if the selection was successfully modified. Otherwise, returns false
.
The wrap
method is often used to wrap a selection with specific HTML tags.
This code example makes the selection a hyperlink:
selection.wrap("<a href="http://www.jimcobooks.com">", "</a>");