Excel User Guide

7/30/2019 Excel User Guide

1/18

Hands-On Lab

Using the Excel Services ECMAScript ObjectModel

Lab version: 1.0.0

Last updated: 11/30/2012


2/18

CONTENTS

OVERVIEW ................................................................................................................................................... 3

EXERCISE 1: EXPERIMENTING WITH THE ECMASCRIPT OBJECT MODEL ........................................ 4

Task 1 Setting up SharePoint Web Part Page ..................................................................................... 4

Task 2 Modifying FabriKamReporting.js ............................................................................................ 7

Exercise 1 Verification ........................................................................................................................... 9

EXERCISE 2: DEPLOYING AND DEBUGGING AN EXCEL SERVICES ECMASCRIPT ........................ 10

Task 1 Using Internet Explorer 8 for Debugging .............................................................................. 10

Task 2Using a Logging Mechanism for Debugging ....................................................................... 11

EXERCISE 3: ADDING NAVIGATION CAPABILITIES TO A WORKBOOK USING ECMASCRIPT ...... 13

Task 1 Examining Navigation with Macros within Microsoft Excel and Excel Web Access ............. 13

Task 2 Adding Funtionality to the Buttons Using the Excel Services JSOM ..................................... 14

Exercise 3 Verification ......................................................................................................................... 17

SUMMARY .................................................................................................................................................. 17


3/18

OverviewIn this Hands-On Lab you will learn how to use the Excel Services ECMAScript Object Model to automate

and interact with an Excel Web Access web part.

Objectives

The objective of this Hands-On Lab is to provide you with a foundation for using the ECMAScript Object

Model to automate and interact with an Excel Web Access (EWA) web part programmatically. In

particular, you will

Experiment with the Excel Services ECMAScript object model

Develop debugging skills to diagnose and resolve development issues

Learn how to deploy your scripts and setup web part pages that consume the scripts

System Requirements

The steps in this Hands-On Lab require the following:

SharePoint 2010

Excel 2010

Visual Studio 2010

This exercise assumes the use of the 2010 Information Worker Demonstration and

Evaluation Virtual Machine (RTM),

http://www.microsoft.com/downloads/en/details.aspx?FamilyID=751fa0d1-356c-4002-

9c60-d539896c66ce&displaylang=en. If you are working with your own SharePoint server

then make the necessary adjustments.

Setup

This Hands-On Lab assumes that the Hands-On Lab files are located in a folder at%Office2010DeveloperTrainingKitPath%\Labs\ExcelJSOM

Exercises

This Hands-On Lab comprises the following exercises:

1. Experimenting with the ECMASript object model
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=751fa0d1-356c-4002-9c60-d539896c66ce&displaylang=enhttp://www.microsoft.com/downloads/en/details.aspx?FamilyID=751fa0d1-356c-4002-9c60-d539896c66ce&displaylang=enhttp://www.microsoft.com/downloads/en/details.aspx?FamilyID=751fa0d1-356c-4002-9c60-d539896c66ce&displaylang=enhttp://www.microsoft.com/downloads/en/details.aspx?FamilyID=751fa0d1-356c-4002-9c60-d539896c66ce&displaylang=enhttp://www.microsoft.com/downloads/en/details.aspx?FamilyID=751fa0d1-356c-4002-9c60-d539896c66ce&displaylang=en


4/18

2. Deploying and debugging an Excel Services ECMAScript

3. Adding Navigation capabilities to a workbook using the Excel Services ECMAScript object

model

Estimated time to complete this lab: 60 minutes.

Starting Materials

This Hands-On Lab includes the following starting materials.

Fabrikam_Reporting.xlsm This is used as an example in exercise 3.

FabriKamReporting.txt This is used as an example in exercise 3.

Exercise 1: Experimenting with the

ECMAScript object modelIn this exercise you will be taking a look at how you can expand the functionality of your Excel

documents stored on a SharePoint site through the use of an Excel Web Access web part and the Excel

Services ECMAScript object model (aka Excel Services JSOM).

Task 1 Setting up SharePoint Web Part Page

In this task you will set up a SharePoint web part page to incorporate the Excel document and your

ECMA script.

1. Open a new workbook in Microsoft Excel

2. Save a blank Excel document to

%Office2010DeveloperTrainingKitPath%\Labs\ExcelJSOM\Starter and name the document

EwaTest.xlsx.

3. Open the SharePoint site at http://intranet.contoso.com/

4. Go to Libraries Shared Documents

5. Click Add document, navigate to

%Office2010DeveloperTrainingKitPath%\Labs\ExcelJSOM\Starter and upload the

FabriKamReporting.jsand EwaTest.xlsx documents to the Shared Documents folder on the

SharePoint site.

