Office.Bindings interface

Represents the bindings the add-in has within the document.

Properties

document

Gets an Office.Document object that represents the document associated with this set of bindings.

Methods

addFromNamedItemAsync(itemName, bindingType, options, callback)

Creates a binding against a named object in the document.

addFromPromptAsync(bindingType, options, callback)

Create a binding by prompting the user to make a selection on the document.

addFromSelectionAsync(bindingType, options, callback)

Create a binding based on the user's current selection.

getAllAsync(options, callback)

Gets all bindings that were previously created.

getByIdAsync(id, options, callback)

Retrieves a binding based on its Name

releaseByIdAsync(id, options, callback)

Removes the binding from the document

Property Details

document

Gets an Office.Document object that represents the document associated with this set of bindings.

document: Document;
Property Value
Document
Remarks

Support details

A capital Y in the following matrix indicates that this property is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this property.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
Word Y Y Y

Method Details

addFromNamedItemAsync(itemName, bindingType, options, callback)

Creates a binding against a named object in the document.

addFromNamedItemAsync(itemName: string, bindingType: BindingType, options?: AddBindingFromNamedItemOptions, callback?: (result: AsyncResult<Binding>) => void): void;
Parameters
itemName
string

Name of the bindable object in the document. For Example 'MyExpenses' table in Excel."

bindingType
BindingType

The Office.BindingType for the data. The method returns null if the selected object cannot be coerced into the specified type.

options
Office.AddBindingFromNamedItemOptions

Provides options for configuring the binding that is created.

callback
(result: AsyncResult<Binding>) => 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 the Binding object that represents the specified named item.

Returns
void
Remarks
Requirement SetsMatrixBindings, TableBindings, TextBindings

For Excel, the itemName parameter can refer to a named range or a table.

By default, adding a table in Excel assigns the name "Table1" for the first table you add, "Table2" for the second table you add, and so on. To assign a meaningful name for a table in the Excel UI, use the Table Name property on the Table Tools | Design tab of the ribbon.

Note: In Excel, when specifying a table as a named item, you must fully qualify the name to include the worksheet name in the name of the table in this format: "Sheet1!Table1"

