Word.CustomXmlPart class
Represents a custom XML part.
- Extends
Remarks
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| id | Gets the ID of the custom XML part. |
| namespace |
Gets the namespace URI of the custom XML part. |
Methods
| delete() | Deletes the custom XML part. |
| delete |
Deletes an attribute with the given name from the element identified by xpath. |
| delete |
Deletes the element identified by xpath. |
| get |
Gets the full XML content of the custom XML part. |
| insert |
Inserts an attribute with the given name and value to the element identified by xpath. |
| insert |
Inserts the given XML under the parent element identified by xpath at child position index. |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| query(xpath, namespace |
Queries the XML content of the custom XML part. |
| set |
Sets the full XML content of the custom XML part. |
| toJSON() | Overrides the JavaScript |
| 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 |
| 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 |
| update |
Updates the value of an attribute with the given name of the element identified by xpath. |
| update |
Updates the XML of the element identified by xpath. |
Property Details
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
id
Gets the ID of the custom XML part.
readonly id: string;Property Value
string
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part.yaml
// Adds a custom XML part.
await Word.run(async (context) => {
const originalXml =
"<Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
const customXmlPart = context.document.customXmlParts.add(originalXml);
customXmlPart.load("id");
const xmlBlob = customXmlPart.getXml();
await context.sync();
const readableXml = addLineBreaksToXML(xmlBlob.value);
console.log("Added custom XML part:");
console.log(readableXml);
// Store the XML part's ID in a setting so the ID is available to other functions.
const settings = context.document.settings;
settings.add("ContosoReviewXmlPartId", customXmlPart.id);
await context.sync();
});
namespaceUri
Gets the namespace URI of the custom XML part.
readonly namespaceUri: string;Property Value
string
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml
// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Gets the namespace URI from a custom XML part.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
const customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
customXmlPart.load("namespaceUri");
await context.sync();
const namespaceUri = customXmlPart.namespaceUri;
console.log(`Namespace URI: ${JSON.stringify(namespaceUri)}`);
} else {
console.warn("Didn't find custom XML part");
}
});
Method Details
delete()
Deletes the custom XML part.
delete(): void;Returns
void
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part.yaml
// Original XML: <Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Deletes a custom XML part.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
let customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
const xmlBlob = customXmlPart.getXml();
customXmlPart.delete();
customXmlPart = context.document.customXmlParts.getItemOrNullObject(xmlPartIDSetting.value);
await context.sync();
if (customXmlPart.isNullObject) {
console.log(`The XML part with the ID ${xmlPartIDSetting.value} has been deleted`);
// Delete the associated setting too.
xmlPartIDSetting.delete();
await context.sync();
} else {
const readableXml = addLineBreaksToXML(xmlBlob.value);
const strangeMessage = `This is strange. The XML part with the id ${xmlPartIDSetting.value} wasn't deleted:\n${readableXml}`;
console.error(strangeMessage);
}
} else {
console.warn("Didn't find custom XML part to delete");
}
});
...
// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Deletes a custom XML part.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
let customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
const xmlBlob = customXmlPart.getXml();
customXmlPart.delete();
customXmlPart = context.document.customXmlParts.getItemOrNullObject(xmlPartIDSetting.value);
await context.sync();
if (customXmlPart.isNullObject) {
console.log(`The XML part with the ID ${xmlPartIDSetting.value} has been deleted`);
// Delete the associated setting too.
xmlPartIDSetting.delete();
await context.sync();
} else {
const readableXml = addLineBreaksToXML(xmlBlob.value);
const strangeMessage = `This is strange. The XML part with the id ${xmlPartIDSetting.value} wasn't deleted:\n${readableXml}`;
console.error(strangeMessage);
}
} else {
console.warn("Didn't find custom XML part to delete");
}
});
deleteAttribute(xpath, namespaceMappings, name)
Deletes an attribute with the given name from the element identified by xpath.
deleteAttribute(xpath: string, namespaceMappings: {
[key: string]: string;
}, name: string): void;Parameters
- xpath
-
string
Required. Absolute path to the single element in XPath notation.
- namespaceMappings
-
{ [key: string]: string; }
Required. An object whose property values are namespace names and whose property names are aliases for the corresponding namespaces. For example, {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. The property names (such as "greg") can be any string that doesn't used reserved XPath characters, such as the forward slash "/".
- name
-
string
Required. Name of the attribute.
Returns
void
Remarks
If any element in the tree has an xmlns attribute (whose value is typically, but not always, a URI), an alias for that attribute value must prefix the element name in the xpath parameter. For example, suppose the tree is the following:
<Day>
<Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
<Week>something</Week>
</Month>
</Day>
The xpath to <Week> must be /Day/greg:Month/Week, where greg is an alias that is mapped to "http://calendartypes.org/xsds/GregorianCalendar" in the namespaceMappings parameter.
deleteElement(xpath, namespaceMappings)
Deletes the element identified by xpath.
deleteElement(xpath: string, namespaceMappings: {
[key: string]: string;
}): void;Parameters
- xpath
-
string
Required. Absolute path to the single element in XPath notation.
- namespaceMappings
-
{ [key: string]: string; }
Required. An object whose property values are namespace names and whose property names are aliases for the corresponding namespaces. For example, {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. The property names (such as "greg") can be any string that doesn't used reserved XPath characters, such as the forward slash "/".
Returns
void
Remarks
If any element in the tree has an xmlns attribute (whose value is typically, but not always, a URI), an alias for that attribute value must prefix the element name in the xpath parameter. For example, suppose the tree is the following:
<Day>
<Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
<Week>something</Week>
</Month>
</Day>
The xpath to <Week> must be /Day/greg:Month/Week, where greg is an alias that is mapped to "http://calendartypes.org/xsds/GregorianCalendar" in the namespaceMappings parameter.
getXml()
Gets the full XML content of the custom XML part.
getXml(): OfficeExtension.ClientResult<string>;Returns
OfficeExtension.ClientResult<string>
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml
// Adds a custom XML part.
// If you want to populate the CustomXml.namespaceUri property, you must include the xmlns attribute.
await Word.run(async (context) => {
const originalXml =
"<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
const customXmlPart = context.document.customXmlParts.add(originalXml);
customXmlPart.load(["id", "namespaceUri"]);
const xmlBlob = customXmlPart.getXml();
await context.sync();
const readableXml = addLineBreaksToXML(xmlBlob.value);
console.log(`Added custom XML part with namespace URI ${customXmlPart.namespaceUri}:`);
console.log(readableXml);
// Store the XML part's ID in a setting so the ID is available to other functions.
const settings = context.document.settings;
settings.add("ContosoReviewXmlPartIdNS", customXmlPart.id);
await context.sync();
});
...
// Adds a custom XML part.
await Word.run(async (context) => {
const originalXml =
"<Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
const customXmlPart = context.document.customXmlParts.add(originalXml);
customXmlPart.load("id");
const xmlBlob = customXmlPart.getXml();
await context.sync();
const readableXml = addLineBreaksToXML(xmlBlob.value);
console.log("Added custom XML part:");
console.log(readableXml);
// Store the XML part's ID in a setting so the ID is available to other functions.
const settings = context.document.settings;
settings.add("ContosoReviewXmlPartId", customXmlPart.id);
await context.sync();
});
insertAttribute(xpath, namespaceMappings, name, value)
Inserts an attribute with the given name and value to the element identified by xpath.
insertAttribute(xpath: string, namespaceMappings: {
[key: string]: string;
}, name: string, value: string): void;Parameters
- xpath
-
string
Required. Absolute path to the single element in XPath notation.
- namespaceMappings
-
{ [key: string]: string; }
Required. An object whose property values are namespace names and whose property names are aliases for the corresponding namespaces. For example, {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. The property names (such as "greg") can be any string that doesn't used reserved XPath characters, such as the forward slash "/".
- name
-
string
Required. Name of the attribute.
- value
-
string
Required. Value of the attribute.
Returns
void
Remarks
If any element in the tree has an xmlns attribute (whose value is typically, but not always, a URI), an alias for that attribute value must prefix the element name in the xpath parameter. For example, suppose the tree is the following:
<Day>
<Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
<Week>something</Week>
</Month>
</Day>
The xpath to <Week> must be /Day/greg:Month/Week, where greg is an alias that is mapped to "http://calendartypes.org/xsds/GregorianCalendar" in the namespaceMappings parameter.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml
// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Inserts an attribute into a custom XML part.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
const customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
// The insertAttribute method inserts an attribute with the given name and value into the element identified by the xpath parameter.
customXmlPart.insertAttribute(
"/contoso:Reviewers",
{ contoso: "http://schemas.contoso.com/review/1.0" },
"Nation",
"US"
);
const xmlBlob = customXmlPart.getXml();
await context.sync();
const readableXml = addLineBreaksToXML(xmlBlob.value);
console.log("Successfully inserted attribute:");
console.log(readableXml);
} else {
console.warn("Didn't find custom XML part to insert attribute into");
}
});
...
// Original XML: <Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Inserts an attribute into a custom XML part.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
const customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
// The insertAttribute method inserts an attribute with the given name and value into the element identified by the xpath parameter.
customXmlPart.insertAttribute("/Reviewers", { contoso: "http://schemas.contoso.com/review/1.0" }, "Nation", "US");
const xmlBlob = customXmlPart.getXml();
await context.sync();
const readableXml = addLineBreaksToXML(xmlBlob.value);
console.log("Successfully inserted attribute:");
console.log(readableXml);
} else {
console.warn("Didn't find custom XML part to insert attribute into");
}
});
insertElement(xpath, xml, namespaceMappings, index)
Inserts the given XML under the parent element identified by xpath at child position index.
insertElement(xpath: string, xml: string, namespaceMappings: {
[key: string]: string;
}, index?: number): void;Parameters
- xpath
-
string
Required. Absolute path to the single parent element in XPath notation.
- xml
-
string
Required. XML content to be inserted.
- namespaceMappings
-
{ [key: string]: string; }
Required. An object whose property values are namespace names and whose property names are aliases for the corresponding namespaces. For example, {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. The property names (such as "greg") can be any string that doesn't used reserved XPath characters, such as the forward slash "/".
- index
-
number
Optional. Zero-based position at which the new XML to be inserted. If omitted, the XML will be appended as the last child of this parent.
Returns
void
Remarks
If any element in the tree has an xmlns attribute (whose value is typically, but not always, a URI), an alias for that attribute value must prefix the element name in the xpath parameter. For example, suppose the tree is the following:
<Day>
<Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
<Week>something</Week>
</Month>
</Day>
The xpath to <Week> must be /Day/greg:Month/Week, where greg is an alias that is mapped to "http://calendartypes.org/xsds/GregorianCalendar" in the namespaceMappings parameter.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml
// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Inserts an element into a custom XML part.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
const customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
// The insertElement method inserts the given XML under the parent element identified by the xpath parameter at the provided child position index.
customXmlPart.insertElement(
"/contoso:Reviewers",
"<Lead>Mark</Lead>",
{ contoso: "http://schemas.contoso.com/review/1.0" },
0
);
const xmlBlob = customXmlPart.getXml();
await context.sync();
const readableXml = addLineBreaksToXML(xmlBlob.value);
console.log("Successfully inserted element:");
console.log(readableXml);
} else {
console.warn("Didn't find custom XML part to insert element into");
}
});
...
// Original XML: <Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Inserts an element into a custom XML part.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
const customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
// The insertElement method inserts the given XML under the parent element identified by the xpath parameter at the provided child position index.
customXmlPart.insertElement(
"/Reviewers",
"<Lead>Mark</Lead>",
{ contoso: "http://schemas.contoso.com/review/1.0" },
0
);
const xmlBlob = customXmlPart.getXml();
await context.sync();
const readableXml = addLineBreaksToXML(xmlBlob.value);
console.log("Successfully inserted element:");
console.log(readableXml);
} else {
console.warn("Didn't find custom XML part to insert element into");
}
});
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.CustomXmlPartLoadOptions): Word.CustomXmlPart;Parameters
Provides options for which properties of the object to load.
Returns
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.CustomXmlPart;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
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.CustomXmlPart;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
query(xpath, namespaceMappings)
Queries the XML content of the custom XML part.
query(xpath: string, namespaceMappings: {
[key: string]: string;
}): OfficeExtension.ClientResult<string[]>;Parameters
- xpath
-
string
Required. An XPath query.
- namespaceMappings
-
{ [key: string]: string; }
Required. An object whose property values are namespace names and whose property names are aliases for the corresponding namespaces. For example, {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. The property names (such as "greg") can be any string that doesn't used reserved XPath characters, such as the forward slash "/".
Returns
OfficeExtension.ClientResult<string[]>
An array where each item represents an entry matched by the XPath query.
Remarks
If any element in the tree has an xmlns attribute (whose value is typically, but not always, a URI), an alias for that attribute value must prefix the element name in the xpath parameter. For example, suppose the tree is the following:
<Day>
<Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
<Week>something</Week>
</Month>
</Day>
The xpath to <Week> must be /Day/greg:Month/Week, where greg is an alias that is mapped to "http://calendartypes.org/xsds/GregorianCalendar" in the namespaceMappings parameter.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml
// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Queries a custom XML part for elements matching the search terms.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
const customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
const xpathToQueryFor = "/contoso:Reviewers";
const clientResult = customXmlPart.query(xpathToQueryFor, {
contoso: "http://schemas.contoso.com/review/1.0"
});
await context.sync();
console.log(`Queried custom XML part for ${xpathToQueryFor} and found ${clientResult.value.length} matches:`);
for (let i = 0; i < clientResult.value.length; i++) {
console.log(clientResult.value[i]);
}
} else {
console.warn("Didn't find custom XML part to query");
}
});
...
// Original XML: <Reviewers><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Queries a custom XML part for elements matching the search terms.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartId").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
const customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
const xpathToQueryFor = "/Reviewers/Reviewer";
const clientResult = customXmlPart.query(xpathToQueryFor, {
contoso: "http://schemas.contoso.com/review/1.0"
});
await context.sync();
console.log(`Queried custom XML part for ${xpathToQueryFor} and found ${clientResult.value.length} matches:`);
for (let i = 0; i < clientResult.value.length; i++) {
console.log(clientResult.value[i]);
}
} else {
console.warn("Didn't find custom XML part to query");
}
});
setXml(xml)
Sets the full XML content of the custom XML part.
setXml(xml: string): void;Parameters
- xml
-
string
Required. XML content to be set.
Returns
void
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-custom-xml-part-ns.yaml
// Original XML: <Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>
// Replaces a custom XML part.
await Word.run(async (context) => {
const settings = context.document.settings;
const xmlPartIDSetting = settings.getItemOrNullObject("ContosoReviewXmlPartIdNS").load("value");
await context.sync();
if (xmlPartIDSetting.value) {
const customXmlPart = context.document.customXmlParts.getItem(xmlPartIDSetting.value);
const originalXmlBlob = customXmlPart.getXml();
await context.sync();
let readableXml = addLineBreaksToXML(originalXmlBlob.value);
console.log("Original custom XML part:");
console.log(readableXml);
// The setXml method replaces the entire XML part.
customXmlPart.setXml(
"<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>John</Reviewer><Reviewer>Hitomi</Reviewer></Reviewers>"
);
const updatedXmlBlob = customXmlPart.getXml();
await context.sync();
readableXml = addLineBreaksToXML(updatedXmlBlob.value);
console.log("Replaced custom XML part:");
console.log(readableXml);
} else {
console.warn("Didn't find custom XML part to replace");
}
});
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 is passed to it.) Whereas the original Word.CustomXmlPart object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.CustomXmlPartData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): Word.Interfaces.CustomXmlPartData;Returns
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.CustomXmlPart;Returns
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.CustomXmlPart;Returns
updateAttribute(xpath, namespaceMappings, name, value)
Updates the value of an attribute with the given name of the element identified by xpath.
updateAttribute(xpath: string, namespaceMappings: {
[key: string]: string;
}, name: string, value: string): void;Parameters
- xpath
-
string
Required. Absolute path to the single element in XPath notation.
- namespaceMappings
-
{ [key: string]: string; }
Required. An object whose property values are namespace names and whose property names are aliases for the corresponding namespaces. For example, {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. The property names (such as "greg") can be any string that doesn't used reserved XPath characters, such as the forward slash "/".
- name
-
string
Required. Name of the attribute.
- value
-
string
Required. New value of the attribute.
Returns
void
Remarks
If any element in the tree has an xmlns attribute (whose value is typically, but not always, a URI), an alias for that attribute value must prefix the element name in the xpath parameter. For example, suppose the tree is the following:
<Day>
<Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
<Week>something</Week>
</Month>
</Day>
The xpath to <Week> must be /Day/greg:Month/Week, where greg is an alias that is mapped to "http://calendartypes.org/xsds/GregorianCalendar" in the namespaceMappings parameter.
updateElement(xpath, xml, namespaceMappings)
Updates the XML of the element identified by xpath.
updateElement(xpath: string, xml: string, namespaceMappings: {
[key: string]: string;
}): void;Parameters
- xpath
-
string
Required. Absolute path to the single element in XPath notation.
- xml
-
string
Required. New XML content to be stored.
- namespaceMappings
-
{ [key: string]: string; }
Required. An object whose property values are namespace names and whose property names are aliases for the corresponding namespaces. For example, {greg: "http://calendartypes.org/xsds/GregorianCalendar"}. The property names (such as "greg") can be any string that doesn't used reserved XPath characters, such as the forward slash "/".
Returns
void
Remarks
If any element in the tree has an xmlns attribute (whose value is typically, but not always, a URI), an alias for that attribute value must prefix the element name in the xpath parameter. For example, suppose the tree is the following:
<Day>
<Month xmlns="http://calendartypes.org/xsds/GregorianCalendar">
<Week>something</Week>
</Month>
</Day>
The xpath to <Week> must be /Day/greg:Month/Week, where greg is an alias that is mapped to "http://calendartypes.org/xsds/GregorianCalendar" in the namespaceMappings parameter.
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for