Edit

Share via

Word.CustomXmlNode class

Package:
word

Represents an XML node in a tree in the document. The CustomXmlNode object is a member of the Word.CustomXmlNodeCollection object.

Extends
OfficeExtension.ClientObject

Remarks

[ API set: WordApiDesktop 1.3 ]

Properties

attributes

Gets a CustomXmlNodeCollection object representing the attributes of the current element in the current node.
baseName

Gets the base name of the node without the namespace prefix, if one exists.
childNodes

Gets a CustomXmlNodeCollection object containing all of the child elements of the current node.
context

The request context associated with the object. This connects the add-in's process to the Office host application's process.
firstChild

Gets a CustomXmlNode object corresponding to the first child element of the current node. If the node has no child elements (or if it isn't of type CustomXmlNodeType.element), returns Nothing.
lastChild

Gets a CustomXmlNode object corresponding to the last child element of the current node. If the node has no child elements (or if it isn't of type CustomXmlNodeType.element), the property returns Nothing.
namespaceUri

Gets the unique address identifier for the namespace of the node.
nextSibling

Gets the next sibling node (element, comment, or processing instruction) of the current node. If the node is the last sibling at its level, the property returns Nothing.
nodeType

Gets the type of the current node.
nodeValue

Specifies the value of the current node.
ownerPart

Gets the object representing the part associated with this node.
parentNode

Gets the parent element node of the current node. If the current node is at the root level, the property returns Nothing.
previousSibling

Gets the previous sibling node (element, comment, or processing instruction) of the current node. If the current node is the first sibling at its level, the property returns Nothing.
text

Specifies the text for the current node.
xml

Gets the XML representation of the current node and its children.
xpath

Gets a string with the canonicalized XPath for the current node. If the node is no longer in the Document Object Model (DOM), the property returns an error message.

Methods

appendChildNode(options)

Appends a single node as the last child under the context element node in the tree.
appendChildSubtree(xml)

Adds a subtree as the last child under the context element node in the tree.
delete()

Deletes the current node from the tree (including all of its children, if any exist).
hasChildNodes()

Specifies if the current element node has child element nodes.
insertNodeBefore(options)

Inserts a new node just before the context node in the tree.
insertSubtreeBefore(xml, options)

Inserts the specified subtree into the location just before the context node.
load(options)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
removeChild(child)

Removes the specified child node from the tree.
replaceChildNode(oldNode, options)

Removes the specified child node and replaces it with a different node in the same location.
replaceChildSubtree(xml, oldNode)

Removes the specified node and replaces it with a different subtree in the same location.
selectNodes(xPath)

Selects a collection of nodes matching an XPath expression.
selectSingleNode(xPath)

Selects a single node from a collection matching an XPath expression.
set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.
toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Word.CustomXmlNode object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.CustomXmlNodeData) that contains shallow copies of any loaded child properties from the original object.
track()

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.
untrack()

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call context.sync() before the memory release takes effect.

Property Details

attributes

Gets a CustomXmlNodeCollection object representing the attributes of the current element in the current node.

readonly attributes: Word.CustomXmlNodeCollection;

Property Value

Word.CustomXmlNodeCollection

Remarks

[ API set: WordApiDesktop 1.3 ]

baseName

Gets the base name of the node without the namespace prefix, if one exists.

readonly baseName: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.3 ]

childNodes

Gets a CustomXmlNodeCollection object containing all of the child elements of the current node.

readonly childNodes: Word.CustomXmlNodeCollection;

Property Value

Word.CustomXmlNodeCollection

Remarks

[ API set: WordApiDesktop 1.3 ]

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Word.RequestContext

firstChild

Gets a CustomXmlNode object corresponding to the first child element of the current node. If the node has no child elements (or if it isn't of type CustomXmlNodeType.element), returns Nothing.

readonly firstChild: Word.CustomXmlNode;

Property Value

Word.CustomXmlNode

Remarks

[ API set: WordApiDesktop 1.3 ]

lastChild

Gets a CustomXmlNode object corresponding to the last child element of the current node. If the node has no child elements (or if it isn't of type CustomXmlNodeType.element), the property returns Nothing.

readonly lastChild: Word.CustomXmlNode;

Property Value

Word.CustomXmlNode

Remarks

[ API set: WordApiDesktop 1.3 ]

namespaceUri

Gets the unique address identifier for the namespace of the node.

readonly namespaceUri: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.3 ]

nextSibling

Gets the next sibling node (element, comment, or processing instruction) of the current node. If the node is the last sibling at its level, the property returns Nothing.

readonly nextSibling: Word.CustomXmlNode;

Property Value

Word.CustomXmlNode

Remarks

[ API set: WordApiDesktop 1.3 ]

nodeType

Gets the type of the current node.

readonly nodeType: Word.CustomXmlNodeType | "element" | "attribute" | "text" | "cData" | "processingInstruction" | "comment" | "document";

Property Value

Word.CustomXmlNodeType | "element" | "attribute" | "text" | "cData" | "processingInstruction" | "comment" | "document"

Remarks

[ API set: WordApiDesktop 1.3 ]

nodeValue

Specifies the value of the current node.

nodeValue: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.3 ]

ownerPart

Gets the object representing the part associated with this node.

readonly ownerPart: Word.CustomXmlPart;

Property Value

Word.CustomXmlPart

Remarks

[ API set: WordApiDesktop 1.3 ]

parentNode

Gets the parent element node of the current node. If the current node is at the root level, the property returns Nothing.

readonly parentNode: Word.CustomXmlNode;

Property Value

Word.CustomXmlNode

Remarks

[ API set: WordApiDesktop 1.3 ]

previousSibling

Gets the previous sibling node (element, comment, or processing instruction) of the current node. If the current node is the first sibling at its level, the property returns Nothing.

