Office.Binding interface

Get the Document object associated with the binding.

document: Office.Document;

Property Value

Examples

Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
    write(asyncResult.value.document.url);
});

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

A string that uniquely identifies this binding among the bindings in the same Office.Document object.

id: string;

Property Value

Examples

Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
    write(asyncResult.value.id);
});

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

Gets the type of the binding.

type: Office.BindingType;

Property Value

Examples

Office.context.document.bindings.getByIdAsync("MyBinding", function (asyncResult) { 
    write(asyncResult.value.type); 
}) 

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

Adds an event handler to the object for the specified Office.EventType. Supported EventTypes are Office.EventType.BindingDataChanged and Office.EventType.BindingSelectionChanged.

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

Requirement set: BindingEvents

You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique.

Adds an event handler to the object for the specified Office.EventType. Supported EventTypes are Office.EventType.BindingDataChanged and Office.EventType.BindingSelectionChanged.

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: Office.AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

Requirement set: BindingEvents

You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique.

Examples

// The following code sample calls the select function of the Office object to access the binding
// with ID "MyBinding", and then calls the addHandlerAsync method to add a handler function 
// for the bindingDataChanged event of that binding.
function addEventHandlerToBinding() {
    Office.select("bindings#MyBinding").addHandlerAsync(
        Office.EventType.BindingDataChanged, onBindingDataChanged);
}

function onBindingDataChanged(eventArgs) {
    write("Data has changed in binding: " + eventArgs.binding.id);
}

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

// To add an event handler for the BindingSelectionChanged event of a binding, 
// use the addHandlerAsync method of the Binding object.
// The event handler receives an argument of type BindingSelectionChangedEventArgs.
function addEventHandlerToBinding() {
    Office.select("bindings#MyBinding").addHandlerAsync(
        Office.EventType.BindingSelectionChanged, onBindingSelectionChanged);
}