6. Click the Site Actions dropdown and select More Options.


5/18

a. Filter by Page, select Web PartPage and click Create.

b. Title the page EWATest and for the Layout Template, select Header, Left Column,

Body.

c. Click the Document Library drop down and select Site Pages.

d. Click Create.

Figure 1

Creating a new Web Part Page


6/18

Figure 2

New Web Part Page

7. Select Add a Web Partin the Body section of the page.

a. View the Categories section and select Business Data. View the Web Parts section,

select Excel Web Access, and then click Add.

i. Select the newly added Excel Web Access web part and click the Options tab at

the top of the page.

ii. Select Web Part Properties and an options box should appear on the side of the

screen.

iii. View the Workbook Display section, under Workbook navigate to the shared

documents section and select EwaTest.xlsm document that you loaded in step 1.

iv. View the Toolbar and Title Bar section, under Type of Toolbar, select None.

v. Expand the Navigation and Interactivity section; check the box next to Typing

and Formula Entry.

vi. Expand the Appearance section, set the Height to 600 and change the ChromeType to None and then click OK to save the changes.

vii. Uncheck web part selection box (upper right hand corner) in Body section

8. Select Add a Web Part in the Left Column.

a. View the Categories section and select Media and Content. View Web Parts and

select Content Editor and then click Add.


7/18

i. In the Left Column, select the drop down next to Content Editor, and select Edit

Web Part.

ii. Open new tab in web browser and navigate to the SharePoint Home page and

then to the Shared Documents section.

iii. Find the document titled FabriKamReporting.js , loaded in step 5, right click andselect Copy Shortcut.

iv. From the Content Editor section, paste the link to the FabriKamReporting.js.

v. From the Appearance section, set the width to 300 Pixels, click Yes and click OK

to save the changes.

9. From the Page tab at the top, click Stop Editing to complete the web page part setup.

Figure 3

EwaTest spreadsheet

Note: At this point, you have performed the bare minimum required to associate an Excel

Service JSOM script with an Excel Web Access web part.

Task 2 Modifying FabriKamReporting.jsThis task involves modifying the FabriKamReporting.js file to experiment with the events that you can

tap into so that your script can interact with an Excel Web Access web part.

1. Open up FabriKamReporting.js in Visual Studio.

a. Add the following code between the two script tags. In this code, we are doing a

couple key things. First off, we are adding an event handler that will call Page_Load()


8/18

once the web page has been loaded. Secondly, we are adding a function to handle

the output logging to the Content Editor web part, writelog().

var logItems = true;

if (window.attachEvent) {

window.attachEvent("onload", Page_Load);

}

else {

window.addEventListener("DOMContentLoaded", Page_Load, false);

}

function Page_Load() {

}

function writelog(output) {

if(logItems) {

output = output + "
";

document.getElementById('resultdiv').innerHTML = output +

document.getElementById('resultdiv').innerHTML;

}

}

b. Next, add the following line of code to Page_Load(). This will add the callback

function that Excel Services calls once the Excel document has loaded.

Ewa.EwaControl.add_applicationReady(GetEwa);

c. Below the Page_Load() function, add the following function. This is the callback

function (set in Page_Load()) that will get a reference an Excel Web Access control

instance and add an event handler for the document.

function GetEwa() {

om = Ewa.EwaControl.getInstances().getItem(0);

om.add_activeSelectionChanged(onSelectionChange);

}

d. Add the following event handler after function GetEwa(). The purpose of this event

handler is to capture selection changes within the document.

function onSelectionChange(rangeArgs) {

writelog('onSelectionChange Address:' +

rangeArgs.getRange().getAddressA1());

}


9/18

2. Save your changes and upload FabriKamReporting.js to the SharePoint site. See Task 1 Step

5 if you forgot where you uploaded the documents before. Make sure to overwrite the

original.

3. Navigate back to Site Pages and load EwaTest.aspx (or refresh the page if you already have it

displayed in your browser).

Exercise 1 Verification

To verify that your script and the Excel Web Access part are working together, perform the following

steps

1. Click on cell B2 in Sheet1

2. Look in the Content Editor section and you should see the following output:

onSelectionChange Address:Sheet1!B2

3.

Click on additional cells and you should see the equivalent results based on the sheet and

cell selected.

Figure 4

Verifying results


10/18

Exercise 2: Deploying and debugging an

Excel Services ECMAScriptIn this exercise we will be going over a couple different options to effectively debug your ECMAScript at

runtime. This will help you diagnose issues at the source.

Task 1 Using Internet Explorer 8 for Debugging

In this task we will be taking a look at the IE 8 developer tools that can come in handy when debugging

ECMAScript on the fly.

1. Press F12 to open up the Developer Tools window in IE.

