Excel User Guide
-
Upload
blasblas1234 -
Category
Documents
-
view
225 -
download
0
Transcript of 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
-
7/30/2019 Excel User Guide
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
-
7/30/2019 Excel User Guide
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 -
7/30/2019 Excel User Guide
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.
-
7/30/2019 Excel User Guide
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
-
7/30/2019 Excel User Guide
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/30/2019 Excel User Guide
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()
-
7/30/2019 Excel User Guide
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());
}
-
7/30/2019 Excel User Guide
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
-
7/30/2019 Excel User Guide
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.
-
7/30/2019 Excel User Guide
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);
-
7/30/2019 Excel User Guide
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
-
7/30/2019 Excel User Guide
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.
-
7/30/2019 Excel User Guide
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();
}
-
7/30/2019 Excel User Guide
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);
}
}
-
7/30/2019 Excel User Guide
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);
}else if(rangeArgs.getRange().getAddressA1() ==
'\'Menu\'!C17:D18') {
currentSheetName = 'Financial Statements';
om.getActiveWorkbook().getRangeA1Async(
'\'Financial Statements\'!CASHFLOW',
getRangeComplete);
}else if(rangeArgs.getRange().getAddressA1() ==
'\'Menu\'!C20:D21') {
currentSheetName = 'Financial Statements';
om.getActiveWorkbook().getRangeA1Async(
'\'Financial
Statements\'!INCOME_STATEMENT', getRangeComplete);
}else if(rangeArgs.getRange().getAddressA1() ==
'\'Menu\'!C23:D24') {
currentSheetName = 'Supporting Data';
om.getActiveWorkbook().getRangeA1Async(
'\'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()
-
7/30/2019 Excel User Guide
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
-
7/30/2019 Excel User Guide
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.