Office.CustomXmlPart interface

Represents a single CustomXMLPart in an Office.CustomXmlParts collection.

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

builtIn

True, if the custom XML part is built in; otherwise false.

id

Gets the GUID of the CustomXMLPart.

namespaceManager

Gets the set of namespace prefix mappings (Office.CustomXmlPrefixMappings) used against the current CustomXmlPart.

Methods

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler to the object using the specified event type.

deleteAsync(options, callback)

Deletes the Custom XML Part.

getNodesAsync(xPath, options, callback)

Asynchronously gets any CustomXmlNodes in this custom XML part which match the specified XPath.

getXmlAsync(options, callback)

Asynchronously gets the XML inside this custom XML part.

removeHandlerAsync(eventType, handler, options, callback)

Removes an event handler for the specified event type.

Property Details

builtIn

True, if the custom XML part is built in; otherwise false.

builtIn: boolean;

Property Value

boolean

Examples

function showXMLPartBuiltIn() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        write(xmlPart.builtIn);
    });
}

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

id

Gets the GUID of the CustomXMLPart.

id: string;

Property Value

string

Examples

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

namespaceManager

Gets the set of namespace prefix mappings (Office.CustomXmlPrefixMappings) used against the current CustomXmlPart.

namespaceManager: CustomXmlPrefixMappings;

Property Value

Examples

function setXMLPartNamespaceManagerNamespace() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.namespaceManager.addNamespaceAsync("myPrefix", "myNamespace");
    });
}

Method Details

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler to the object using the specified event type.

addHandlerAsync(eventType: Office.EventType, handler: (result: any) => void, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameters

eventType
Office.EventType

Specifies the type of event to add. For a CustomXmlPart object, the eventType parameter can be specified as Office.EventType.NodeDeleted, Office.EventType.NodeInserted, and Office.EventType.NodeReplaced.

handler
(result: any) => void

The event handler function to add, whose only parameter is of type Office.NodeDeletedEventArgs, Office.NodeInsertedEventArgs, or Office.NodeReplacedEventArgs

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

You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique.

Examples

// To add an event handler for the NodeDeleted event, use the addHandlerAsync method of the CustomXmlPart object.
function addNodeDeletedEvent() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.addHandlerAsync(Office.EventType.NodeDeleted, function (eventArgs) {
            write("A node has been deleted.");
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}
// To add an event handler for the NodeInserted event, use the addHandlerAsync method of the CustomXmlPart object.
function addNodeInsertedEvent() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.addHandlerAsync(Office.EventType.NodeInserted, function (eventArgs) {
            write("A node has been inserted.");
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}
// To add an event handler for the NodeReplaced event, use the addHandlerAsync method of the CustomXmlPart object.
function addNodeReplacedEvent() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        var xmlPart = result.value;
        xmlPart.addHandlerAsync(Office.EventType.NodeReplaced, function (eventArgs) {
            write("A node has been replaced.");
        });
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

deleteAsync(options, callback)

Deletes the Custom XML Part.

deleteAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => 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<void>) => void

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

Returns

void

Examples

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

getNodesAsync(xPath, options, callback)

Asynchronously gets any CustomXmlNodes in this custom XML part which match the specified XPath.

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

Parameters

xPath
string

An XPath expression that specifies the nodes you want returned. 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

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; 
}

getXmlAsync(options, callback)

Asynchronously gets the XML inside this custom XML part.

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 CustomXmlPart object.

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; 
}

removeHandlerAsync(eventType, handler, options, callback)

Removes an event handler for the specified event type.

removeHandlerAsync(eventType: Office.EventType, handler?: (result: any) => void, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameters

eventType
Office.EventType

Specifies the type of event to remove. For a CustomXmlPart object, the eventType parameter can be specified as Office.EventType.NodeDeleted, Office.EventType.NodeInserted, and Office.EventType.NodeReplaced.

handler
(result: any) => void

The name of the handler to remove.

options
Office.RemoveHandlerOptions

Provides options to determine which event handler or handlers are removed.

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

Examples

function removeNodeInsertedEventHandler() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}",
        function (result) {
            var xmlPart = result.value;
            xmlPart.removeHandlerAsync(Office.EventType.DataNodeInserted, {handler:myHandler});
    });
}