39. Expression Web 4 JavaScript API Reference
Conventions Used in this Reference
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 Object
The 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 Property
The version property returns a string that identifies the version of Expression Web.
Syntax
xweb.application.version;
Returns
The full version number is returned as a string.
Information
The version property is read-only.
Example
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 Method
The chooseFile method displays a Browse dialog (commonly referred to as a file picker).
Syntax
xweb.application.chooseFile(label, [filter]);
Parameters
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.
Returns
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.
Information
The syntax for the filter parameter is *.ext, and multiple filters can be applied by separating each with a comma.
Example
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.
Tip
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 Method
The endDialog method closes a modal dialog that was opened using the showModalDialog method.
Syntax
xweb.application.endDialog(boolValue);
Parameters
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.
Returns
Nothing.
Information
If no value is provided for the boolValue parameter, an invalid procedure call error occurs.
Example
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 Method
The 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.
Syntax
xweb.application.handleEvent(event);
Parameters
The event parameter is a JavaScript event (IHTMLEventObj) object.
Returns
Returns true if the event is handled by Expression Web. Otherwise, false.
Information
The handleEvent method only handles the keydown event.
Example
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 Method
The 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.
Syntax
xweb.application.newDocument([doctype]);
Parameters
The optional doctype parameter is a string that specifies the doctype for the new document.
Returns
Returns an xweb.document object representing the newly created page.
Information
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.
Note
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.
Example
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 Method
The openDocument method opens a web page.
Syntax
xweb.application.openDocument(URI);
Parameters
The URI parameter is the URI of the document to be opened.
Returns
Returns an xweb.document object.
Information
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.
Tip
If the fileURI refers to a file that is already open in Expression Web, the tab for the already opened file will be activated.
Example
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 Method
The refreshFileListing method refreshes the Folder List in Expression Web.
Syntax
xweb.application.refreshFileListing();
Parameters
None.
Returns
If successful in refreshing the Folder List, refreshFileListing returns true. Otherwise, it returns false.
Information
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).
Example
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 Method
The setActiveDocument method activates the xweb.document that is passed to it.
Syntax
xweb.application.setActiveDocument(doc);
Parameters
The doc parameter is the xweb.document object to activate.
Returns
Returns true if the document is activated. Otherwise, returns false.
Example
The following example opens two documents. It then activates the first document that was opened.
xweb.application.setPanelVisibility Method
The setPanelVisibility method allows you to show or hide panels within the Expression Web interface.
Syntax
xweb.application.setPanelVisibility(panel, "hidden"|"visible");
Parameters
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
Returns true if the panel was found. Otherwise, returns false.
Information
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
Example
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.
Tip
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.
Tip
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 Method
The showModalDialog method opens a modal dialog.
Syntax
xweb.application.showModalDialog(dialogURI, dialogTitle, [dialogOptions];
Parameters
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.
Tip
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.
Returns
A Boolean. The return value for showModalDialog is set by the endDialog method.
Information
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.
Tip
Vertical scrollbars are always visible. Horizontal scrollbars are only visible when the width of the dialog’s content exceeds the width of the dialog.
Example
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 Object
The 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 Method
The read method reads a setting.
Syntax
xweb.application.settings.read(setting);
Parameters
The setting parameter is a string that identifies the setting to be retrieved.
Returns
Returns the value of the specified setting.
Information
If the setting you attempt to read does not exist, the read method returns undefined.
Example
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 Method
The write method stores a setting and value.
Syntax
xweb.application.settings.write(setting, value);
Parameters
The setting parameter is a string that identifies the setting. The value parameter is the value to be stored.
Returns
Nothing.
Information
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.
Tip
If the setting specified by the setting parameter already exists, the existing value is overridden by the new value.
Example
The following example writes a setting called ConfirmOnClose and sets it based on a checkbox called chkConfirm.
XWEB.DEVELOPER Object
The xweb.developer object contains methods that write information to the debug console for add-ins.
Tip
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 Method
The write method writes a value to the debug console for an add-in.
Syntax
xweb.developer.write(value);
Parameters
The value parameter is the value to be written to the debug console.
Returns
Undefined.
Information
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.
Note
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.
Example
The following example uses the xweb.developer.write method to log output to the debug console.
xweb.developer.writeLine Method
The writeLine method is equivalent to the write method except that a line break is added after each value.
Syntax
xweb.developer.writeLine(value);
Parameters
The value parameter is written to the debug console, followed by a line break.
Returns
Undefined.
XWEB.DOCUMENT Object
The 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.
Caution
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.
Tip
When used without explicitly specifying the xweb namespace, the document object refers to window.document.
Caution
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 Property
The anchors property locates all anchors on the document.
Syntax
xweb.document.anchors;
Returns
An array of xweb.document.htmlElement objects is returned. If no anchors are defined in the page, the anchors property returns null.
Information
The anchors property is read-only.
Example
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 Property
The applets property locates all applet elements in the document.
Syntax
xweb.document.applets;
Returns
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.
Information
The applets property is read-only.
xweb.document.embeds Property
The embeds property locates all embed elements in the document.
Syntax
xweb.document.embeds;
Returns
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.
Information
The embeds property is read-only.
xweb.document.filename Property
The filename property returns the filename and extension of the document.
Syntax
xweb.document.filename;
Returns
The filename and extension as a string.
Information
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.
Tip
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.
Example
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 Property
The forms property locates all form elements in the document.
Syntax
xweb.document.forms;
Returns
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.
Information
The forms property is read-only.
xweb.document.frames Property
The frames property locates all frame elements in the document.
Syntax
xweb.document.frames;
Returns
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.
Information
The frames property is read-only.
xweb.document.images Property
The images property locates all img elements in the document.
Syntax
xweb.document.images;
Returns
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.
Information
The images property is read-only.
xweb.document.isXHTML Property
The isXHTML property determines whether the document is an XHTML document.
Syntax
xweb.document.isXHTML;
Returns
Returns a Boolean value indicating whether the document contains an XHTML doctype. If no doctype exists in the document, isXHTML returns false.
Information
The isXHTML property is read-only.
Tip
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 Property
The links property locates all hyperlinks in the document.
Syntax
xweb.document.links;
Returns
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.
Information
The links property is read-only.
Tip
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 Property
The location property returns the location of the document.
Syntax
xweb.document.location;
Returns
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.
Information
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.
Tip
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.
Example
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 Property
The name property returns the name of the document.
Syntax
xweb.document.name;
Returns
The name of the document, along with the file extension, as a string.
Information
This property is identical to the filename property. The name property is read-only.
xweb.document.pathFromSiteRoot Property
The pathFromSiteRoot property is used to determine where the document exists relative to the root of the site.
Syntax
xweb.document.pathFromSiteRoot;
Returns
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.
Information
Use the pathFromSiteRoot property to construct relative paths to web pages.
The pathFromSiteRoot property is read-only.
Example
The following example computes the relative path from the site root for the active document.
xweb.document.scripts Property
The scripts property locates all script elements in the document.
Syntax
xweb.document.scripts;
Returns
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.
Information
The scripts property is read-only.
xweb.document.selection Property
The selection property returns whatever is selected in the document.
Syntax
xweb.document.selection;
Returns
A selection object.
For more information on the selection object, see “xweb.document.selection Object,” p. 751, in this chapter.
Information
The selection property is read-only.
Example
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 Method
The appendScriptReference method adds a script reference before the closing head element.
Syntax
xweb.document.appendScriptReference(path, type);
Parameters
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
Returns true if the script reference was added successfully and false otherwise.
Information
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.
Tip
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.
Example
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 Method
The appendStyleReference method adds a style sheet reference before the closing head element.
Syntax
xweb.document.appendStyleReference(path);
Parameters
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
Returns true if the style sheet reference was successfully added and false otherwise.
Tip
If you attempt to add a style sheet reference that already exists, nothing will be added and appendStyleReference will return false.
Information
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" />
Example
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 Method
The close method closes the document.
Syntax
xweb.document.close();
Parameters
None.
Returns
Returns true if the document is successfully closed and false otherwise.
xweb.document.getElementById Method
The getElementById method returns the first element in the DOM of the document that contains an id attribute that matches the argument passed to it.
Syntax
xweb.document.getElementById(id);
Parameters
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.
Returns
The getElementById method returns an htmlElement object.
For more information on the htmlElement object, see “htmlElement Object,” p. 742, in this chapter.
Example
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 Method
The getElementsByAttributeName method returns elements that contain the specified attribute.
Syntax
xweb.document.getElementsByAttributeName(attrib);
Parameters
The attrib parameter is a string that specifies the attribute name.
Returns
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.
Example
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 Method
The getElementsByTagName method returns elements with a tag name that matches the specified tag name.
Syntax
xweb.document.getElementsByTagName(tag);
Parameters
The tag parameter is a string that specifies an HTML element name.
Returns
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.
Example
For an example of using the getElementsByTagName method, see the code example for the getElementsByAttributeName method.
xweb.document.getScriptElementByCode Method
The getScriptElementByCode method searches for code within script blocks in the document and returns the first script element that contains the specified code.
Syntax
xweb.document.getScriptElementByCode(code);
Parameters
The code parameter is a case-insensitive string that specifies the script code that the getScriptElementByCode method is to find.
Returns
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.
Example
The following example uses the getScriptElementByCode method to determine if a specific script has already been inserted onto the page.
xweb.document.getScriptElementByFile Method
The getScriptElementByFile method searches script references in the document for script elements with an src attribute that matches a particular pattern.
Syntax
xweb.document.getScriptElementByFile(pattern);
Parameters
The pattern parameter can be any part of the path specified by the src attribute of the script element.
Returns
The first script element that matches the pattern is returned as an htmlElement. If no script element is found, getScriptElementByFile returns null.
Information
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 Method
The getStyleElementByCode method searches style elements in the document for a specified code pattern.
Syntax
xweb.document.getStyleElementByCode(pattern);
Parameters
The pattern parameter is a case-insensitive string that contains the text for which to search inside style elements.
Returns
The first style element found that contains the specified string is returned as an htmlElement object. If no style elements are found, returns null.
Example
The following example returns the first style element that defines a first-child pseudo class.
xweb.document.getStyleElementByFile Method
The getStyleElementByFile method searches for a filename pattern in style sheet links.
Syntax
xweb.document.getStyleElementByFile(pattern);
Parameters
The pattern parameter is a case-insensitive string that contains the pattern to find.
Returns
Returns the first link element that matches the pattern as an htmlElement object. If no match is found, returns null.
Information
The getStyleElementByFile method searches the href attribute of all link elements with a rel attribute set to stylesheet.
xweb.document.insertBeforeHtml Method
The insertBeforeHtml method inserts text at the top of the document immediately before the opening html element.
Syntax
xweb.document.insertBeforeHtml(text);
Parameters
The text parameter contains the text to be inserted.
Returns
Returns true if the text was inserted and false otherwise.
Information
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.
Example
The following example inserts a copyright block at the top of the active document.
xweb.document.save Method
The save method saves the document. This method is equivalent to selecting File, Save in Expression Web.
Syntax
xweb.document.save([path]);
Parameters
The optional path parameter can be used to save a file under a new name.
Returns
Returns true if the document is successfully saved. Otherwise, it returns false.
Information
The path must be preceded by site: and it must be relative to the root of the site.
Example
The following example saves the existing file as newfile.htm.
xweb.document.save("site:newfile.htm");
xweb.document.saveAs Method
The saveAs method opens the Save As dialog so that the document can be saved under a different name.
Syntax
xweb.document.saveAs();
Parameters
None.
Returns
Returns true if the document is successfully saved and false otherwise.
Information
If you want to programmatically save the document under a new name without user interaction, use the xweb.legacyapp.ActivePageWindow.SaveAs method.
Example
The following example shows how to save a document under a new name with and without user interaction.
xweb.document.synchronizeViews Method
The synchronizeViews method synchronizes the Code and Design views in Expression Web.
Syntax
xweb.document.synchronizeViews();
Parameters
None.
Returns
Returns true if views are successfully synchronized and false otherwise.
Information
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 Object
The 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 Method
The copy method copies a file from one location to another.
Syntax
xweb.file.copy(source, dest, overwrite);
Parameters
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.
Returns
The copy method returns true if the file is successfully copied. Otherwise, it returns false.
Information
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);
Tip
The preceding code requires that the legacy attribute be set to true for the addin element in your manifest.
Example
The following example copies a style sheet from the add-in folder to the active site.
xweb.file.createFile Method
The createFile method creates a file at the location specified.
Syntax
xweb.file.createFile(path);
Parameters
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
Returns true unless an error occurs. If an error occurs, returns false.
Information
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.
Caution
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.
Example
The following example creates a new HTML file and adds the necessary base code.
xweb.file.createFolder Method
The createFolder method creates a folder in the current site at the path specified.
Syntax
xweb.file.createFolder(path);
Parameters
The path parameter is a string specifying the root relative path for the new folder. It must be preceded with site:.
Returns
Returns true if the folder is successfully created and false otherwise. If the folder specified by the path parameter already exists, createFolder returns false.
Information
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 Method
The deleteFile method deletes the file that is specified.
Syntax
xweb.file.deleteFile(file);
Parameters
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
Returns true if the file is successfully deleted and false otherwise.
Information
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 Method
The exists method checks to see whether the specified file exists in the current site.
Syntax
xweb.file.exists(path);
Parameters
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
Returns true if the file exists and false if it doesn’t.
xweb.file.getAttributes Method
The getAttributes method returns attributes of the specified file or folder.
Syntax
xweb.file.getAttributes(path);
Parameters
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
Returns a string indicating the attributes of the file or folder. If the file or folder doesn’t exist, returns null.
Information
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 Method
The getCreationDate method returns the date that the specified file was created.
Syntax
xweb.file.getCreationDate(path);
Parameters
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
Returns a JavaScript Date object. If the specified file is not found, returns undefined.
Information
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.
Note
For a full reference on the JavaScript Date object, see http://www.w3schools.com/jsref/jsref_obj_date.asp.
Example
The following example uses the getCreationDate method to obtain time and date information about a file:
xweb.file.getModificationDate Method
The getModificationDate method returns the last modified date of the specified file.
Syntax
xweb.file.getModificationDate(path);
Parameters
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
Returns a JavaScript Date object. If the specified file is not found, returns undefined.
Information
See getCreationDate for more information on the JavaScript Date object.
xweb.file.getSize Method
The getSize method gets the file size of the specified file.
Syntax
xweb.file.getSize(path);
Parameters
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
Returns an integer representing the size of the specified file in bytes.
Information
The size returned is the size on disk and doesn’t take unsaved modifications into account.
xweb.file.listFolder Method
The listFolder method returns a list of files or folders in the site that match a specified pattern.
Syntax
xweb.file.listFolder(path, type);
Parameters
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
Returns an array of strings containing the name(s) of files or folders that match the specified path.
Information
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.
Example
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 Method
The read method reads the specified file.
Syntax
xweb.file.read(path);
Parameters
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
Returns a string that contains the entire contents of the file.
Information
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 Method
The setAttributes method sets attributes on the specified file or folder.
Syntax
xweb.file.setAttributes(path, attribute);
Parameters
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
Returns true if the attribute was successfully set. Otherwise, returns false.
Example
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 Method
The write method writes the specified string to the specified file.
Syntax
xweb.file.write(path, string);
Parameters
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
Returns true if the string was successfully written to the file. Otherwise, returns false.
Information
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 Object
The 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.
Tip
The properties and methods of the xweb.document object can be used to obtain a reference to an htmlElement object.
htmlElement.childNodes Property
The 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.
Syntax
htmlElement.childNodes;
Returns
The childNodes property only returns first-level children of the element.
Information
The childNodes property is read-only.
Example
In the following example code, only the ul element is returned by the childNodes property. None of the li elements is returned.
htmlElement.className Property
The className property returns the value of the class attribute of the element.
Syntax
htmlElement.className;
Returns
Returns the value of the class attribute as a string. If the element does not have a class element, className returns undefined.
Information
The className property is read-only.
htmlElement.id Property
The id property returns the value of the id attribute of the element.
Syntax
htmlElement.id;
Returns
Returns the value of the id attribute as a string. If the element does not have an id attribute, id returns undefined.
Information
The id property is read-only.
htmlElement.innerHtml Property
The innerHtml property returns or sets the HTML code that is between the start and end tags of the element.
Syntax
htmlElement.innerHtml;
Returns
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.
Information
The innerHtml property is a read/write property.
Example
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 Property
The innerText property is similar to the innerHtml property, but the innerText property returns text only and not HTML.
Syntax
htmlElement.innerText;
Returns
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.
Information
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.
Example
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 Property
The nextSibling property returns the next htmlElement at the same DOM level as the element.
Syntax
htmlElement.nextSibling;
Returns
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.
Information
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.
Example
In the following code example, nextSibling returns the link element.
htmlElement.outerHtml Property
The outerHtml property returns or sets the HTML code of the element.
Syntax
htmlElement.outerHtml;
Returns
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.
Information
The outerHtml property is a read/write property.
Example
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 Property
The parentNode property returns parent node of the element.
Syntax
htmlElement.parentNode;
Returns
Returns the parent node of the element as an htmlElement object. If the element has no parent nodes, returns undefined.
Information
The parentNode property is read-only.
Example
In the following code example, the parentNode property returns the div element.
htmlElement.previousSibling Property
The 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.
Syntax
htmlElement.previousSibling;
Returns
Returns the previous element at the same level in DOM as an htmlElement object.
If the element has no previous siblings, previousSibling returns null.
Information
The previousSibling property is read-only.
htmlElement.tagName Property
The tagName property returns the element’s HTML tag name.
Syntax
htmlElement.tagName;
Returns
Returns the name of the element’s tag as a string.
Information
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 Method
The getAttribute method returns the value of the element’s specified attribute.
Syntax
htmlElement.getAttribute(attribName);
Parameters
The attribName parameter specifies the name of the attribute to return.
Returns
Returns the value of the specified attribute as a string. If the specified attribute does not exist, returns undefined.
Example
When the preceding code example runs, the alert box displays the following:
font-size:.75em
htmlElement.removeAttribute Method
The removeAttribute method removes the specified attribute from the element.
Syntax
htmlElement.removeAttribute(attribName);
Parameters
The attribName parameter specifies the attribute name to remove from the element.
Returns
The removeAttribute method returns true if the attribute is found and removed and returns false otherwise.
htmlElement.setAttribute Method
The setAttribute method sets an attribute name and value of the element.
Syntax
htmlElement.setAttribute(name, value);
Parameters
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.
Returns
The setAttribute returns true if the attribute is set. Otherwise, it returns false.
Information
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 Object
The 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 Property
The end property identifies the end of the selection in the document.
Syntax
selection.end;
Returns
Returns an integer that represents the number of characters from the first character in the document to the last character in the selection.
Information
The end property is read-only.
selection.start Property
The start property identifies the start of the selection in the document.
Syntax
selection.start;
Returns
Returns an integer that represents the number of characters from the first character in the document to the first character in the selection.
Information
The start property is read-only.
selection.text Property
The text property retrieves or sets the text of the selection.
Syntax
selection.text;
Returns
Returns the selected text as a string. If nothing is selected, returns an empty string.
Information
The text property is read/write.
Example
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 Method
The append method adds text to the end of the selection.
Syntax
selection.append(text);
Parameters
The text parameter is the text to add to the end of the selection.
Returns
Returns true if the text was successfully added. Otherwise, returns false.
Information
The append method can be used to add text, HTML code, JavaScript code, and so on.
selection.insert Method
The insert method inserts text in front of the selection.
Syntax
selection.insert(text);
Parameters
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
Returns true if the text was successfully inserted. Otherwise, returns false.
Information
Like the append method, the insert method can be used to insert text or code.
selection.set Method
The set method sets the start and end position of the selection.
Syntax
selection.set(start, end);
Parameters
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
Returns true if the selection was successfully set. Otherwise, returns false.
Information
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 Method
The remove method removes the selection from the document.
Syntax
selection.remove();
Parameters
None.
Returns
Returns true if the selection was successfully removed. Otherwise, returns false.
selection.replace Method
The replace method replaces the current selection with the specified text.
Syntax
selection.replace(text);
Parameters
The text parameter is a string that represents the new text for the selection.
Returns
Returns true if the selection was successfully replaced. Otherwise, returns false.
Information
The replace method performs the same operation as setting the text property of the selection.
selection.wrap Method
The wrap method wraps the selection with the specified start and end text.
Syntax
selection.wrap(startText, endText);
Parameters
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
Returns true if the selection was successfully modified. Otherwise, returns false.
Information
The wrap method is often used to wrap a selection with specific HTML tags.
Example
This code example makes the selection a hyperlink:
selection.wrap("<a href="http://www.jimcobooks.com">", "</a>");