Office.CustomXmlPart interface

  • Reference
Package:
office

Represents a single CustomXMLPart in an Office.CustomXmlParts collection.

Remarks

Applications: Word

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.
addHandlerAsync(eventType, handler, callback)

Adds an event handler to the object using the specified event type.
deleteAsync(options, callback)

Deletes the Custom XML Part.
deleteAsync(callback)

Deletes the Custom XML Part.
getNodesAsync(xPath, options, callback)

Asynchronously gets any CustomXmlNodes in this custom XML part which match the specified XPath.
getNodesAsync(xPath, 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.
getXmlAsync(callback)

Asynchronously gets the XML inside this custom XML part.
removeHandlerAsync(eventType, handler, options, callback)

Removes an event handler for the specified event type.
removeHandlerAsync(eventType, handler, 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) {
        const 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) {
        const 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

Office.CustomXmlPrefixMappings

Examples

function setXMLPartNamespaceManagerNamespace() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        const 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: Office.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 set: CustomXmlParts

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

addHandlerAsync(eventType, handler, callback)

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

addHandlerAsync(eventType: Office.EventType, handler: (result: any) => void, 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

callback

(result: Office.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 set: CustomXmlParts

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) {
        const 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) {
        const 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) {
        const 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: Office.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 set: CustomXmlParts

deleteAsync(callback)

Deletes the Custom XML Part.

deleteAsync(callback?: (result: AsyncResult<void>) => void): void;

Parameters

callback

(result: Office.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 set: CustomXmlParts

Examples

function deleteXMLPart() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        const 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: Office.AsyncResult<Office.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 set: CustomXmlParts

getNodesAsync(xPath, callback)

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

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

Parameters

xPath

string

An XPath expression that specifies the nodes you want returned. Required.

callback

(result: Office.AsyncResult<Office.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 set: CustomXmlParts

Examples

function showXmlNodeType() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        const xmlPart = result.value;
        xmlPart.getNodesAsync('*/*', function (nodeResults) {
            for (let i = 0; i < nodeResults.value.length; i++) {
                const 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: Office.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

Remarks

Requirement set: CustomXmlParts

getXmlAsync(callback)

Asynchronously gets the XML inside this custom XML part.

getXmlAsync(callback?: (result: AsyncResult<string>) => void): void;

Parameters

callback

(result: Office.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

Remarks

Requirement set: CustomXmlParts

Examples

function showXMLPartInnerXML() {
    Office.context.document.customXmlParts.getByIdAsync(
        "{3BC85265-09D6-4205-B665-8EB239A8B9A1}", function (result) {
        const 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: Office.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 set: CustomXmlParts

removeHandlerAsync(eventType, handler, callback)

Removes an event handler for the specified event type.

removeHandlerAsync(eventType: Office.EventType, handler?: (result: any) => void, 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.

callback

(result: Office.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 set: CustomXmlParts

Examples

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