function onBindingSelectionChanged(eventArgs) {
    write(eventArgs.binding.id + " has been selected.");
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Returns the data contained within the binding.

getDataAsync<T>(options?: GetBindingDataOptions, callback?: (result: AsyncResult<T>) => void): void;

Parameters

Returns

Remarks

Requirement sets:

• HtmlCoercion (when using Office.CoercionType.Html)

• MatrixBindings

• MatrixCoercion (when using Office.CoercionType.Matrix)

• OoxmlCoercion (when using Office.CoercionType.Ooxml)

• TableBindings

• TableCoercion (when using Office.CoercionType.Table)

• TextBindings

• TextCoercion (when using Office.CoercionType.Text)

When called from a MatrixBinding or TableBinding, the getDataAsync method will return a subset of the bound values if the optional startRow, startColumn, rowCount, and columnCount parameters are specified (and they specify a contiguous and valid range).

Returns the data contained within the binding.

getDataAsync<T>(callback?: (result: AsyncResult<T>) => void): void;

Parameters

Returns

Remarks

Requirement sets:

• HtmlCoercion (when using Office.CoercionType.Html)

• MatrixBindings

• MatrixCoercion (when using Office.CoercionType.Matrix)

• OoxmlCoercion (when using Office.CoercionType.Ooxml)

• TableBindings

• TableCoercion (when using Office.CoercionType.Table)

• TextBindings

• TextCoercion (when using Office.CoercionType.Text)

When called from a MatrixBinding or TableBinding, the getDataAsync method will return a subset of the bound values if the optional startRow, startColumn, rowCount, and columnCount parameters are specified (and they specify a contiguous and valid range).

Examples

function showBindingData() {
    Office.select("bindings#MyBinding").getDataAsync(function (asyncResult) {
        write(asyncResult.value)
    });
}

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

// There is an important difference in behavior between using the "table" and "matrix" coercionType with the
// Binding.getDataAsync method, with respect to data formatted with header rows, as shown in the following
// two examples. These code examples show event handler functions for the Binding.SelectionChanged event.

// If you specify the "table" coercionType, the TableData.rows property ( result.value.rows in the following
// code example) returns an array that contains only the body rows of the table. So, its 0th row will be the
// first non-header row in the table.
function selectionChanged(evtArgs) { 
    Office.select("bindings#TableTranslate").getDataAsync(
        { coercionType: 'table', 
          startRow: evtArgs.startRow, 
          startCol: 0, 
          rowCount: 1, 
          columnCount: 1 },  
        function (result) { 
            if (result.status == 'succeeded') { 
                write("Image to find: " + result.value.rows[0][0]); 
            } 
            else 
                write(result.error.message); 
    }); 
}     
// Function that writes to a div with id='message' on the page. 
function write(message){ 
    document.getElementById('message').innerText += message; 
}

// However, if you specify the "matrix" coercionType, result.value in the following code example returns an array
// that contains the table header in the 0th row. If the table header contains multiple rows, then these are all
// included in the result.value matrix as separate rows before the table body rows are included.
function selectionChanged(evtArgs) { 
    Office.select("bindings#TableTranslate").getDataAsync(
        { coercionType: 'matrix', 
          startRow: evtArgs.startRow, 
          startCol: 0, 
          rowCount: 1, 
          columnCount: 1 },  
        function (result) { 
            if (result.status == 'succeeded') { 
                write("Image to find: " + result.value[1][0]); 
            } 
            else 
                write(result.error.message); 
    }); 
}     
// Function that writes to a div with id='message' on the page. 
function write(message){ 
    document.getElementById('message').innerText += message; 
}

Removes the specified handler from the binding for the specified event type.

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

Requirement set: BindingEvents

Removes the specified handler from the binding for the specified event type.

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

Requirement set: BindingEvents

Examples

function removeEventHandlerFromBinding() {
    Office.select("bindings#MyBinding").removeHandlerAsync(
        Office.EventType.BindingDataChanged, {handler:onBindingDataChanged});
}

Writes data to the bound section of the document represented by the specified binding object.

setDataAsync(data: TableData | any, options?: SetBindingDataOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

Requirement sets:

• HtmlCoercion (when using Office.CoercionType.Html)

• MatrixBindings

• MatrixCoercion (when using Office.CoercionType.Matrix)

• OoxmlCoercion (when using Office.CoercionType.Ooxml)

• TableBindings

• TableCoercion (when using Office.CoercionType.Table)

• TextBindings

• TextCoercion (when using Office.CoercionType.Text)

The value passed for data contains the data to be written in the binding. The kind of value passed determines what will be written as described in the following table.

Additionally, these application-specific actions apply when writing data to a binding. For Word, the specified data is written to the binding as follows.

For Excel, the specified data is written to the binding as follows.

For Excel on the web:

• The total number of cells in the value passed to the data parameter can't exceed 20,000 in a single call to this method.

• The number of formatting groups passed to the cellFormat parameter can't exceed 100. A single formatting group consists of a set of formatting applied to a specified range of cells.

In all other cases, an error is returned.

The setDataAsync method will write data in a subset of a table or matrix binding if the optional startRow and startColumn parameters are specified, and they specify a valid range.

In the callback function passed to the setDataAsync method, you can use the properties of the AsyncResult object to return the following information.

Writes data to the bound section of the document represented by the specified binding object.

setDataAsync(data: TableData | any, callback?: (result: AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

Requirement sets:

• HtmlCoercion (when using Office.CoercionType.Html)

• MatrixBindings

• MatrixCoercion (when using Office.CoercionType.Matrix)

• OoxmlCoercion (when using Office.CoercionType.Ooxml)

• TableBindings

• TableCoercion (when using Office.CoercionType.Table)

• TextBindings

• TextCoercion (when using Office.CoercionType.Text)

The value passed for data contains the data to be written in the binding. The kind of value passed determines what will be written as described in the following table.

Additionally, these application-specific actions apply when writing data to a binding. For Word, the specified data is written to the binding as follows.

For Excel, the specified data is written to the binding as follows.

For Excel on the web:

• The total number of cells in the value passed to the data parameter can't exceed 20,000 in a single call to this method.

• The number of formatting groups passed to the cellFormat parameter can't exceed 100. A single formatting group consists of a set of formatting applied to a specified range of cells.

In all other cases, an error is returned.

The setDataAsync method will write data in a subset of a table or matrix binding if the optional startRow and startColumn parameters are specified, and they specify a valid range.

In the callback function passed to the setDataAsync method, you can use the properties of the AsyncResult object to return the following information.

Examples

function setBindingData() {
    Office.select("bindings#MyBinding").setDataAsync('Hello World!', function (asyncResult) { });
}

// Specifying the optional coercionType parameter lets you specify the kind of data you want to write to a binding.
// For example, in Word if you want to write HTML to a text binding, you can specify the coercionType parameter 
// as "html" as shown in the following example, which uses HTML <b> tags to make "Hello" bold.
function writeHtmlData() {
    Office.select("bindings#myBinding").setDataAsync(
        "<b>Hello</b> World!", {coercionType: "html"}, function (asyncResult) {
        if (asyncResult.status == "failed") {
            write('Error: ' + asyncResult.error.message);
        }
    });
}

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

// In this example, the call to setDataAsync passes the data parameter as an array of arrays
// (to create a single column of three rows), and specifies the data structure with the 
// coercionType parameter as a "matrix".
function writeBoundDataMatrix() {
    Office.select("bindings#myBinding").setDataAsync(
        [['Berlin'],['Munich'],['Duisburg']],{ coercionType: "matrix" }, function (asyncResult) {
        if (asyncResult.status == "failed") {
            write('Error: ' + asyncResult.error.message);
        } else {
            write('Bound data: ' + asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

// In the writeBoundDataTable function in this example, the call to setDataAsync passes the data parameter 
// as a TableData object (to write three columns and three rows), and specifies the data structure
// with the coercionType parameter as a "table".

// In the updateTableData function, the call to setDataAsync again passes the data parameter as a TableData object,
// but as a single column with a new header and three rows, to update the values in the last column 
// of the table created with the writeBoundDataTable function. The optional zero-based startColumn parameter 
// is specified as 2 to replace the values in the third column of the table.
function writeBoundDataTable() {
    // Create a TableData object.
    const myTable = new Office.TableData();
    myTable.headers = ['First Name', 'Last Name', 'Grade'];
    myTable.rows = [['Kim', 'Abercrombie', 'A'], ['Junmin','Hao', 'C'],['Toni','Poe','B']];

    // Set myTable in the binding.
    Office.select("bindings#myBinding").setDataAsync(myTable, { coercionType: "table" }, 
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed) {
                write('Error: '+ asyncResult.error.message);
        } else {
            write('Bound data: ' + asyncResult.value);
        }
    });
}

// Replace last column with different data.
function updateTableData() {
    const newTable = new Office.TableData();
    newTable.headers = ["Gender"];
    newTable.rows = [["M"],["M"],["F"]];
    Office.select("bindings#myBinding").setDataAsync(newTable, { coercionType: "table", startColumn:2 }, 
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed) {
                write('Error: '+ asyncResult.error.message);
        } else {
            write('Bound data: ' + asyncResult.value);
        }     
    });   
}

// In this example, the following call passes two formatting groups to cellFormat.
Office.select("bindings#myBinding").setDataAsync([['Berlin'],['Munich'],['Duisburg']],
  {cellFormat:[{cells: {row: 1}, format: {fontColor: "yellow"}}, 
      {cells: {row: 3, column: 4}, format: {borderColor: "white", fontStyle: "bold"}}]}, 
  function (asyncResult){});