Using Visio Services and the Mash Up API

SharePoint 2010 Technical Article

Writer: Chris Hopkins

Published: 12/2009

Applies to: Visio 2010 / SharePoint 2010

Summary: This document contains a development scenario for building a dashboard on a

SharePoint 2010 site using the Visio Web Access Web Part and the Mash Up API.

2

Copyright

The information contained in this document represents the current view of Microsoft Corporation

on the issues discussed as of the date of publication. Because Microsoft must respond to

changing market conditions, it should not be interpreted to be a commitment on the part of

Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the

date of publication.

This white paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES,

EXPRESS, IMPLIED, OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the

rights under copyright, no part of this document may be reproduced, stored in, or introduced into

a retrieval system, or transmitted in any form or by any means (electronic, mechanical,

photocopying, recording, or otherwise), or for any purpose, without the express written

permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual

property rights covering subject matter in this document. Except as expressly provided in any

written license agreement from Microsoft, the furnishing of this document does not give you any

license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-

mail addresses, logos, people, places, and events depicted herein are fictitious, and no

association with any real company, organization, product, domain name, e-mail address, logo,

person, place, or event is intended or should be inferred.

© 2009 Microsoft Corporation. All rights reserved.

Microsoft, are trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.

3

Contents

Prerequisites ............................................................................................................................................... 4

Introduction .................................................................................................................................................. 5

Publishing and viewing .............................................................................................................................. 7

Visio Web Access Web Part ..................................................................................................................... 9

Introducing the Mashup API ................................................................................................................... 12

Walk thru - Building a dashboard ........................................................................................................... 14

Walk thru – JavaScript explained .......................................................................................................... 19

Complete JavaScript source listing for this walk thru ......................................................................... 23

References ................................................................................................................................................ 29

4

Prerequisites

Before you begin you will want to open the sample diagram that is installed with Visio 2010

named “IT Asset Management”. This diagram demonstrates a sample network equipment

management diagram that could be used to communicate network status to IT management.

Figure 1 - Sample Diagrams available from the File tab

5

Figure 2 - Selection the IT Asset Management sample diagram

The shapes in this diagram have specific Shape Data properties which the functionality in

this article depends on, Network Name, IP Address, Administrator, and Status. Investigate

these properties for the shapes in the sample diagram so you are familiar with their values.

Introduction

SharePoint 2010 includes Visio Services, a new feature that provides SharePoint users with

the ability to view Visio diagrams from within compatible browsers without having to install any

additional components on the client machine.

When viewing a Visio diagram the user can navigate all the pages in the diagram, navigate

any hyperlinks on shapes, select shapes individually to view the shape’s Shape Data, as well as

pan zoom capabilities.

6

Figure 3 - Published diagram example

No additional components are required on the client machine? That is correct. Visio 2010

introduced a new file format that is used to publish Visio diagrams to SharePoint document

libraries, giving SharePoint 2010 and the browser the ability to render the published diagrams.

Prior to SharePoint 2010 this was only possible using the Visio application that was installed on

the client machine, the Visio ActiveX control embedded on a page in the browser, or the Visio

Viewer application or control.

This new file format (VDW) uses PNG and XAML in order to provide this functionality. If the

client machine does not have Silverlight installed, Visio Services will present the diagram using

the PNG format. However, if the client machine does have Silverlight installed, Visio Services

will present the diagram using the XAML format. Silverlight is the preferred method as it allows

for higher fidelity vector based graphics.

7

Figure 4 - Rendered using Silverlight

Figure 5 - Rendered using PNG

Publishing and viewing

The process to publish a Visio diagram to a SharePoint document library is very simple.

From the Visio 2010 client select the File tab on the ribbon and choose the Share option. From

the Share option you will see the option to “Publish to Visio Services”.

8

Figure 6 - Publish to Visio Services

Choose this option and you will be presented with a Save As dialog where you will navigate

to your SharePoint document library, choose any additional save options, and then click the

Save button.

