Office.CustomXmlParts interface

Represents a collection of CustomXmlPart objects.

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

Methods

addAsync(xml, options, callback)

Asynchronously adds a new custom XML part to a file.

getByIdAsync(id, options, callback)

Asynchronously gets the specified custom XML part by its id.

getByNamespaceAsync(ns, options, callback)

Asynchronously gets the specified custom XML part(s) by its namespace.

Method Details

addAsync(xml, options, callback)

Asynchronously adds a new custom XML part to a file.

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

The XML to add to the newly created custom XML part.

options
Office.AsyncContextOptions

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

callback
(result: AsyncResult<CustomXmlPart>) => 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 the newly created CustomXmlPart object.

Returns
void

Examples

function addXMLPart() {
    Office.context.document.customXmlParts.addAsync(
        '<root categoryId="1" xmlns="http://tempuri.org"><item name="Cheap Item" price="$193.95"/><item name="Expensive Item" price="$931.88"/></root>',
        function (result) {});
}

function addXMLPartandHandler() {
    Office.context.document.customXmlParts.addAsync(
        "<testns:book xmlns:testns='http://testns.com'><testns:page number='1'>Hello</testns:page><testns:page number='2'>world!</testns:page></testns:book>",
        function(r) { r.value.addHandlerAsync(Office.EventType.DataNodeDeleted,
            function(a) {write(a.type)
            },
                function(s) {write(s.status)
                });
        });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

getByIdAsync(id, options, callback)

Asynchronously gets the specified custom XML part by its id.

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

The GUID of the custom XML part, including opening and closing braces.

options
Office.AsyncContextOptions

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

callback
(result: AsyncResult<CustomXmlPart>) => 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 CustomXmlPart object that represents the specified custom XML part. If there is no custom XML part with the specified id, the method returns null.

Returns
void

Examples

function showXMLPartInnerXML() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.getXmlAsync({}, function (eventArgs) {
            write(eventArgs.value);
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

getByNamespaceAsync(ns, options, callback)

Asynchronously gets the specified custom XML part(s) by its namespace.

getByNamespaceAsync(ns: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<CustomXmlPart[]>) => void): void;
Parameters
ns
string

The namespace URI.

options
Office.AsyncContextOptions

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

callback
(result: AsyncResult<CustomXmlPart>) => 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 CustomXmlPart objects that match the specified namespace.

Returns
void

Examples

function showXMLPartsInNamespace() {
    Office.context.document.customXmlParts.getByNamespaceAsync(
        "http://tempuri.org", 
        function (eventArgs) {
            write("Found " + eventArgs.value.length + " parts with this namespace");
    }); 
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}