2. Click on the Script tab and use search script search bar to locate the ECMAScript we loaded

in Exercise 1 (FabriKamReporting.js ). Input writelog into search bar and execute.

3. Find the following line of code within onSelectionChange() and set a breakpoint by clicking

on the line number.

writelog('onSelectionChange Address:' +

rangeArgs.getRange().getAddressA1());

4. Click on the Breakpoints tab below the Search Script search bar and you should see the

breakpoint that you just set.

5. Once you have your breakpoint set, click the Start Debugging button at the top. Click OK if

prompted to Refresh Webpage.

6. Go back to the IE window and click on cell B2 in Sheet1 to trigger the event and hit the

breakpoint.

7. Go back to the Developer Tools window and click the Locals tab below the Search Script

search bar.


11/18

Figure 5

Locals tab

a. Expand rangeArgs

b. Expand $1x_0

c. Verify the value next to $RF_0 is Sheet1!B2 (the cell you clicked on in step 5).

8. Press the Continue button (little green button to the left of the Stop Debugging button) or

F5 to resume execution.

9. Go back to the Developer Tools Window and stop debugging by clicking Stop Debugging at

the top or close the DeveloperTools window.

Task 2Using a Logging Mechanism for Debugging

In this task you will take a look at another method you can use to debug our ECMAScript. This method

involves creating functionality within the script itself to relay information about program flow. If you

noticed before in FabriKamReporting.js we had a function called writelog() that output information to a

Content Editor web part to as events occurred. We can use this function in the same manner across the

script to verify the functionality.

1. Go back to Visual Studio and add the following lines of code to FabriKamReporting.js:

a. At the beginning of function Page_Load() :

writelog("Page_Load called");

writelog("Ewa object: " + Ewa);


12/18

b. At the beginning of function GetEwa():

writelog("GetEwa called");

2. Save changes to FabriKamReporting.js

3. Upload FabriKamReporting.js (making sure to overwrite the original).

4. Load the web part page EwaTest.aspx we created in Exercise 1

5. Look at the Content Editor section and verify the following result:

a. GetEwa called - This shows you that the funtion GetEwa() was called.

b. Ewa object: [object Object] - This is verifying that the Ewa object is valid. If the

object was invalid, the result would be undefined, null, or nothing would bereturned.

c. Page_Load called - This shows you that the function Page_Load() was called.

Figure 6

Content Editor


13/18

Exercise 3: Adding Navigation

capabilities to a workbook using

ECMAScriptIn this exercise you will be taking a look at how you can recreate navigation implemented with VBA

within a Microsoft Excel workbook using the Excel Services JSOM with an Excel Web Access web part.

Task 1 Examining Navigation with Macros within Microsoft Excel and Excel Web Access

In this task you will be taking a look how the navigation is handled within Microsoft Excel and what

functionality cannot be ported directly over to Excel Web Access without the use of ECMAScript.

1. In Excel open up Fabrikam_Reporting.xlsm in rExcelJSOM\Started.

a. Click on Balance Sheets

b. Click on Return to get back to the Menu sheet.

c. Click View Data

d. Click on Return to get back to the Menu sheet.

Note: Notice how you managed to navigate throughout the document with these

embedded buttons. In the background there are macros that handle this functionality.

Since VBA does not run in Excel Services, when you open the document on the server,

the navigation functionality will not work.Navigation is a common task in complex workbooks that consist of numerous

worksheets. By providing basic navigation, you can make complex workbooks easier to

use and understand to casual users of the workbook.

2. Click on the File tab

3. Click on Save & Send

4. Click Save to SharePoint and double-click Browse for a location

5. Click in the File name box and enter in

http://intranet.contoso.com/Shared%20Documents/Fabrikam_Reporting.xlsm

6. Click Save (Note: if there are any issues saving the document from the client to SharePoint,

then close the client and upload the document from the Shared Docuements library in

SharePoint.)

7. If a new SharePoint window opens with the new Fabrikam document, close the web page.


14/18

8. Create a new web part page identical to that in exercise 1, task 1. Make sure to set the Excel

Web Access web part to Fabrikam_Reporting.xlsm instead ofEwaTest.xlsx (exercise 1 task

1) and name the page FabrikamReporting .

9. Click on the nagivation links that you were using in Excel (steps 1.a-d)

Note: As youve noticed, the navigation no longer works once the document has been loaded

on the SharePoint site. The macros that were once handling navigation, are no longer

functional. You can easily reimplement this functionality using the Excel Services JSOM.

Task 2 Adding Funtionality to the Buttons Using the Excel Services JSOM

In this task you will be restoring navigation to the Fabrikam_Reporting.xlsm workbook displayed on the

server using an Excel Web Access web part.

1. Open up FabriKamReporting.js in Visual Studio.