Note: You can also save this file format to any local or network drive and continue to work on

the file. The VDW format is full fidelity so it can be used instead of the previous VSD or VDX

formats. When you are ready to publish you can use the Upload Documents feature in the

Document Library to upload the VDW file.

9

Figure 7 - Publish to Document Library

Once published, your browser will open and navigate to the published version of the diagram

(Figure 3 - Published diagram example) unless you uncheck the “Automatically view files in

browser” option.

Visio Web Access Web Part

Published diagrams are displayed to the user using the Visio Web Access Web Part. This

Web Part provides the interface that allows a user to view and navigate published diagrams

10

from within their browser. Add this Web Part to any of your Web Part pages in SharePoint to

incorporate Visio diagrams into your dashboards or SharePoint application.

To add an instance of the VWA Web Part to your Web Part page simply select the zone on

the page and from the Insert tab on the ribbon choose the Web Part option. From the list of

categories choose Office Client Applications and then Visio Web Access from the list of

available Web Parts.

Figure 8 - Adding the VWA Web Part to a zone

After you add the VWA Web Part to your page you will need to configure each instance of the

VWA Web Part by setting any necessary properties using the Modify Shared Web Part option.

Figure 9 - Modify Shared Web Part

In order to display a particular Visio diagram in this instance of the VWA Web Part you must

set the Diagram URL property. This property must point to a VDW diagram as this is the only

file format that the server can render. If you choose any other file format you will see an error in

11

the Web Part. The Diagram URL property must also point to a location on the same server, it

cannot refer to a document on an external site.

Figure 10 - Setting the Diagram URL property

Once the Diagram URL property has been set and you click on the OK or Apply buttons the

target diagram should be rendered in the VWA Web Part.

12

Figure 11 - Rendered diagram

Introducing the Mashup API

Not only does SharePoint 2010 provide Visio Services functionality to render Visio diagrams

in the browser, it also supports extensibility allowing developers to build server based

applications that incorporate Visio diagrams.

This new API allows developers to interact with a diagram that is hosted in an instance of the

VWA Web Part, providing:

Diagram navigation such as setting the view and zoom level

Shape selection including notification of selection changed

Highlight functionality to highlight shapes

Overlay functionality to add additional markup

13

Shape data access to query individual shape data fields

Hyperlink access to query individual hyperlinks on each shape

The Mashup API is a browser-side JavaScript API with an easy to learn object model and

support up to JavaScript 1.3 as this version of JavaScript is compatible with most browsers.

Figure 12 - Mashup API Object Model

The object model shown above lists all of the objects that are available in the Mashup API

however all of the methods and properties are not documented here. For full documentation

please refer to the Visio 2010 SDK.

getActivePage()

setActivePage()

getShapes()

getItemById() getItemAtIndex()

diagramComplete

shapeMouseEnter

shapeMouseLeave

selectionChanged

diagramError

getSelectedShape()

setSelectedShape()

VWA Control

Page

Shapes

Shape

getShapeData()getHyperlinks()

Shape

14

Walk thru - Building a dashboard

Now that we have our basic Web Part page (created above) that is displaying an instance of

a published diagram using the VWA Web Part, lets add additional functionality to this Web Part

page using the new Mashup API. For this particular example we will add two additional

enhancements to our Web Part page:

1. Selecting a shape in the diagram will present the user with additional information that is

stored in ShapeData for the selected shape. This is data that is of interest to users of

this dashboard.

2. Allow a user to filter the shapes in the diagram by using the Highlight functionality of the

Mashup API to highlight shapes in the diagram that meet specific criteria.

In order to provide the capabilities described above we will need to edit our Web Part page

and add another Web Part that will contain the JavaScript code and HTML. Edit the Web

Part page and insert a Content Editor Web Part in the Right Column zone on the page.

Figure 13 - Adding the HTML Form Web Part

Once this new Web Part has been added to the page you will need to use the Edit Web

Part option to access the properties of this Web Part.

15

Figure 14 – Edit Web Part to link JavaScript source