readonly previousSibling: Word.CustomXmlNode;

Property Value

Word.CustomXmlNode

Remarks

[ API set: WordApiDesktop 1.3 ]

text

Specifies the text for the current node.

text: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.3 ]

xml

Gets the XML representation of the current node and its children.

readonly xml: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.3 ]

xpath

Gets a string with the canonicalized XPath for the current node. If the node is no longer in the Document Object Model (DOM), the property returns an error message.

readonly xpath: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.3 ]

Method Details

appendChildNode(options)

Appends a single node as the last child under the context element node in the tree.

appendChildNode(options?: Word.CustomXmlAppendChildNodeOptions): OfficeExtension.ClientResult<number>;

Parameters

options
Word.CustomXmlAppendChildNodeOptions

Optional. The options that define the node to be appended.

Returns

OfficeExtension.ClientResult<number>

Remarks

[ API set: WordApiDesktop 1.3 ]

appendChildSubtree(xml)

Adds a subtree as the last child under the context element node in the tree.

appendChildSubtree(xml: string): OfficeExtension.ClientResult<number>;

Parameters

xml

string

A string representing the XML subtree.

Returns

OfficeExtension.ClientResult<number>

Remarks

[ API set: WordApiDesktop 1.3 ]

delete()

Deletes the current node from the tree (including all of its children, if any exist).

delete(): void;

Returns

void

Remarks

[ API set: WordApiDesktop 1.3 ]

hasChildNodes()

Specifies if the current element node has child element nodes.

hasChildNodes(): OfficeExtension.ClientResult<boolean>;

Returns

OfficeExtension.ClientResult<boolean>

Remarks

[ API set: WordApiDesktop 1.3 ]

insertNodeBefore(options)

Inserts a new node just before the context node in the tree.

insertNodeBefore(options?: Word.CustomXmlInsertNodeBeforeOptions): OfficeExtension.ClientResult<number>;

Parameters

options
Word.CustomXmlInsertNodeBeforeOptions

Optional. The options that define the node to be inserted.

Returns

OfficeExtension.ClientResult<number>

Remarks

[ API set: WordApiDesktop 1.3 ]

insertSubtreeBefore(xml, options)

Inserts the specified subtree into the location just before the context node.

insertSubtreeBefore(xml: string, options?: Word.CustomXmlInsertSubtreeBeforeOptions): OfficeExtension.ClientResult<number>;

Parameters

xml

string

A string representing the XML subtree.

options
Word.CustomXmlInsertSubtreeBeforeOptions

Optional. The options available for inserting the subtree.

Returns

OfficeExtension.ClientResult<number>

Remarks

[ API set: WordApiDesktop 1.3 ]

load(options)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Word.Interfaces.CustomXmlNodeLoadOptions): Word.CustomXmlNode;

Parameters

options
Word.Interfaces.CustomXmlNodeLoadOptions

Provides options for which properties of the object to load.

Returns

Word.CustomXmlNode

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Word.CustomXmlNode;

Parameters

propertyNames

string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Word.CustomXmlNode

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Word.CustomXmlNode;

Parameters

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

Word.CustomXmlNode

removeChild(child)

Removes the specified child node from the tree.

removeChild(child: Word.CustomXmlNode): OfficeExtension.ClientResult<number>;

Parameters

child
Word.CustomXmlNode

The child node to remove.

Returns

OfficeExtension.ClientResult<number>

Remarks

[ API set: WordApiDesktop 1.3 ]

replaceChildNode(oldNode, options)

Removes the specified child node and replaces it with a different node in the same location.

replaceChildNode(oldNode: Word.CustomXmlNode, options?: Word.CustomXmlReplaceChildNodeOptions): OfficeExtension.ClientResult<number>;

Parameters

oldNode
Word.CustomXmlNode

The node to be replaced.

options
Word.CustomXmlReplaceChildNodeOptions

Optional. The options that define the child node which is to replace the old node.

Returns

OfficeExtension.ClientResult<number>

Remarks

[ API set: WordApiDesktop 1.3 ]

replaceChildSubtree(xml, oldNode)

Removes the specified node and replaces it with a different subtree in the same location.

replaceChildSubtree(xml: string, oldNode: Word.CustomXmlNode): OfficeExtension.ClientResult<number>;

Parameters

xml

string

A string representing the new subtree.

oldNode
Word.CustomXmlNode

The node to be replaced.

Returns

OfficeExtension.ClientResult<number>

Remarks

[ API set: WordApiDesktop 1.3 ]

selectNodes(xPath)

Selects a collection of nodes matching an XPath expression.

selectNodes(xPath: string): Word.CustomXmlNodeCollection;

Parameters

xPath

string

The XPath expression.

Returns

Word.CustomXmlNodeCollection

Remarks

[ API set: WordApiDesktop 1.3 ]

selectSingleNode(xPath)

Selects a single node from a collection matching an XPath expression.

selectSingleNode(xPath: string): Word.CustomXmlNode;

Parameters

xPath

string

The XPath expression.

Returns

Word.CustomXmlNode

Remarks

[ API set: WordApiDesktop 1.3 ]

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.CustomXmlNodeUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

properties
Word.Interfaces.CustomXmlNodeUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options
OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Word.CustomXmlNode): void;

Parameters

properties
Word.CustomXmlNode

Returns

void

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Word.CustomXmlNode object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.CustomXmlNodeData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Word.Interfaces.CustomXmlNodeData;

Returns

Word.Interfaces.CustomXmlNodeData

track()

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.

track(): Word.CustomXmlNode;

Returns

Word.CustomXmlNode

untrack()

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call context.sync() before the memory release takes effect.

untrack(): Word.CustomXmlNode;

Returns

Word.CustomXmlNode