Word.ContentControlCollection class

Contains a collection of Word.ContentControl objects. Content controls are bounded and potentially labeled regions in a document that serve as containers for specific types of content. Individual content controls may contain contents such as images, tables, or paragraphs of formatted text. Currently, only rich text content controls are supported.

[ API set: WordApi 1.1 ]

Extends

Properties

items

Gets the loaded child items in this collection.

Methods

getById(id)

Gets a content control by its identifier. Throws if there isn't a content control with the identifier in this collection.

[ API set: WordApi 1.1 ]

getByIdOrNullObject(id)

Gets a content control by its identifier. Returns a null object if there isn't a content control with the identifier in this collection.

[ API set: WordApi 1.3 ]

getByTag(tag)

Gets the content controls that have the specified tag.

[ API set: WordApi 1.1 ]

getByTitle(title)

Gets the content controls that have the specified title.

[ API set: WordApi 1.1 ]

getByTypes(types)

Gets the content controls that have the specified types and/or subtypes.

[ API set: WordApi 1.3 ]

getFirst()

Gets the first content control in this collection. Throws if this collection is empty.

[ API set: WordApi 1.3 ]

getFirstOrNullObject()

Gets the first content control in this collection. Returns a null object if this collection is empty.

[ API set: WordApi 1.3 ]

getItem(index)

Gets a content control by its index in the collection.

[ API set: WordApi 1.1 ]

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

toJSON()
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 are 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 needed to have added the object to the tracked object collection when the object was first created.

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 will need to call "context.sync()" before the memory release takes effect.

Property Details

items

Gets the loaded child items in this collection.

readonly items: Word.ContentControl[];

Property Value

Word.ContentControl[]

Method Details

getById(id)

Gets a content control by its identifier. Throws if there isn't a content control with the identifier in this collection.

[ API set: WordApi 1.1 ]

getById(id: number): Word.ContentControl;

Parameters

id
number

Required. A content control identifier.

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the content control that contains a specific id.
    var contentControl = context.document.contentControls.getById(30086310);

    // Queue a command to load the text property for a content control.
    context.load(contentControl, 'text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        console.log('The content control with that Id has been found in this document.');
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});
// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the content control that contains a specific id.
    var contentControl = context.document.contentControls.getByIdOrNullObject(30086310);

    // Queue a command to load the text property for a content control.
    context.load(contentControl, 'text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        if (contentControl.isNullObject) {
            console.log('There is no content control with that ID.')
        } else {
            console.log('The content control with that ID has been found in this document.');
        }
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

getByIdOrNullObject(id)

Gets a content control by its identifier. Returns a null object if there isn't a content control with the identifier in this collection.

[ API set: WordApi 1.3 ]

getByIdOrNullObject(id: number): Word.ContentControl;

Parameters

id
number

Required. A content control identifier.

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the content control that contains a specific id.
    var contentControl = context.document.contentControls.getByIdOrNullObject(30086310);

    // Queue a command to load the text property for a content control.
    context.load(contentControl, 'text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        if (contentControl.isNullObject) {
            console.log('There is no content control with that ID.')
        } else {
            console.log('The content control with that ID has been found in this document.');
        }
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

getByTag(tag)

Gets the content controls that have the specified tag.

[ API set: WordApi 1.1 ]

getByTag(tag: string): Word.ContentControlCollection;

Parameters

tag
string

Required. A tag set on a content control.

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the content controls collection that contains a specific tag.
    var contentControlsWithTag = context.document.contentControls.getByTag('Customer-Address');

    // Queue a command to load the text property for all of content controls with a specific tag.
    context.load(contentControlsWithTag, 'text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        if (contentControlsWithTag.items.length === 0) {
            console.log("There isn't a content control with a tag of Customer-Address in this document.");
        } else {
            console.log(
                'The first content control with the tag of Customer-Address has this text: ' + 
                contentControlsWithTag.items[0].text);
        }

    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

// The Word-Add-in-DocumentAssembly sample has another example of using the getByTag method.
// https://github.com/OfficeDev/Word-Add-in-DocumentAssembly
await Word.run(async (context) => {
    let contentControls = context.document.contentControls.getByTag("customer");
    contentControls.load("text");

    await context.sync();

    for (let i = 0; i < contentControls.items.length; i++) {
      contentControls.items[i].insertText("Fabrikam", "Replace");
    }

    await context.sync();
});

getByTitle(title)

Gets the content controls that have the specified title.

[ API set: WordApi 1.1 ]

getByTitle(title: string): Word.ContentControlCollection;

Parameters

title
string