In order to attach the code to this Web Part, insert the URL of the JavaScript file into the

Content Link property, clicking OK to accept the changes.

Figure 15 - Set the Content Link property to the URL of the JS file

Note: To get the URL, use the Copy Shortcut RMA by right-clicking on the JavaScript file in the

document library.

16

Figure 16 – Copy Shortcut is an easy way to get the URL

Once submitted the Web Part should update, displaying the HTML controls that are part

of this sample code. Not only should the HTML be visible but the JavaScript code is also

active at this point so you can test the code before you exit edit mode and make the page

available to your users.

Figure 17 - HTML Form Web Part rendering our HTML and JavaScript

17

Updating other properties of the Content Editor Web Part will improve the user

experience. For example, set a Title (under the Appearance group) for the Web Part and

you might also change the size of the Web Part for better viewing.

When you are done editing the properties of the Web Part you can click OK to close the

Web Part Content Editor and exit Edit mode on the Web Part page.

Figure 18 - Web Part Page running in Edit mode

18

To test the functionality that we added using JavaScript you should be able to click on a

shape in the drawing and the HTML TextBox controls should populate with property values from

the selected shape. Clicking on any of the radio buttons for Status should add a highlight to any

shapes on the page with a Status property matching the selected value.

Figure 19 - Status property used to highlight shapes

19

Walk thru – JavaScript explained

onApplicationLoad

This method is responsible for getting the instance of the VWA control on the Web Part page.

Once you have the instance of the VWA control you can call the addHandler() method to

connect to the events supported by the VWA control, which for this example are

diagramComplete and shapeSelectionChanged.

new Vwa.VwaControl("WebPartWPQ3")

This returns the named instance of the VWA control on the Web Part

page.

addHandler(string event, function handler)

This method is not specific to the VWA control but allows you to

connect functions to events on the target object.

o event is the name of the event on the VWA control instance

"shapeselectionchanged"

"diagramcomplete"

o handler is the name of the function to call.

Note: The only gotcha in this method is the name of the VWA control instance.

"WebPartWPQ3" in this example happens to be the name assigned to the VWA Web Part

instance. Assigned because when you inserted the control on your Web Part page

SharePoint assigned this name automatically to the control instance. "WebPartWPQ#" is

the format used where # is the next Web Part instance on the page.

This id is not available from the UI. The best way to determine the id of the Visio Web Part

is to open the source for the page and search for it by searching for class="VisioWebAccess".

From the View menu on your browser, choose Source and then in the text editor search for

class="VisioWebAccess".

20

Figure 20 - Searching for the Web Part id

You will see the id attribute in the parent node above the class attribute as shown in Figure 20 -

Searching for the Web Part idabove.

onDiagramComplete

This method is called when the diagram is finished rendering in the VWA control instance. We

connected this method to the diagramComplete event in the onApplicationLoad method

described above.

This method simply gets the instance of the ActivePage from the control and sets a zoom value.

This actually turns out to be a good debugging technique that will indicate you were successful

retrieving the VWA control instance in the onApplicationLoad method. If your specific zoom

value is not set when the diagram renders then you know that you were not successful in getting

the instance of the VWA control and you will need to verify the control name that you used.

getActivePage()

This method returns the instance of the Page object that is the active

page in the VWA control instance.

21

shapeSelectionChangedHandler

As the name implies this is the method that we connected to the shapeSelectionChanged event

in the onApplicationLoad method described above.

This method is responsible for retrieving Shape Data values from the selected shape and

populating the HTML controls on the page. To accomplish this we need to first get the active

page from the control (getActivePage). Then we need to get the shapes collection from the

active page (getShapes). Once we have the shapes collection we need to get the selected

shape by passing the shapeId argument to the getItemFromId method on the shapes collection.

Finally, once we have the selected shape, we can call the getShapeData method which will give

us an array of the Label and Values for all the Shape Data properties. With the label and values

from Shape Data we can populate our HTML controls appropriately.

