Document.getSelectedDataAsync method (JavaScript API for Office v1.1)

JavaScript API for Office v1.1

Reads the data contained in the current selection of the document.

Last modified: June 12, 2014

Introduced in Office.js version

1.0

Updated in Office.js version

1.1

Available in requirement sets

Selection

Office.context.document.getSelectedDataAsync(coercionType [, options], callback); 

coercionType

Type: CoercionType

The type of data structure to return. Required.

options

Type: object

Specifies the following optional parameters.

valueFormat

Type: ValueFormat

Specifies whether to return the result with its number or date values formatted or unformatted. Optional.

filterType

Type: FilterType

Specifies whether to apply filtering when the data is retrieved. Optional.

Note Note

This parameter is ignored in Word 2013 documents.

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: 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 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 getSelectedDataAsync 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 current selection, which are returned in the data structure or format you specified with the coercionType parameter. (See Remarks for more information about data coercion.)

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.

In your task pane or content app, use the getSelectedDataAsync method to write script that reads the data from the user's selection in a document, spreadsheet, presentation, or project. For example, after a user selects content in a Word document, you can use the getSelectedDataAsync method to read that selection, and then submit it to a web service as a query or some other operation.

After reading the selection, you can also use the setSelectedDataAsync and addHandlerAsync methods of the Document object to write back to the selection or add an event handler to detect if the user changes the selection.

The getSelectDataAsync method can read from the selection only as long as it's active. In apps for Word and Excel, if you need to make a persistent association to read and write to the user's selection, instead use the Bindings.addFromSelectionAsync method to bind to that selection.

Use the coercionType parameter of the getSelectedDataAsync method to specify the data structure or format of the selected data being read.

Specified coercionType

Data returned

Office host application support

Office.CoercionType.Text or "text"

A string.

Word, Excel, PowerPoint, and Project.

Note Note

In Excel, even when a subset of a cell is selected, the entire cell contents are returned.

Office.CoercionType.Matrix or "matrix"

An array of arrays. For example, [['a','b'], ['c','d']] for a selection of two rows in two columns.

Word and Excel.

Office.CoercionType.Table or "table"

A TableData object for reading a table with headers.

Word and Excel.

Office.CoercionType.Html or "html"

In HTML format.

Word only.

Office.CoercionType.Ooxml or "ooxml"

In Open Office XML (OpenXML) format.

Word only.

Tip Tip

When developing your app's code, you can use the "ooxml"coercionType of the getSelectedDataAsync method to see how the content you select in a Word document is defined as OpenXML tags. Then, use those tags in the data parameter of the Document.setSelectedDataAsync method to write content with that formatting or structure to a document. For example, you can insert an image into a document as OpenXML.

Office.CoercionType.SlideRange or "slideRange"

A JSON object that contains an array of the ids, titles, and indexes of the selected slides.

For example, {"slides":[{"id":257,"title":"Slide 2","index":2},{"id":256,"title":"Slide 1","index":1}]} for a selection of two slides.

PowerPoint

If the data structure of the selection doesn't match the specified coercionType, the getSelectedDataAsync method will attempt to coerce the data into that type or structure. If the selection can't be coerced into the Office.CoercionType you specified, the AsyncResult.status property returns "failed".

  • In content apps for PowerPoint, you can get the ids, titles, and indexes of the selected range of slides by passing Office.CoercionType.SlideRange as the coercionType parameter of the getSelectedDataAsync method. See the Document.goToByIdAsync method topic for an example of how to use this value to navigate to the currently selected slide.

To read the value of the current selection, you need to write a callback function that reads the selection. The following example shows how to:

  • Pass an anonymous callback function that reads the value of the current selection to the callback parameter of the getSelectedDataAsync method.

  • Read the selection as text, unformatted, and not filtered.

  • Display the value on the app's page.

function getText() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, 
        { valueFormat: "unformatted", filterType: "all" },
        function (asyncResult) {
            var error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                write(error.name + ": " + error.message);
            } 
            else {
                // Get selected data.
                var dataValue = asyncResult.value; 
                write('Selected data is ' + dataValue);
            }            
        });
}

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

App types

Content apps, Task pane apps

Supported clients

Excel 2013, Excel 2013 SP1, Excel 2013 RT, Excel Online, Word 2013, Word 2013 SP1, Word 2013 RT, PowerPoint 2013, PowerPoint 2013 SP1, PowerPoint 2013 RT, Project 2013 SP1, and Project 2013

Library

Office.js

Namespace

Office

Show:
© 2014 Microsoft