Share via


Ewa.EwaControl.loadEwaAsync(fileID, divID, embedOptions, callback, userContext)

Applies to: apps for SharePoint | Excel Services | SharePoint Server 2013

In this article
Return Value
Remarks
Example

Embeds a Microsoft Excel workbook in a <div> element on a host web page.

var value = Ewa.EwaControl.loadEwaAsync(fileID, divID, embedOptions, callback, userContext);

Parameters

fileID

A required string that specifies the location of the workbook to embed.

Note

The Microsoft Excel OnlineEmbed dialog box provides the only reliable way to get the file token for the file stored on Microsoft OneDrive.

For more information about the Excel OnlineEmbed dialog box, see Make a mashup: extend Excel to your web app.

divID

A required string that specifies the id of the <div> element in the page that displays the embedded workbook.

embedOptions

An optional object that contains three child objects that specify a named object, a set of appearance options, and a set of interactivity options for the embedded workbook. If this object is not passed into the call to loadEwaAsync, then the workbook is loaded with the default appearance and interactivity options.

As mentioned, the object that you create can include two child objects that you use to modify the appearance and interactivity for the embedded workbook. You set appearance options for the embedded workbook using the properties of one child object. You set interactivity options for the embedded workbook using the other child object. To learn how to create and use an object with two child objects that set appearance and interactivity options for an embedded workbook, see the code example later in this topic. The specific properties that you use to set appearance options and to set interactivity options are listed in the following tables.

The following table shows properties that represent appearance options for the embedded workbook.

Note

By default, each property that holds a boolean value is set to true

Table 1. Properties for Specifying Appearance Options on the Embedded Workbook

Name

Description

showDownloadButton

If true, displays a download link for the workbook.

selectedCell

Selects the specified cell.

Note

If set to an invalid cell value, this setting is ignored.

Note

There is no default value for this setting.

showParametersTaskPane

If true, displays the Parameters Task Pane.

Important

Setting this property to true will not enable the display of the Parameters Task Pane if there are no parameters that are published in the workbook.

showRowColumnHeaders

If true, displays row and column headers.

Important

Setting this property to true will not enable the display of row and column headers in the embedded workbook if the underlying workbook has hidden the display of row and column headers.

showGridlines

If true, displays gridlines.

Important

Setting this property to true will not enable the display of gridlines in the embedded workbook if the underlying workbook has hidden the display of gridlines.

The following table shows properties that represent interactivity options for the embedded workbook. By default, each property that holds a boolean value is set to true. Setting a property to false also hides the user interface for that option.

Table 2. Properties for Specifying Interactivity Options on the Embedded Workbook

Name

Description

allowTypingAndFormulaEntry

If true, enables formula and typing entry.

allowParameterModification

If true, enables modification of parameters.

allowSorting

If true, enables sorting.

allowFiltering

If true, enables filtering.

allowPivotTableInteractivity

If true, enables all interactivity for pivot tables.

allowHyperlinkNavigation

If true, enables hyperlink navigation.

callback

Specifies the function that is called when the asynchronous operation is complete.

userContext

An object provided as a way for callers to pass state through the asynchronous call.

Return Value

None.

Remarks

The loadEwaAsync method lets you embed a Excel workbook that is stored on OneDrive into a host web page.

To display and programmatically work with the workbook on an external web page, you must create and insert embed code into the HTML of the host web page. Although you can write your own code to embed a workbook, the easiest way to write the embed code is to use the OneDriveEmbed dialog box. The Embed dialog box enables you to set embedding options on a workbook and automatically generate the HTML and ECMAScript (JavaScript, JScript) code to embed the workbook with options that specify the display and interactivity for the workbook. The ECMAScript (JavaScript, JScript) code that is generated by the Embed dialog uses the loadEwaAsync method.

Figure 1. Embed dialog box

Embed dialog box

Additionally, the Embed dialog box provides the only reliable way to get the file token for the file that is stored on OneDrive.

Note

For more information about how to use the Embed dialog box to generate embed code automatically, see Make a mashup: extend Excel to your web app

Example

The following code example shows how to use the loadEwaAsync method to embed a workbook named Book1.xlsx in a host web page. This code example was generated using the OneDriveEmbed dialog box.

<div id="myExcelDiv" style="width: 402px; height: 346px"></div>
<script type="text/javascript" src="http://r.office.microsoft.com/r/rlidExcelWLJS?v=1&kip=1"></script>
<script type="text/javascript">

// Use this file token to reference Book1.xlsx in the Excel APIs.
var fileToken = "SD206C5E037684EDE5!1119/2336345675664780773/";

// Run the Excel load handler on page load.
if (window.attachEvent) {
window.attachEvent("onload", loadEwaOnPageLoad);
} else {
window.addEventListener("DOMContentLoaded", loadEwaOnPageLoad, false);
}

function loadEwaOnPageLoad() {                               
var props = {
                  item: "LunchSales",
uiOptions: {
showGridlines: false,
showRowColumnHeaders: false,
showParametersTaskPane: false
},
interactivityOptions: {
allowTypingAndFormulaEntry: false,
allowParameterModification: false,
allowSorting: false,
allowFiltering: false,
allowPivotTableInteractivity: false
}
};

Ewa.EwaControl. loadEwaAsync(fileToken, "myExcelDiv", props, onEwaLoaded);
}

function onEwaLoaded(result) {

        if (asyncResult.getSucceeded())
        {
            // Use the AsyncResult.getEwaControl() method to get a reference to the EwaControl object
            ewa = asyncResult.getEwaControl();
            ewa.add_activeCellChanged(cellChanged);
        }
        else
        {
            alert("Async operation failed!");
        }
}
</script>

See also

Reference

Ewa.EwaControl Object

Other resources

Using the Excel Services JavaScript API to Work with Embedded Excel Workbooks