Office Add-Ins: Working with Tables in Word. Part 4: Getting a table in a Content Control

In this article we will see how to use a ContentControl to quickly and accurately access a table in a Word document.

Introduction

In previous articles we have seen how to get a Table using a search or cycling through allTables in the document. While these are two perfectly valid methods they come with some potential issues and considerations for architecting the Word document itself. In this article we will see how to control access to the right table at the right time without the concerns or issues from the previous article.

Content Controls

Rich Text Content controls are the only content controls supported in Office.js (as of version 1.3). The documentation for the Content control API documentation shows us that we can get a content control via a “tag” which is assigned to the Content Control in Developer Mode within the word document.

Create a Content Control on your word document and give it a Tag (Birds in this case)

In normal mode we can then insert a table

Using the following code we can access the content control, get the first (only) table inside there and manipulate it by adding a new row.

async function runContent() {
    await Word.run(async (context) => {

        // Create a proxy object for the content controls collection that contains a specific tag.
        var contentBirds = context.document.contentControls.getByTag('Birds');
        // Queue a command to load the tag property for all of content controls. 
        context.load(contentBirds, 'tag');
        await context.sync()

        // Queue a commmand to load the results.
        const tableCollection = contentBirds.items[0].tables;
        context.load(tableCollection);
        await context.sync()
        var theTable = tableCollection.items[0];
        context.load(theTable, '');
        await context.sync();
        let numRows = theTable.rowCount.toString()
        theTable.addRows("End", 1, [[numRows, "Phoenix"]])
        
    });
}

The inserted row can be seen, and in a similar manner to the previous article we can log the amount of time taken to execute the function. In this case it is slightly slower (100ms) than searching (80ms) (there is more context loading) but it is consistent and does not come with any of the disadvantages of having to search for a specific term in a table.

Note

The obvious downside to this method is if a user of the word document takes the table out of the content control (either on purpose or by mistake). Checks should be put int he code to determine that if the table cannot be found then call the elgant error handling.

Conclusion

This is the most reliable manner for accessing a table quickly and accurately within a Word document, but does come with a small amount of additional overhead and the extra construct of having to have a Content Control within the Word document.