Export (0) Print
Expand All

Binding.getDataAsync method (JavaScript API for Office v1.1)

JavaScript API for Office v1.1

Returns the data contained within the binding.

Last modified: June 12, 2014

Available in requirement sets

MatrixBindings, TableBindings, TextBindings

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

options

Type: object

Specifies the following optional parameters.

coercionType

Type: CoercionType

Specifies how to coerce the returned data. Optional.

valueFormat

Type: ValueFormat

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

filterType

Type: FilterType

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

rows

Type: Office.TableRange.ThisRow

Only for table bindings in content apps for Access, specifies the pre-defined string "thisRow" to get data in the currently selected row. Optional.

startRow

Type: number

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

startColumn

Type: number

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

rowCount

Type: number

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

columnCount

Type: number

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

asyncContext

Type: 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. Optional.

callback

Type: object

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

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.

colCount

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 colCount parameters are specified (and they specify a contiguous and valid range).

In version 1.1 of Office.js, you can create table bindings in content apps for Access.

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, colCount: 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, colCount: 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;

App types

Content app, Task pane app

Supported clients

Access app for SharePoint, Excel 2013, Excel 2013 SP1, Excel 2013 RT, Excel Online, Word 2013, Word 2013 SP1, Word 2013 RT

Library

Office.js

Namespace

Office

Show:
© 2014 Microsoft