Applies to: All add-in types
When an add-in is initialized, it has many different objects that it can interact with in the runtime environment. The add-in's runtime context is reflected in the API by the Context object. The Context is the main object that provides access to the most important objects of the API, such as the Document and Mailbox objects, which in turn provide access to document and mailbox content.
For example, in task pane or content add-ins, you can use the document property of the Context object to access the properties and methods of the Document object to interact with the content of Word documents, Excel worksheets, or Project schedules. Similarly, in Outlook add-ins, you can use the mailbox property of the Context object to access the properties and methods of the Mailbox object to interact with the message, meeting request, or appointment content.
The Context object also provides access to the contentLanguage and displayLanguage properties that let you determine the locale (language) used in the document or item, or by the Office application. The roamingSettings property lets you access the members of the RoamingSettings object, which stores settings specific to your add-in for individual users' mailboxes. Finally, the Context object provides a ui property that enables your add-in to launch pop-up dialogs.
Applies to: Content and task pane add-in types
To interact with document data in Excel, PowerPoint, and Word, the API provides the Document object. You can use
Document object members to access data from the following ways.
Read and write to active selections in the form of text, contiguous cells (matrices), or tables.
Tabular data (matrices or tables).
Bindings (created with the "add" methods of the
Custom XML parts (only for Word).
Settings or add-in state persisted per add-in on the document.
You can also use the
Document object to interact with data in Project documents. The Project-specific functionality of the API is documented in the members ProjectDocument abstract class. For more information about creating task pane add-ins for Project, see Task pane add-ins for Project.
All these forms of data access start from an instance of the abstract
You can access an instance of the
Document object when the task pane or content add-in is initialized by using the document property of the
Context object. The
Document object defines common data access methods shared across Word and Excel documents, and also provides access to the
CustomXmlParts object for Word documents.
Document object supports four ways for developers to access document contents.
Custom XML part-based access (Word only)
Entire document-based access (PowerPoint and Word only)
To help you understand how selection- and binding-based data access methods work, we will first explain how the data-access APIs provide consistent data access across different Office applications.
Consistent data access across Office applications
Applies to: Content and task pane add-in types
Common data types
In both selection-based and binding-based data access, document contents are exposed through data types that are common across all the supported Office applications. Three main data types are supported.
|Data type||Description||Host application support|
|Text||Provides a string representation of the data in the selection or binding.||In Excel, Project, and PowerPoint, only plain text is supported. In Word, three text formats are supported: plain text, HTML, and Office Open XML (OOXML). When text is selected in a cell in Excel, selection-based methods read and write to the entire contents of the cell, even if only a portion of the text is selected in the cell. When text is selected in Word and PowerPoint, selection-based methods read and write only to the run of characters that are selected. Project and PowerPoint support only selection-based data access.|
||Matrix data access is supported only in Excel and Word.|
|Table||Provides the data in the selection or binding as a TableData object. The
||Table data access is supported only in Excel and Word.|
Data type coercion
The data access methods on the
Document and Binding objects support specifying the desired data type using the coercionType parameter of these methods, and corresponding CoercionType enumeration values. Regardless of the actual shape of the binding, the different Office applications support the common data types by trying to coerce the data into the requested data type. For example, if a Word table or paragraph is selected, the developer can specify to read it as plain text, HTML, Office Open XML, or a table, and the API implementation handles the necessary transformations and data conversions.
When should you use the matrix versus table coercionType for data access? If you need your tabular data to grow dynamically when rows and columns are added, and you must work with table headers, you should use the table data type (by specifying the coercionType parameter of a
Binding object data access method as
Office.CoercionType.Table). Adding rows and columns within the data structure is supported in both table and matrix data, but appending rows and columns is supported only for table data. If you aren't planning on adding rows and columns, and your data doesn't require header functionality, then you should use the matrix data type (by specifying the coercionType parameter of the data access method as
Office.CoercionType.Matrix), which provides a simpler model of interacting with the data.
If the data can't be coerced to the specified type, the AsyncResult.status property in the callback returns
"failed", and you can use the AsyncResult.error property to access an Error object with information about why the method call failed.
Work with selections using the Document object
Document object exposes methods that let you to read and write to the user's current selection in a "get and set" fashion. To do that, the
Document object provides the
For code examples that demonstrate how to perform tasks with selections, see Read and write data to the active selection in a document or spreadsheet.
Work with bindings using the Bindings and Binding objects
Binding-based data access enables content and task pane add-ins to consistently access a particular region of a document or spreadsheet through an identifier associated with a binding. The add-in first needs to establish the binding by calling one of the methods that associates a portion of the document with a unique identifier: addFromPromptAsync, addFromSelectionAsync, or addFromNamedItemAsync. After the binding is established, the add-in can use the provided identifier to access the data contained in the associated region of the document or spreadsheet. Creating bindings provides the following value to your add-in.
Permits access to common data structures across supported Office applications, such as: tables, ranges, or text (a contiguous run of characters).
Enables read/write operations without requiring the user to make a selection.
Establishes a relationship between the add-in and the data in the document. Bindings are persisted in the document, and can be accessed at a later time.
Establishing a binding also allows you to subscribe to data and selection change events that are scoped to that particular region of the document or spreadsheet. This means that the add-in is only notified of changes that happen within the bound region as opposed to general changes across the whole document or spreadsheet.
The Bindings object exposes a getAllAsync method that gives access to the set of all bindings established on the document or spreadsheet. An individual binding can be accessed by its ID using either the Bindings.getBindingByIdAsync method or Office.select function. You can establish new bindings as well as remove existing ones by using one of the following methods of the
Bindings object: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync, or releaseByIdAsync.
There are three different types of bindings that you specify with the bindingType parameter when you create a binding with the
|Binding type||Description||Host application support|
|Text binding||Binds to a region of the document that can be represented as text.||In Word, most contiguous selections are valid, while in Excel only single cell selections can be the target of a text binding. In Excel, only plain text is supported. In Word, three formats are supported: plain text, HTML, and Open XML for Office.|
||In Excel, any contiguous selection of cells can be used to establish a matrix binding. In Word, only tables support matrix binding.|
|Table binding||Binds to a region of a document that contains a table with headers. Data in a table binding is written or read as a TableData object. The
||Any Excel or Word table can be the basis for a table binding. After you establish a table binding, each new row or column a user adds to the table is automatically included in the binding.|
After a binding is created by using one of the three "add" methods of the
Bindings object, you can work with the binding's data and properties by using the methods of the corresponding object: MatrixBinding, TableBinding, or TextBinding. All three of these objects inherit the getDataAsync and setDataAsync methods of the
Binding object that enable to you interact with the bound data.
For code examples that demonstrate how to perform tasks with bindings, see Bind to regions in a document or spreadsheet.
Work with custom XML parts using the CustomXmlParts and CustomXmlPart objects
Applies to: Task pane add-ins for Word
The CustomXmlParts and CustomXmlPart objects of the API provide access to custom XML parts in Word documents, which enable XML-driven manipulation of the contents of the document. For demonstrations of working with the
CustomXmlPart objects, see the Word-add-in-Work-with-custom-XML-parts code sample.
Work with the entire document using the getFileAsync method
Applies to: Task pane add-ins for Word and PowerPoint
The Document.getFileAsync method and members of the File and Slice objects to provide functionality for getting entire Word and PowerPoint document files in slices (chunks) of up to 4 MB at a time. For more information, see Get the whole document from an add-in for PowerPoint or Word.
Applies to: Outlook add-ins
Outlook add-ins primarily use a subset of the API exposed through the Mailbox object. To access the objects and members specifically for use in Outlook add-ins, such as the Item object, use the mailbox property of the Context object to access the Mailbox object, as shown in the following line of code.
// Access the Item object. const item = Office.context.mailbox.item;
Additionally, Outlook add-ins can use the following objects.
Office object: for initialization.
Context object: for access to content and display language properties.
RoamingSettings object: for saving Outlook add-in-specific custom settings to the user's mailbox where the add-in is installed.