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.

addFromNamedItemAsync(itemName, bindingType, 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.

addFromPromptAsync(bindingType, 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.

addFromSelectionAsync(bindingType, callback)

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

getAllAsync(options, callback)

Gets all bindings that were previously created.

getAllAsync(callback)

Gets all bindings that were previously created.

getByIdAsync(id, options, callback)

Retrieves a binding based on its Name

getByIdAsync(id, callback)

Retrieves a binding based on its Name

releaseByIdAsync(id, options, callback)

Removes the binding from the document

releaseByIdAsync(id, 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

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 sets:

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.

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; 
}

addFromNamedItemAsync(itemName, bindingType, callback)

Creates a binding against a named object in the document.

addFromNamedItemAsync(itemName: string, bindingType: BindingType, 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.

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

MatrixBindings, 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.

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 set: Not 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.

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; 
}

addFromPromptAsync(bindingType, callback)

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

addFromPromptAsync(bindingType: BindingType, 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.

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 set: Not 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.

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 sets:

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.

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; 
}

addFromSelectionAsync(bindingType, callback)

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

addFromSelectionAsync(bindingType: BindingType, 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.

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 sets:

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.

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 sets:

getAllAsync(callback)

Gets all bindings that were previously created.

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

Parameters

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 sets:

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 sets:

Fails if the specified id does not exist.

getByIdAsync(id, callback)

Retrieves a binding based on its Name

getByIdAsync(id: string, callback?: (result: AsyncResult<Binding>) => void): void;

Parameters

id
string

Specifies the unique name of the binding object. Required.

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 sets:

Fails if the specified id does not exist.

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 sets:

Fails if the specified id does not exist.

releaseByIdAsync(id, callback)

Removes the binding from the document

releaseByIdAsync(id: string, callback?: (result: AsyncResult<void>) => void): void;

Parameters

id
string

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

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 sets:

Fails if the specified id does not exist.

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;  
}