Office.CustomXmlNode interface

Represents an XML node in a tree in a document.

Remarks

Requirement SetsCustomXmlParts

Support details

A capital Y in the following matrix indicates that this interface is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this interface.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Word Y Y Y

Properties

baseName

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

namespaceUri

Retrieves the string GUID of the CustomXMLPart.

nodeType

Gets the type of the CustomXMLNode.

Methods

getNodesAsync(xPath, options, callback)

Gets the nodes associated with the XPath expression.

getNodeValueAsync(options, callback)

Gets the node value.

getTextAsync(options, callback)

Gets the text of an XML node in a custom XML part.

getXmlAsync(options, callback)

Gets the node's XML.

setNodeValueAsync(value, options, callback)

Sets the node value.

setTextAsync(text, options, callback)

Asynchronously sets the text of an XML node in a custom XML part.

setXmlAsync(xml, options, callback)

Sets the node XML.

Property Details

baseName

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

baseName: string;
Property Value
string
Remarks

Requirement SetsCustomXmlParts

Examples

function showXmlNodeBaseNames() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getNodesAsync('*/*', function (nodeResults) {
            for (i = 0; i < nodeResults.value.length; i++) {
                var node = nodeResults.value[i];
                write(node.baseName);
            }
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

namespaceUri

Retrieves the string GUID of the CustomXMLPart.

namespaceUri: string;
Property Value
string
Remarks

Requirement SetsCustomXmlParts

Examples

function showXmlNamespaceUri() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getNodesAsync('*/*', function (nodeResults) {
            for (i = 0; i < nodeResults.value.length; i++) {
                var node = nodeResults.value[i];
                write(node.namespaceUri);
            }
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

nodeType

Gets the type of the CustomXMLNode.

nodeType: string;
Property Value
string
Remarks

Requirement SetsCustomXmlParts

Examples

function showXmlNodeType() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getNodesAsync('*/*', function (nodeResults) {
            for (i = 0; i < nodeResults.value.length; i++) {
                var node = nodeResults.value[i];
                write(node.nodeType);
            }
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Method Details

getNodesAsync(xPath, options, callback)

Gets the nodes associated with the XPath expression.

getNodesAsync(xPath: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<CustomXmlNode[]>) => void): void;
Parameters
xPath
string

The XPath expression that specifies the nodes to get. Required.

options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<CustomXmlNode>) => void[]

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult. The value property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the xPath parameter.

Returns
void
Remarks

Requirement SetsCustomXmlParts

Examples

function showXmlChildNodes() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getNodesAsync('*', function (nodeResults) {
            for (i = 0; i < nodeResults.value.length; i++) {
                var node = nodeResults.value[i];
                node.getNodesAsync('*', function (nodeResults) {
                    write(nodeResults.value.length + " childNodes");
                });
            }
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

getNodeValueAsync(options, callback)

Gets the node value.

getNodeValueAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<string>) => void): void;
Parameters
options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<string>) => void

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult. The value property of the result is a string that contains the value of the referenced node.

Returns
void
Remarks

Requirement SetsCustomXmlParts

Examples

function showXmlNodeValues() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getNodesAsync('*/*', function (nodeResults) {
            for (i = 0; i < nodeResults.value.length; i++) {
                var node = nodeResults.value[i];
                node.getNodeValueAsync(function (asyncResult) {
                    write(asyncResult.value);
                });
            }
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

getTextAsync(options, callback)

Gets the text of an XML node in a custom XML part.

getTextAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<string>) => void): void;
Parameters
options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<string>) => void

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult. The value property of the result is a string that contains the inner text of the referenced nodes.

Returns
void
Remarks

Requirement SetsCustomXmlParts

Examples

// Get the built-in core properties XML part by using its ID. This results in a call to Word.
Office.context.document.customXmlParts.getByIdAsync(
    "{6C3C8BC8-F283-45AE-878A-BAB7291924A1}", function (getByIdAsyncResult) {

    // Access the XML part.
    var xmlPart = getByIdAsyncResult.value;

    // Add namespaces to the namespace manager. These two calls result in two calls to Word.
    xmlPart.namespaceManager.addNamespaceAsync(
        'cp',
        'http://schemas.openxmlformats.org/package/2006/metadata/core-properties',
        function () {
        xmlPart.namespaceManager.addNamespaceAsync(
            'dc', 
            'http://purl.org/dc/elements/1.1/', 
            function () {

            // Get XML nodes by using an Xpath expression. This results in a call to Word.
            xmlPart.getNodesAsync("/cp:coreProperties/dc:title", function (getNodesAsyncResult) {

                // Get the first node returned by using the Xpath expression. 
                var node = getNodesAsyncResult.value[0];

                // Get the text value of the node and use the asyncContext. This results in a call to Word. 
                // The results are logged to the browser console.
                node.getTextAsync({asyncContext: "StateNormal"}, function (getTextAsyncResult) {
                  console.log("Text of the title element = " + getTextAsyncResult.value;
                  console.log("The asyncContext value = " + getTextAsyncResult.asyncContext;
                });
            });
        });
    });
});

getXmlAsync(options, callback)

Gets the node's XML.

getXmlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<string>) => void): void;
Parameters
options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<string>) => void

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult. The value property of the result is a string that contains the XML of the referenced node.

Returns
void
Remarks

Requirement SetsCustomXmlParts

Examples

function showXmlNodeInnerXml() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getNodesAsync('*', function (nodeResults) {
            for (i = 0; i < nodeResults.value.length; i++) {
                var node = nodeResults.value[i];
                node.getXmlAsync(function (asyncResult) {
                    write(asyncResult.value);
                });
            }
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

setNodeValueAsync(value, options, callback)

Sets the node value.

setNodeValueAsync(value: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;
Parameters
value
string

The value to be set on the node

options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<void>) => void

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult.

Returns
void
Remarks

Requirement SetsCustomXmlParts

Examples

function setXmlNodeValue() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getNodesAsync('*/*', function (nodeResults) {
            for (i = 0; i < nodeResults.value.length; i++) {
                var node = nodeResults.value[i];
                write(node);
                node.setNodeValueAsync("item number" + i, {}, function (result) { });
            }
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

setTextAsync(text, options, callback)

Asynchronously sets the text of an XML node in a custom XML part.

setTextAsync(text: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;
Parameters
text
string

Required. The text value of the XML node.

options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<void>) => void

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult.

Returns
void
Remarks

HostsWord
Requirement SetsCustomXmlParts

Examples

// Learn how to set the text value of a node in a custom XML part from the following example.

// Get the built-in core properties XML part by using its ID. This results in a call to Word.
Office.context.document.customXmlParts.getByIdAsync(
    "{6C3C8BC8-F283-45AE-878A-BAB7291924A1}",
    function (getByIdAsyncResult) {

    // Access the XML part.
    var xmlPart = getByIdAsyncResult.value;

    // Add namespaces to the namespace manager. These two calls result in two calls to Word.
    xmlPart.namespaceManager.addNamespaceAsync(
        'cp', 
        'http://schemas.openxmlformats.org/package/2006/metadata/core-properties', 
        function () {
        xmlPart.namespaceManager.addNamespaceAsync(
            'dc', 
            'http://purl.org/dc/elements/1.1/', 
            function () {

            // Get XML nodes by using an Xpath expression. This results in a call to the host.
            xmlPart.getNodesAsync("/cp:coreProperties/dc:subject", function (getNodesAsyncResult) {

                // Get the first node returned by using the Xpath expression.
                // This will be the subject element in this example.
                var subjectNode = getNodesAsyncResult.value[0];

                // Set the text value of the subject node and use the asyncContext. 
                // This results in a call to the host.  The results are logged to the browser console.
                subjectNode.setTextAsync(
                    "newSubject", 
                    {asyncContext: "StateNormal"}, 
                    function (setTextAsyncResult) {
                        console.log("The status of the call: " + setTextAsyncResult.status);
                        console.log("The asyncContext value = " + setTextAsyncResult.asyncContext);
                });
            });
        });
    });
});

setXmlAsync(xml, options, callback)

Sets the node XML.

setXmlAsync(xml: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;
Parameters
xml
string

The XML to be set on the node

options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<void>) => void

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult.

Returns
void
Remarks

Requirement SetsCustomXmlParts

Examples

function setXmlNodeInnerXml() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getNodesAsync('*', function (nodeResults) {
            for (i = 0; i < nodeResults.value.length; i++) {
                var node = nodeResults.value[i];
                node.setXmlAsync("<childNode>" + i + "</childNode>");
            }
        });
    });
}