getItemById(string shapeId)

This method returns the instance of the shape based on the shapeId

argument.

o shapeId is the Sheet Name used in Visio.

getShapeData()

This method returns an array of shape data items.

o The label property of each item returns the value from the Label

cell of the Property row of the ShapeSheet.

o The value property of each item returns the value from Value cell

of the Property row of the ShapeSheet.

22

Highlight

A nice feature of the Mashup API is the ability to highlight shapes on the active page. The

addHighlight() method on the Shape object draws a rectangle around the target shape. You

can specify the line weight and the line color of the rectangle. removeHighlight() is responsible

for removing a highlight from the target shape.

This method is called from the HTML input controls on our page using the onClick attributes

(onclick="Highlight()") of each control. Each time a user clicks on one of these controls

our Highlight method is called.

The first thing our Highlight method does is clean up the active page of any existing highlighted

shapes. It walks thru the shapes collection calling removeHighlight() for each shape on the

active page.

Secondly, our Highlight method uses the value attribute (value="ok") of the clicked HTML

control as the filter to determine which shapes to highlight. The method walks thru each shape

in the active page’s shapes collection, gets the array of Shape Data from the getShapeData

method and determines if the shape has a specific property and value. If so we call the

addHighlight() method on the shape.

removeHighlight()

this method does not accept any arguments. It removes any

existing highlights on the target shape.

addHighlight(int width, string color)

this method adds a highlight rectangle to the target shape as

specified by the following arguments

o width - must be a positive integer.

o color - accepts “#RRGGBB” formatted values.

23

Complete JavaScript source listing for this walk thru

Below is all the source needed for the functionality described in this article.

<script language="javascript">

// hook up Application event handlers

var app = Sys.Application;

app.add_load(onApplicationLoad);

app.add_unload(onApplicationUnload);

// hold an instance of the Visio VWA control

var vwaControl;

var shapeSelectionChangedHandler = null;

//----------------------------------------------------------

// Wait till the Visio Web Access HTML & Script has been sent

// down from the server, and create a VwaControl Object

// (the root Visio Web Access object) for use throughout the

// script.

//

// Also add handlers for the onDiagramComplete &

// shapeSelectionChanged we'll for the solution.

//----------------------------------------------------------

function onApplicationLoad()

{

vwaControl= new Vwa.VwaControl("WebPartWPQ3"); // this is the name of the

visio Web Part instance on the Web Part page

vwaControl.addHandler("diagramcomplete", onDiagramComplete);

vwaControl.addHandler("shapeselectionchanged",

shapeSelectionChangedHandler);

}

//----------------------------------------------------------

// Handler for unloading of this page.

//----------------------------------------------------------

function onApplicationUnload()

{

//alert("unloading");

}

24

//----------------------------------------------------------

// Wait till the default page is loaded by VwaControl; get

// references to all of these objects for later use during

// the script.

//----------------------------------------------------------

function onDiagramComplete()

{

var vwaPage = vwaControl.getActivePage();

vwaPage.setZoom(75); // force the initial zoom level

}

//----------------------------------------------------------

// On shape selection changed, this function extracts the

// Shape Data from a shape and passes it along as a URL

// parameter to the HRDataSystem ASPX application that is

// being displayed in the EmployeeData IFRAME on the page.

//----------------------------------------------------------

shapeSelectionChangedHandler = function(source, args)

{

// get the selected shape from the shapes on the page

var vwaPage = vwaControl.getActivePage();

var vwaShapes = vwaPage.getShapes();

var shape = vwaShapes.getItemById(args);

// get the data to display for the selected shape

var data = shape.getShapeData();

var strNetworkName = "";

var strIPAddress = "";

var strAdministrator = "";

var strStatus = "";

for (var j = 0; j < data.length; j++)

{

if (data[j].label == "Network Name")

{

strNetworkName = data[j].value;

continue;

}

if (data[j].label == "IP Address")

{

strIPAddress = data[j].value;

continue;

}

25

if (data[j].label == "Administrator")

{

strAdministrator = data[j].value;

continue;

}

if (data[j].label == "Status")

{

strStatus = data[j].value;

continue;

}

}

// get the selected state input and set its value

var inputNetworkName = document.getElementById('strNetworkName');

inputNetworkName.value = strNetworkName;

var inputIPAddress = document.getElementById('strIPAddress');

inputIPAddress.value = strIPAddress;

var inputAdministrator = document.getElementById('strAdministrator');

inputAdministrator.value = strAdministrator;

var inputStatus = document.getElementById('strStatus');

inputStatus.value = strStatus;

}