Required. The title of a content control.

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the content controls collection that contains a specific title.
    var contentControlsWithTitle = context.document.contentControls.getByTitle('Enter Customer Address Here');

    // Queue a command to load the text property for all of content controls with a specific title.
    context.load(contentControlsWithTitle, 'text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        if (contentControlsWithTitle.items.length === 0) {
            console.log(
                "There isn't a content control with a title of 'Enter Customer Address Here' in this document.");
        } else {
            console.log(
                "The first content control with the title of 'Enter Customer Address Here' has this text: " + 
                contentControlsWithTitle.items[0].text);
        }

    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

// The Word-Add-in-DocumentAssembly sample has another example of using the getByTitle method.
// https://github.com/OfficeDev/Word-Add-in-DocumentAssembly

getByTypes(types)

Gets the content controls that have the specified types and/or subtypes.

[ API set: WordApi 1.3 ]

getByTypes(types: Word.ContentControlType[]): Word.ContentControlCollection;

Parameters

types
Word.ContentControlType[]

Required. An array of content control types and/or subtypes.

Returns

getFirst()

Gets the first content control in this collection. Throws if this collection is empty.

[ API set: WordApi 1.3 ]

getFirst(): Word.ContentControl;

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the first content control in the document.
    var contentControl = context.document.contentControls.getFirstOrNullObject();

    // Queue a command to load the text property for a content control.
    context.load(contentControl, 'text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        if (contentControl.isNullObject) {
            console.log('There are no content controls in this document.')
        } else {
            console.log('The first content control has been found in this document.');
        }
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

getFirstOrNullObject()

Gets the first content control in this collection. Returns a null object if this collection is empty.

[ API set: WordApi 1.3 ]

getFirstOrNullObject(): Word.ContentControl;

Returns

getItem(index)

Gets a content control by its index in the collection.

[ API set: WordApi 1.1 ]

getItem(index: number): Word.ContentControl;

Parameters

index
number

The index.

Returns

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(option?: string | string[]): Word.ContentControlCollection;

Parameters

option
string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Remarks

In addition to this signature, this method has the following signatures:

load(option?: { select?: string; expand?: string; }): Word.ContentControlCollection - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Word.ContentControlCollection - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the content controls collection.
    var contentControls = context.document.contentControls;

    // Queue a command to load the id property for all of the content controls.
    context.load(contentControls, 'id');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        if (contentControls.items.length === 0) {
            console.log('No content control found.');
        }
        else {
            // Queue a command to load the properties on the first content control.
            contentControls.items[0].load(  'appearance,' +
                                            'cannotDelete,' +
                                            'cannotEdit,' +
                                            'id,' +
                                            'placeHolderText,' +
                                            'removeWhenEdited,' +
                                            'title,' +
                                            'text,' +
                                            'type,' +
                                            'style,' +
                                            'tag,' +
                                            'font/size,' +
                                            'font/name,' +
                                            'font/color');

            // Synchronize the document state by executing the queued commands,
            // and return a promise to indicate task completion.
            return context.sync()
                .then(function () {
                    console.log('Property values of the first content control:' +
                        '   ----- appearance: ' + contentControls.items[0].appearance +
                        '   ----- cannotDelete: ' + contentControls.items[0].cannotDelete +
                        '   ----- cannotEdit: ' + contentControls.items[0].cannotEdit +
                        '   ----- color: ' + contentControls.items[0].color +
                        '   ----- id: ' + contentControls.items[0].id +
                        '   ----- placeHolderText: ' + contentControls.items[0].placeholderText +
                        '   ----- removeWhenEdited: ' + contentControls.items[0].removeWhenEdited +
                        '   ----- title: ' + contentControls.items[0].title +
                        '   ----- text: ' + contentControls.items[0].text +
                        '   ----- type: ' + contentControls.items[0].type +
                        '   ----- style: ' + contentControls.items[0].style +
                        '   ----- tag: ' + contentControls.items[0].tag +
                        '   ----- font size: ' + contentControls.items[0].font.size +
                        '   ----- font name: ' + contentControls.items[0].font.name +
                        '   ----- font color: ' + contentControls.items[0].font.color);
            });
        }
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

// The Silly stories add-in sample shows how the load method is used
// to load the content control collection with the tag and title properties.
// https://aka.ms/sillystorywordaddin

toJSON()

toJSON(): Word.Interfaces.ContentControlCollectionData;

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 are 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 needed to have added the object to the tracked object collection when the object was first created.

track(): Word.ContentControlCollection;

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 will need to call "context.sync()" before the memory release takes effect.

untrack(): Word.ContentControlCollection;

Returns