a. Add the following line of code after var logItems = true;

var currentSheetName = "";

b. Begin by adding the next piece of code to the end of function GetEwa(). You are now

adding another event handler and retrieving the value at the named range

LOG_JSOM in the Inputs sheet.

om.add_workbookChanged(onWorkbookChange);

om.getActiveWorkbook().getRangeA1Async('\'Inputs\'!LOG_JSOM',

getInputsComplete);

c. Add the following callback function getRangeComplete() after the end of function

GetEwa(). This will handle changing the cell focus for navigation changes.

function getRangeComplete(asyncResult) {

var range = asyncResult.getReturnValue();writelog('getRangeComplete');

range.activateAsync();

}


15/18

d. Add the next callback function showLogging()after the end of getRangeComplete().

This will handle toggling the logging on and off that appears in the Content Editor

web part.

function showLogging(asyncResult) {writelog('showLogging',1);

var value = asyncResult.getReturnValue();

if(value == 'no') {

writelog('showLogging: Show Logging FALSE');

logItems = false;

} else {

logItems = true;

writelog('showLogging: Show Logging TRUE');

}

}

e. Add the next callback function getInputsComplete() after the end of showLogging().

This purpose of this callback function is to handle retrieving the Log JSOM values

from the Inputs sheet.

function getInputsComplete(asyncResult) {

writelog('getInputsComplete: Entered');

var format = null;

var range = asyncResult.getReturnValue();

range.getValuesAsync(format, showLogging);

writelog('getInputsComplete: Exited');}

f. Add the following event handler onWorkbookChange() after the end of

getInputsComplete(). Excel Services triggers this event handler every time a cell is

changed. The purpose of this event handler is to check whether the script should

continue logging or not.

function onWorkbookChange(workbookArgs) {

if(workbookArgs.getWorkbook().getActiveSheet().getName()=='Inputs'){

om.getActiveWorkbook().getRangeA1Async('\'Inputs\'!LOG_JSOM',

getInputsComplete);

}

}


16/18

g. Add this remaining code to the end of onSelectionChange(). This will be handling all

the navigation. The function is going to check which cell was selected. If the selected

cell was one that contains a button, it will set the focus of the workbook to the

appropriate place.

if(rangeArgs.getRange().getSheet().getName() == 'Menu' &&

currentSheetName == 'Menu') {

if(rangeArgs.getRange().getAddressA1() ==

'\'Menu\'!C11:D12') {

currentSheetName = 'Inputs';

om.getActiveWorkbook().getRangeA1Async(

'\'Inputs\'!INPUTS',

getRangeComplete);

}else if(rangeArgs.getRange().getAddressA1() ==

'\'Menu\'!C14:D15') {

currentSheetName = 'Financial Statements';

om.getActiveWorkbook().getRangeA1Async('\'Financial

Statements\'!BALANCE_SHEET', getRangeComplete);


'\'Menu\'!C17:D18') {



'\'Financial Statements\'!CASHFLOW',

getRangeComplete);


'\'Menu\'!C20:D21') {



'\'Financial

Statements\'!INCOME_STATEMENT', getRangeComplete);


'\'Menu\'!C23:D24') {

currentSheetName = 'Supporting Data';


'\'Supporting Data\'!A1',

getRangeComplete);

}

} else if (rangeArgs.getRange().getSheet().getName() == 'Menu'

&& currentSheetName != 'Menu' ){

currentSheetName = 'Menu';

} else {

var values = rangeArgs.getFormattedValues();

if (values.length == 1) {

if(values[0][0].trim() == 'Return') {

om.getActiveWorkbook().getSheets()


17/18

.getItemByName('Menu').activateAsync();

}

}

}

2. Save and upload FabriKamReporting.js to the SharePoint site making sure to overwrite the

original.

3. Load FabrikamReporting.aspx to view the changes.

Figure 7

FabrikamReporting.aspx view

Exercise 3 Verification

To verify that the content was loaded correctly for the FabriKam Reports, do the following:

1. Click the Modify Inputs button. This should take you to the Input sheet.

a. Change the Log JSOM cell from yes to no.

b. Change the cell selection and you should see a message to the left stating that

logging has been disabled (Show Logging FALSE).

c. Re-enable it by changing the value back to yes.

2. Click the Return button to return to the main menu.

3. Click on the remaining links to ensure that the rest of the navigation is working correctly.

Summary


18/18

The Excel Services ECMAScript object model is an exciting new part of Excel Services that enables

developers to automate and interact with documents displayed using an Excel Web Access web part. In

this Hands-On Lab, you learned how to connect a script to an Excel Web Access web part, how to use

the events available in the object model, how to debug your scripts, and how to apply this technology to

a common navigation scenario when working with complex Excel workbooks.