Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Office.select method (JavaScript API for Office)

Office Add-ins

Creates a promise to return a binding based on the selector string passed in.

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, PartialTableBindings, TableBindings, TextBindings

Last changed in

1.1

See all support details

Office.select(str, onError);

str

Type: string

The selector string to parse and create a promise for.

onError

Type: function

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

When the function you passed to the onError parameter executes, it receives an AsyncResult object that you can access from the callback function's only parameter. If the operation failed, use the AsyncResult.error property to access an Error object that provides information about the error.

The Office.select method provides access to a Binding object promise that attempts to return the specified binding when any of its asynchronous methods are invoked.

Supported formats: "bindings#bindingId", which returns a Binding object for the binding with the id of bindingId. For more information, see https://msdn.microsoft.com/en-us/library/jj220067#AsyncProgramming_PromisesPattern and Bind to regions in a document or spreadsheet.

Note Note

If the select method promise successfully returns a Binding object, that object exposes only the following four methods of the Binding object: getDataAsync, setDataAsync, addHandlerAsync, and removeHandlerAsync. If the promise cannot return a Binding object, the onError callback can be used to access an asyncResult.error object to get more information.

If you need to call a member of the Binding object other than the four methods exposed by the Binding object promise returned by the select method, instead use the getByIdAsync method by using the Document.bindings property and Bindings.getByIdAsync method to retrieve the Binding object.

The following code example uses the select method to retrieve a binding with the id "cities" from the Bindings collection, and then calls the addHandlerAsync method to add an event handler for the dataChanged event of the binding.

function addBindingDataChangedEventHandler() {
    Office.select("bindings#cities", function onError(){}).addHandlerAsync(Office.EventType.BindingDataChanged,
    function (eventArgs) {
        doSomethingWithBinding(eventArgs.binding);
    });
}

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.

Office for Windows desktop

Office Online
(in browser)

Office for iPad

Access

Excel

Word

Available in requirement sets

MatrixBindings, PartialTableBindings, TableBindings, TextBindings

Minimum permission level

ReadDocument (ReadAllDocument for Open Office XML)

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 the use of the select method to return table bindings created in content apps for Access.

1.0

Introduced

Show:
© 2015 Microsoft