Hands-On Lab
Using the ECMAScript Object Model for Visio Services
Lab version: 1.0.0
Last updated: 3/30/2011
Contents
Overview 3
Exercise 1: Using the Visio JSOM 4
Task 1 – Creating the Script 4
Task 2 – Setting up the Web Part Page 6
Task 3 – Verifing the Visio Web Access WebPartElementID 9
Exercise 1 Verification 9
Exercise 2: Working with Overlays and Highlights 10
Task 1 – Adding Employee Photos to SharePoint 10
Task 2 – Creating the Visio JSOM Script 11
Exercise 2 Verification 13
Exercise 3: Working with Shape Data 14
Task 1 – Creating a SharePoint List 14
Task 2 – Creating the Script 16
Exercise 3 Verification 18
Summary 19
Overview
Visio Services is a service application for SharePoint Server 2010. The purpose of Visio Services is to allow users to publish and share their Visio web based drawings to a SharePoint site. You can use Visio Services to render a Visio Web drawing which people can view in a Web browser. Since Visio Services does all of the rendering, anyone can view the Visio Web drawing without having Visio or Visio Viewer installed on their computer.
Visio Services includes an ECMAScript (JavaScript or Jscript) Object Model that allows you to integrate JavaScript code with a Visio Web Access web part (a web part used for viewing Visio Web drawings).
Objectives
The objective of this Hands On Lab is to provide you with a foundation for using the Visio ECMAScript object model to expand the functionality of a Visio Web Access web part. In particular, you will
· Experiment with the ECMAScript object model and examine the role it plays in Visio Services
· Add Shape Overlays and Highlights to a Visio Web Access web part using the ECMScript object model
· Use the the ECMAScript object model to retrieve shape data based on the selected shape in a Visio Web Access part and combine it with other SharePoint data to create a convienent user browsing experience
System Requirements
The steps in this Hands On Lab require the following:
· SharePoint 2010
· Visual Studio 2010 (substitute any program that can edit text files)
· This exercise assumes the use of the 2010 Information Worker Demonstration and Evaluation Virtual Machine (RTM),. 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 named %Office2010DeveloperTrainingKitPath%\Labs\VisioJSOM.
Exercises
This Hands-On Lab comprises the following exercises:
1. Using the Visio JSOM
2. Working with Overlays and Highlights
3. Working with Shape Data
Estimated time to complete this lab: 60 minutes.
Starting Materials
This Hands-On Lab includes the following starting materials.
· FabriKamOrgChart.js – This is the ECMAScript you will be building on throughout the exercises that will interact with the Visio Web Access object.
· FabriKamOrgChart.vdw – This is the Visio document will be using to associate with Visio Web Access.
· JPG Files – These images are used to demonstrate overlays.
Exercise 1: Using the Visio JSOM
In this exercise you will learn how to create and use a simple Visio Services JSOM script. The objective of this exercise is to demonstrate all of the tasks required to use the Visio Services JSOM. In this exercise, you will create a simple script that logs user activity on a Visio diagram to a Content Editor Web part.
Task 1 – Creating the Script
In this task, you will be developing a script to use ECMAScript that will allow you to communicate with the SharePoint Visio services.
1. Navigate to %Office2010DeveloperTrainingKitPath%\Labs\VisioJSOM\Starter and open FabriKamOrgChart.js in Visual Studio
2. Add the following variables and function call to your code between the <script> tags. vwaControl will be used to hold a reference to a Visio Services Web Access part instance. vwaPage will be used to hold a reference to the page object. Sys.Application.add_load() is used to add an event handler that is called once the scripts have been loaded and all objects in the application have been loaded and initialized.
var logItems = true;
var webPartElementID = "WebPartWPQ4";
var vwaControl;
var vwaPage;
Sys.Application.add_load(onApplicationLoad);
3. Add the following function to your code after Sys.Application.add_load(). This function is the event handler that was specified in the last step. In this function, you are creating a new Visio Web Access Control object that is associated with the Visio Web Access web part. You are also adding an event handler that will be called once the Visio diagram is done loading.
function onApplicationLoad() {
try {
vwaControl = new Vwa.VwaControl(webPartElementID);
vwaControl.addHandler("diagramcomplete", onDiagramComplete);
}
catch(err) {
}
}
4. Add the following function to your code after the onApplicationLoad() function. This function is the event handler that you specified in the last step. In this function, you obtain a reference to the active Visio page object and add an event handler that is called when the active shape selection changes.
function onDiagramComplete() {
try {
vwaPage = vwaControl.getActivePage();
vwaPage.setZoom(-2);
vwaControl.addHandler("shapeselectionchanged", onShapeSelectionChanged);
}
catch(err) {
}
}
5. Add the following function to your code after the function onDiagramComplete(). This event handler that will be triggered every time the shape selection changes.
function onShapeSelectionChanged() {
var sh = vwaPage.getSelectedShape();
writelog("Logging: onShapeSelectionChanged - " + sh.getName());
}
6. Add the following function to your code after the function onShapeSelectionChanged(). This function will write messages to a Content Editor Web part. You will use it to trace the flow of events as you work with a Visio Web Access web part.
function writelog(item) {
if(logItems) {
var output = item + '<br />';
document.getElementById('logdiv').innerHTML = output +
document.getElementById('logdiv').innerHTML;
}
}
7. Save your changes to FabriKamOrgChart.js
8. Open Internet Explorer and navigate to http://intranet.contoso.com
9. Click on Shared Documents
10. Click on Add Document
11. Click Browse and navigate to %Office2010DeveloperTrainingKitPath%\Labs\VisioJSOM\Starter\ FabriKamOrgChart.js
12. Click Open and then OK
13. Repeat steps 10-12 for FabriKamOrgChart.vdw
Task 2 – Setting up the Web Part Page
In this task, you will be setting up a SharePoint web part page that will incorporate your Visio document and ECMAScript.
1. Open up Internet Explorer and navigate to http://intranet.contoso.com
2. Click the Site Actions dropdown and select More Options
a. Filter by Page, select Web Part Page and click Create
b. Title the page FabriKamOrgChart 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
New Web Part Page dialog
3. Click Add a Web Part in the Body section of the page
a. View the Categories section and select Business Data. View the Web Parts section, select Visio Web Access, and then click Add
b. Click the dropdown menu next to the checkbox in the Visio Web Access web part
c. Select Edit Web Part
d. View the Web Drawing Display section of the Visio Web Access property box and under Web Drawing URL, click the box and navigate to FabriKamOrgChart.vdw, which is located in the Shared Documents folder
e. View the Toolbar and User Interface section and uncheck every option except for Show default background
f. View the Appearance section, set the Height to 600 and change the Chrome Type to None
g. Click OK to save the changes
h. If the checkbox in the Visio Web Access web part is checked, uncheck it
4. Click Add a Web Part in the Left Column section of the page
a. View the Categories section and select Media and Content. View the Web Parts section, select Content Editor and then click Add
b. Click the dropdown menu next to the checkbox in the Content Editor web part
c. Select Edit Web Part
d. Open up the SharePoint site homepage in a new tab or window
i. Click Shared Documents
ii. Find FabriKamOrgChart.js, right-click on it and select Copy shortcut
iii. Go back to the web part page you were working on before
e. Right-click in the box under Content Link in the Content Editor section and select Paste
f. View the Appearance section and set the Width to 200. Be sure to select Yes next to the Width box
g. Set the Chrome Type to None in the Appearance section
h. Click OK to save the changes
5. Click Stop Editing in the top left corner of the page
Figure 2
Web Part
Task 3 – Verifing the Visio Web Access WebPartElementID
In this task, you will learn how to go about verifying the correct web part element ID for a Visio Web Access web part. This is necessary to verify that the web part element ID you use in your script is the web part element ID associated with the Visio Web Access web part you desire to interact with.
1. If you’re not on your web part page already, go to http://intranet.contoso.com, click on Site Pages and click on FabriKamOrgChart
2. Right-click on the page and select View source
3. Search for the keyword class="VisioWebAccess"
4. Look just above that div tag and find the div tag that starts with <div WebPartID
5. Find the id attribute within the div tag and take note of the value of that attribute. That is the web part element ID that needs to be reflected in the ECMAScript. In task 1, that value was WebPartWPQ4. If the element ID does not match, change the value in your FabriKamOrgChart.js script and re-save it to the site.
Figure 3
Web Part Page Source Code
Exercise 1 Verification
To verify that the ECMAScript and Visio Web Access web part are functioning together and correctly, perform the following steps
1. Click on Mike at the top
2. View the content editor along the left side and verify the following output
Logging: onShapeSelectionChanged – Executive
3. Click on additional people to view similar results
Note: If there is nothing being logged, review Task 3 1-5 in the previous exercise section to make sure your JavaScript is referencing the correct WebPart id.
Figure 4
Finished Web Part Page
Exercise 2: Working with Overlays and Highlights
In this exercise, you will learn how to use overlays and highlights on a Visio shape.
Task 1 – Adding Employee Photos to SharePoint
In this task, you will add pictures to the SharePoint site that you will use as overlays on your Visio Web Access web part.
1. Open up Internet Explorer and navigate to http://intranet.contoso.com
2. Click on Shared Documents
3. Click Add document
4. Click Upload Multiple Files…
5. Click Browse for files instead
6. Navigate to %Office2010DeveloperTrainingKitPath%\Labs\VisioJSOM\Starter and select all the 11 JPEG image files
7. Click Open and then OK
8. Click Done
Task 2 – Creating the Visio JSOM Script
This task involves building on FabriKamOrgChart.js to match pictures with the names of the employees on the org chart using overlays. You will also look at using highlights.
1. Open %Office2010DeveloperTrainingKitPath%\Labs\VisioJSOM\Started\FabriKamOrgChart.js in Visual Studio
2. Add the following two variable to your code after
var vwaPage;
var vwaShapes;
var showHighlights = false;
3. Add the following code to onDiagramComplete() after
vwaControl.addHandler(“shapeselectionchanged”, onShapeSelectionChanged);
This code adds two more event handlers that will handle the mouse enter and mouse leave events. You will be using this to handle the overlay effect. The call to setSelectedShape() is going to set the focus of the selected shape to the shape with the name Executive.
vwaShapes = vwaPage.getShapes();
vwaPage.setSelectedShape(vwaShapes.getItemByName("Executive").getId());
vwaControl.addHandler("shapemouseenter", onShapeMouseEnter);
vwaControl.addHandler("shapemouseleave", onShapeMouseLeave);
4. Add the following code to onShapeSelectionChanged() after
writelog(“Logging: onShapeSelectionChanged – “ + sh.getName());
The purpose of the if statement is to check if a particular shape has been selected. In this case, it’s the toggle button at the bottom of the Visio document. If the button is clicked, it will toggle both the logging and the highlights. Note that the setTimeout() function merely calls the function named highlightSVPs() after a 20ms delay. This slight delay is necessary in order to ensure that the highlights toggled in highlightSVPs() are properly displayed.
if(sh.getName()=="LogToggle") {
writelog("Toggling logging");
logItems = !logItems;
setTimeout(highlightSVPs(), 20);
}
5. Add the following two functions after the function onShapeSelectionChanged(). These functions are the two event handlers that will handle the overlay. The first event handler is triggered every time the mouse cursor is moved over a shape. The second is triggered whenever the mouse cursor is moved off the shape.
function onShapeMouseEnter(source, args) {
try {
var shape = vwaShapes.getItemById(args);
var n = shape.getName();
var o = shape.getShapeData();
writelog(o[2].value);
if(n !="LogToggle" &&
n !="Logo" &&
n !="TopHR" &&
n !="BottomHR") {
shape.addOverlay("myOverlay",
"<Image Source=\"http://intranet.contoso.com/Shared Documents/"
+ o[2].value + ".jpg\"
Width=\"50\" Height=\"50\"><\/Image>", 1, 1, 50, 50);
}
writelog("onShapeMouseEnter: shape - " + shape.getName());
} catch (err) {
writelog("onShapeMouseEnter: err - " + err.Message);
}
}
function onShapeMouseLeave(source, args) {
try {
var shape = vwaShapes.getItemById(args);
shape.removeOverlay("myOverlay");
writelog("onShapeMouseLeave: shape - " + shape.getName());
} catch (err) {
writelog("onShapeMouseLeave: err - " + err.Message);
}
}
6. Add the following function after the function onShapeMouseLeave(). This function will be called every time you click on the toggle log button and will toggle the highlighting for all employees who are Senior Vice Presidents.
function highlightSVPs() {
showHighlights = !(showHighlights);
for(var i=0; i<vwaShapes.getCount(); i++)
{
var shape = vwaShapes.getItemAtIndex(i);
var shData = shape.getShapeData();
if(shData.length > 0)
{
if(shData[3].value=="SVP")
{
if(showHighlights)
shape.addHighlight(2, '#FF0000');
else
shape.removeHighlight();
}
}
}
}
7. Save your changes to FabriKamOrgChart.js
8. Upload FabriKamOrgChart.js to the SharePoint site making sure to overwrite the original
Exercise 2 Verification
To verify that the overlay and highlighting is working correctly, perform the following steps
1. Navigate to your SharePoint web part page. If you are already on the web page, make sure to refresh.
2. Move your cursor over Mike. A picture of Mike should then appear over top of the shape.
3. Move your cursor off Mike. His picture should then disappear.
4. Click the Click here to toggle logging button at the bottom. All shapes that contain SVP employees should then have a red box around them.
5. Click another shape to change focus from the toggle button.
6. Click the Click here to toggle logging button again. All highlighting should then be removed.
Note: If you get a JavaScript error (icon in lower left corner of IE) double-click the icon and choose to show detail. Once you see the line number for the error, then view source on the HTML page. Scroll down to the line number for the error. In most cases it will be that when you copy/pasted the code from the work document, the line of code wrapped to several lines. Go back to the original code, merge the separate lines into a single line, save and reupload the .js file to SharePoint. Then navigate to the site page again. If there are more errors, fix these until all are working.