Document.getSelectedDataAsync method (apps for Office)

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 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 Document.getSelectedDataAsync method, you can use the properties of the AsyncResult object to return the following information.

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

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

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; 
}