For Word, the itemName parameter refers to the Title property of a Rich Text content control. (You can't bind to content controls other than the Rich Text content control).

By default, a content control has no Title value assigned. To assign a meaningful name in the Word UI, after inserting a Rich Text content control from the Controls group on the Developer tab of the ribbon, use the Properties command in the Controls group to display the Content Control Properties dialog box. Then set the Title property of the content control to the name you want to reference from your code.

Note: In Word, if there are multiple Rich Text content controls with the same Title property value (name), and you try to bind to one these content controls with this method (by specifying its name as the itemName parameter), the operation will fail.

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
Word Y Y Y

Examples

// The following example adds a binding to the myRange named item in Excel as a "matrix" binding,
// and assigns the binding's id as myMatrix.
function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync(
        "myRange", "matrix", {id:'myMatrix'}, function (result) {
        if (result.status == 'succeeded'){
            write('Added new binding with type: ' + result.value.type + ' and id: ' + result.value.id);
            }
        else
            write('Error: ' + result.error.message);
    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

// The following example adds a binding to the Table1 named item in Excel as a "table" binding,
// and assigns the binding's id as myTable.
function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync(
        "Table1", "table", {id:'myTable'}, function (result) {
        if (result.status == 'succeeded'){
            write('Added new binding with type: ' + result.value.type + ' and id: ' + result.value.id);
            }
        else
            write('Error: ' + result.error.message);
    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

// The following example creates a text binding in Word to a rich text content control named "FirstName",
// assigns the id "firstName", and then displays that information.
function bindContentControl() {
    Office.context.document.bindings.addFromNamedItemAsync('FirstName', 
        Office.BindingType.Text, {id:'firstName'},
        function (result) {
            if (result.status === Office.AsyncResultStatus.Succeeded) {
                write('Control bound. Binding.id: '
                    + result.value.id + ' Binding.type: ' + result.value.type);
            } else {
                write('Error:', result.error.message);
            }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

addFromPromptAsync(bindingType, options, callback)

Create a binding by prompting the user to make a selection on the document.

addFromPromptAsync(bindingType: BindingType, options?: AddBindingFromPromptOptions, callback?: (result: AsyncResult<Binding>) => void): void;
Parameters
bindingType
BindingType

Specifies the type of the binding object to create. Required. Returns null if the selected object cannot be coerced into the specified type.

options
Office.AddBindingFromPromptOptions

Provides options for configuring the prompt and identifying the binding that is created.

callback
(result: AsyncResult<Binding>) => 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 the Binding object that represents the selection specified by the user.

Returns
void
Remarks
Requirement SetsNot in a set

Adds a binding object of the specified type to the Bindings collection, which will be identified with the supplied id. The method fails if the specified selection cannot be bound.

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y

Examples

function addBindingFromPrompt() {
    Office.context.document.bindings.addFromPromptAsync(
        Office.BindingType.Text, 
        { id: 'MyBinding', promptText: 'Select text to bind to.' },
        function (asyncResult) {
            write('Added new binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

addFromSelectionAsync(bindingType, options, callback)

Create a binding based on the user's current selection.

addFromSelectionAsync(bindingType: BindingType, options?: AddBindingFromSelectionOptions, callback?: (result: AsyncResult<Binding>) => void): void;
Parameters
bindingType
BindingType

Specifies the type of the binding object to create. Required. Returns null if the selected object cannot be coerced into the specified type.

options
Office.AddBindingFromSelectionOptions

Provides options for configuring the prompt and identifying the binding that is created.

callback
(result: AsyncResult<Binding>) => 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 the Binding object that represents the selection specified by the user.

Returns
void
Remarks
Requirement SetsMatrixBindings, TableBindings, TextBindings

Adds the specified type of binding object to the Bindings collection, which will be identified with the supplied id.

Note In Excel, if you call the addFromSelectionAsync method passing in the Binding.id of an existing binding, the Binding.type of that binding is used, and its type cannot be changed by specifying a different value for the bindingType parameter. If you need to use an existing id and change the bindingType, call the Bindings.releaseByIdAsync method first to release the binding, and then call the addFromSelectionAsync method to reestablish the binding with a new type.

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
Word Y Y Y

Examples

function addBindingFromSelection() {
    Office.context.document.bindings.addFromSelectionAsync(Office.BindingType.Text, { id: 'MyBinding' }, 
        function (asyncResult) {
        write('Added new binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
        }
    );
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

getAllAsync(options, callback)

Gets all bindings that were previously created.

getAllAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Binding[]>) => void): void;
Parameters
options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<Binding>) => void[]

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 that contains each binding created for the referenced Bindings object.

Returns
void
Remarks
Requirement SetsMatrixBindings, TableBindings, TextBindings

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
Word Y Y Y

Examples

function displayAllBindingNames() {
    Office.context.document.bindings.getAllAsync(function (asyncResult) {
        var bindingString = '';
        for (var i in asyncResult.value) {
            bindingString += asyncResult.value[i].id + '\n';
        }
        write('Existing bindings: ' + bindingString);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

getByIdAsync(id, options, callback)

Retrieves a binding based on its Name

getByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Binding>) => void): void;
Parameters
id
string

Specifies the unique name of the binding object. Required.

options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: AsyncResult<Binding>) => 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 the Binding object specified by the id in the call.

Returns
void
Remarks
Requirement SetsCustomXmlParts, MatrixBindings, TableBindings, TextBindings

Fails if the specified id does not exist.

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
Word Y Y Y

Examples

function displayBindingType() {
    Office.context.document.bindings.getByIdAsync('MyBinding', function (asyncResult) {
        write('Retrieved binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

releaseByIdAsync(id, options, callback)

Removes the binding from the document

releaseByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;
Parameters
id
string

Specifies the unique name to be used to identify the binding object. Required.

options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback
(result: 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 SetsMatrixBindings, TableBindings, TextBindings

Fails if the specified id does not exist.

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
Word Y Y Y

Examples

Office.context.document.bindings.releaseByIdAsync("MyBinding", function (asyncResult) { 
    write("Released MyBinding!"); 
}); 
// Function that writes to a div with id='message' on the page. 
function write(message){ 
    document.getElementById('message').innerText += message;  
}