Ewa.NamedItem.getRefersToRangeAsync(callback, userContext)

Last modified: June 13, 2011

Applies to: apps for SharePoint | SharePoint Server 2010

In this article
Return Value
Applies To

Gets the range coordinates of the named item.

var value = Ewa.NamedItem.getRefersToRangeAsync(callback, userContext);


The function that is called when the request is completed.


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

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

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.

<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", ewaOmPageLoad);    
    window.addEventListener("DOMContentLoaded", ewaOmPageLoad, false); 

// Add event handler for applicationReady event.
function ewaOmPageLoad() 

function getEwa()
    // 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.");
            // 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.
        // If at the end of the named items collection, start over.
        if (itemCount == items.getCount())
            itemCount = 0;
        // 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;

<input type="button" id="GetCoordinates" value="Get Range Coordinates" onclick="getRangeCoordinatesButton()" /> 
<div id="debugDiv"></div>