Binding.getDataAsync method (JavaScript API for Office)

apps for Office

Returns the data contained within the binding.

Last modified: June 22, 2015

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.

Hosts:

Access, Excel, Word

Available in Requirement sets

MatrixBindings, TableBindings, TextBindings

Last changed in TableBindings

1.1

See all support details

bindingObj.getDataAsync([, options] , callback );

Name

Type

Description

Support notes

options

object

Specifies any of the following optional parameters

coercionType

CoercionType

Specifies how to coerce the data being set.

valueFormat

ValueFormat

Specifies whether values, such as numbers and dates, are returned with their formatting applied.

filterType

FilterType

Specifies if a filter must be applied when the data is retrieved.

rows

Office.TableRange.ThisRow

Specifies the pre-defined string "thisRow" to get data in the currently selected row.

Only for table bindings in content apps for Access.

startRow

number

For table or matrix bindings, specifies the zero-based starting row for a subset of the data in the binding.

startColumn

number

For table or matrix bindings, specifies the zero-based starting column for a subset of the data in the binding.

rowCount

number

For table or matrix bindings, specifies the number of rows offset from the startRow.

columnCount

number

For table or matrix bindings, specifies the number of columns offset from the startColumn.

asyncContext

array, boolean, null, number, object, string, or undefined

A user-defined item of any type that is returned in the AsyncResult object without being altered.

callback

object

A function that is invoked when the callback returns, whose only parameter is of type AsyncResult.

When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

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

Property

Use to...

AsyncResult.value

Access the values in the specified binding.

If the coercionType parameter is specified (and the call is successful), the data is returned in the format described in the CoercionType enumeration topic.

AsyncResult.status

Determine the success or failure of the operation.

AsyncResult.error

Access an Error object that provides error information if the operation failed.

AsyncResult.asyncContext

Access your user-defined object or value, if you passed one as the asyncContext parameter.

If an optional parameter is omitted, the following default value is used (when applicable to type and format of the data).

Parameter

Default

coercionType

The original, uncoerced type of the binding.

valueFormat

Unformatted data.

filterType

All values (not filtered).

startRow

The first row.

startColumn

The first column.

rowCount

All rows.

columnCount

All columns.

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).

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;

A checkmark (√) 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 apps for Office.

Supported hosts, by platform

Office for Windows desktop

Office Online
(in browser)

Office for iPad

Access

Excel

Word

Available in requirement sets

MatrixBindings, TableBindings, TextBindings

Minimum permission level

ReadDocument

App types

Content, task pane

Library

Office.js

Namespace

Office

Version

Changes

1.1

Added support for Excel and Word in Office for iPad.

1.1

Added support for table bindings in apps for Access.

1.0

Introduced

Show:
© 2015 Microsoft