//----------------------------------------------------------

// Highlight method

//----------------------------------------------------------

function Highlight()

{

var vwaPage = vwaControl.getActivePage();

var vwaShapes = vwaPage.getShapes();

var vwaShapeCount = vwaShapes.getCount();

// clean up any existing highlights before we highlight other choices

for (var nextShapeIndex = 0; nextShapeIndex < vwaShapeCount;

nextShapeIndex++)

{

var nextShape = vwaShapes.getItemAtIndex(nextShapeIndex);

if (nextShape == null)

{

continue;

}

else

{

26

nextShape.removeHighlight();

}

}

//---------------------------------------------------

// Go through all controls on the page (could be more

// efficient) and find the solution's checkboxes. Then

// Highlight the appropriate shapes by assigning

// to rackSetToInterate the the appropriate array of

// of shapeIds and iterating though them.

//---------------------------------------------------

var inputs = document.getElementsByTagName('input');

var strSelectedStatusValue = "";

for(var i=0; i < inputs.length; i++)

{

// check if the input is a checkbox

if (inputs[i].getAttribute('type') == 'radio' &&

inputs[i].id == "StatusSelector" &&

inputs[i].checked)

{

strSelectedStatusValue = inputs[i].value;

break;

}

}

// chose the color based on the status selected

var highlightColor = "red";

if (strSelectedStatusValue == "ok")

{

highlightColor = "green";

}

if (strSelectedStatusValue.length > 0)

{

// what we actually want to do here is find the shape based on the

ShapeData HealthState property that has a matching

// value to the selected input control

27

for (var nextShapeIndex = 0; nextShapeIndex < vwaShapeCount;

nextShapeIndex++)

{

var nextShape = vwaShapes.getItemAtIndex(nextShapeIndex);

if (nextShape == null)

{

continue;

}

else

{

// inputs[i].value - this is the selected value in the radio

control that needs to match the HealthState property in the shape

// get the shape data

var data = nextShape.getShapeData();

for (var j = 0; j < data.length; j++)

{

if (data[j].label == "Status")

{

if (strSelectedStatusValue.toLowerCase() ==

data[j].value.toLowerCase())

{

nextShape.addHighlight(4, highlightColor);

}

continue;

}

}

}

}

}

}

</SCRIPT>

28

Network Name:<br>

<input id="strNetworkName" name="NetworkName" style="width: 284px"

type="text" />

IP Address:<br>

<input id="strIPAddress" name="IPAddress" style="width: 284px" type="text" />

Administrator:<br>

<input id="strAdministrator" name="Administrator" style="width: 284px"

type="text" />

Status:<br>

<input id="strStatus" name="Status" style="width: 284px" type="text" />

<br>

<hr>

<br>

Filter Options

<br>

<input type="radio" id="StatusSelector" name="StatusSelector" value="ok"

onclick="Highlight()">Online</input><br>

<input type="radio" id="StatusSelector" name="StatusSelector"

value="unavailable" onclick="Highlight()">Offline</input><br>

<input type="radio" id="StatusSelector" name="StatusSelector" value="unknown"

onclick="Highlight()">Unknown</input><br>

<br>

<input type="radio" id="StatusSelector" name="StatusSelector" value="none"

onclick="Highlight()">None</input><br>

29

References

JavaScript references

Sys.Application class

Sys.Application Load event

Visio references

Visio Insights – Announcing Visio Services