Ewa.NamedItem.getRefersToRangeAsync(callback, userContext)
Applies to: apps for SharePoint | Excel Services | SharePoint Server 2013
In this article
Return Value
Remarks
Example
Applies To
Gets the range coordinates of the named item.
var value = Ewa.NamedItem.getRefersToRangeAsync(callback, userContext);
Parameters
callback
The function that is called when the request is completed.
userContext
An object provided as a way for callers to pass state through the asynchronous call.
Return Value
None.
Remarks
The callback method specified in Ewa.NamedItem.getRefersToRangeAsync returns the range coordinates of the specified named item through the AsyncResult argument that was passed in to the call to the callback method. Use the AsyncResult.getReturnValue method to retrieve the coordinates.
Range coordinates are returned if the named item type is a named range, parameter, tables, or PivotTables; otherwise, the method returns null (for example, if the named item type is Chart).
Example
The following code example shows how to add a button to the page and then adds an event handler for the onClick event of the button that loops through each named item in the workbook and prints the name and range coordinates for the named item to the page. The code example assumes that you are working with Excel Web Access Web Parts on SharePoint Server 2013.
<script type="text/javascript">
var ewa = null;
// Create counter for looping through named items.
var itemCount = 0;
// Add event handler for onload event.
if (window.attachEvent)
{
window.attachEvent("onload", ewaOnPageLoad);
}
else
{
window.addEventListener("DOMContentLoaded", ewaOnPageLoad, false);
}
// Add event handler for applicationReady event.
function ewaOnPageLoad()
{
Ewa.EwaControl.add_applicationReady(onApplicationReady);
}
function onApplicationReady()
{
// Get a reference to the Excel Services Web Part.
ewa = Ewa.EwaControl.getInstances().getItem(0);
}
// Use the button onClick event handler.
function getRangeCoordinatesButton()
{
// Get the NamedItems collection.
var items = ewa.getActiveWorkbook().getNamedItems();
// Get the next named item in the collection.
var item = items.getItem(itemCount);
if (item != null)
{
var type = item.getNamedItemType();
// getRefersToRangeAsync() will not work on a chart named item.
if (type == Ewa.NamedItemType.Chart || type == "undefined")
{
alert("Cannot get range coordinates from this type of named item.");
}
else
{
// Call getRefersToRangeAsync(), passing in callback and the
// current named item.
item.getRefersToRangeAsync(getRangeCoordinatesCallback, item);
}
// Advance to the next named item in the named items collection.
itemCount++;
// If at the end of the named items collection, start over.
if (itemCount == items.getCount())
{
itemCount = 0;
}
}
else
{
// No named item present.
alert("No named items here.");
}
}
function getRangeCoordinatesCallback(asyncResult)
{
// Get the range object returned from getRefersToRangeAsync().
var rng = asyncResult.getReturnValue();
// Get named item from userContext (the named item passed in to getRefersToRangeAsync()).
var item = asyncResult.getUserContext();
// Create output message to show in div.
var output = "Named item " + item.getName() + " is at range coordinates " + rng.getAddressA1() + ".";
output = output + "<br/>";
// Write name of activated named item to div in page.
document.getElementById('debugDiv').innerHTML = output + document.getElementById('debugDiv').innerHTML;
}
</script>
<input type="button" id="GetCoordinates" value="Get Range Coordinates" onclick="getRangeCoordinatesButton()" />
<div id="debugDiv"></div>