Document.setSelectedDataAsync method (apps for Office)

data

Type: String, Array (array of arrays – "matrix"), TableData, HTML (Word only), or Office Open XML (Word only)

The data to be set in the current selection. Required.

options

Type: object

Specifies the following optional parameters.

coercionType Type: CoercionType Specifies how to coerce the data being set. 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. For the setSelectedDataAsync method, the AsyncResult.value property always returns undefined. To determine the success or failure of the operation, use the AsyncResult.status property. If the operation failed, use the AsyncResult.error property to access an Error object that provides information about the error. If you passed a user-defined object to the asyncContext parameter, use the AsyncResult.asyncContext property to access that object.

The value passed for data contains the data to write to the current selection. If the value is:

• A string: Plain text or anything that can be coerced to a string will be inserted.

• An array of arrays ("matrix"): Tabular data without headers will be inserted. For example, to write data to three rows in two columns, you can pass an array like this: [["R1C1", "R1C2"], ["R2C1", "R2C2"], ["R3C1", "R3C2"]]. To write a single column of three rows, pass an array like this: [["R1C1"], ["R2C1"], ["R3C1"]]

• A TableData object: A table with headers will be inserted.

Additionally, the following application-specific actions apply when writing data to a selection.

For Word

• If there is no selection and the insertion point is at a valid location, the specified data is inserted at the insertion point as follows:

  • If data is a string, the specified text is inserted.

  • If data is an array of arrays ("matrix") or a TableData object, a new Word table is inserted.

  • If data is HTML, the specified HTML is inserted.

    Important
    If any of the HTML you insert is invalid, Word will not raise an error. Word will insert as much of the HTML as it can and will omit any invalid data.

  • If data is Office Open XML, the specified the XML is inserted.

• If there is a selection, it will be replaced with the specified data following the same rules as above.

For Excel

• If a single cell is selected:

  • If data is a string, the specified text is inserted as the value of the current cell.

  • If data is an array of arrays ("matrix"), the specified set of rows and columns are inserted, if no other data in surrounding cells will be overwritten.

  • If data is a TableData object, a new Excel table with the specified set of rows and headers is inserted, if no other data in surrounding cells will be overwritten.

• If multiple cells are selected and the shape does not match the shape of data, an error is returned.

• If multiple cells are selected and the shape of the selection exactly matches the shape of data, the values of the selected cells are updated based on the values in data.

In all other cases, an error is returned.

The following example sets the selected text or cell to "Hello World!", and if that fails, displays the value of the error.message property.

function writeText() {
    Office.context.document.setSelectedDataAsync("Hello World!",
        function (asyncResult) {
            var error = asyncResult.error;
            if (asyncResult.status === "failed"){
            write(error.name + ": " + error.message);
            }
        });
}

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

Specifying the optional coercionType parameter lets you specify the kind of data you want to write to a selection. The following example writes data as an array of three rows of two columns, specifying the coercionType as "matrix" for that data structure, and if that fails, displays the value of the error.message property.

function writeMatrix() {
    Office.context.document.setSelectedDataAsync([["Red", "Rojo"], ["Green", "Verde"], ["Blue", "Azul"]], {coercionType: "matrix"}
        function (asyncResult) {
            var error = asyncResult.error;
            if (asyncResult.status === "failed"){
            write(error.name + ": " + error.message);
            }
        });
}

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

The following example writes data as a one column table with a header and four rows, specifying the coercionType as "table" for that data structure, and if that fails, displays the value of the error.message property.

function writeTable() {
    // Build table.
    var myTable = new Office.TableData();
    myTable.headers = [["Cities"]];
    myTable.rows = [['Berlin'], ['Roma'], ['Tokyo'], ['Seattle']];

    // Write table.
    Office.context.document.setSelectedDataAsync(myTable, {coercionType: "table"},
        function (result) {
            var error = result.error
            if (result.status === "failed") {
                write(error.name + ": " + error.message);
            }
    });
}

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

In Word if you want to write HTML to the selection, you can specify the coercionType parameter as "html" as shown in the following example, which uses HTML <b> tags to make "Hello" bold.

function writeHtmlData() {
    Office.document.setSelectedDataAsync("<b>Hello</b> World!", {coercionType: "html"}, function (asyncResult) {
        if (asyncResult.status == "failed") {
            write('Error: ' + asyncResult.error.message);
        }
    });
}

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