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

2
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

3
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

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

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

6
 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”.

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

8
 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

9
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
10
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.

11
 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

12
  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.

VWA getActivePage()

Control setActivePage()

diagramComplete getShapes()
Page
shapeMouseEnter

shapeMouseLeave Shapes
selectionChanged
getItemById() getItemAtIndex()
diagramError

Shape Shape
getSelectedShape()
setSelectedShape()

getShapeData()
getHyperlinks()

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.

13
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.
14
 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.

15
 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

16
 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

17
 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

18
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".

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

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

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

22
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");
}

23
//----------------------------------------------------------
// 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;
}

24
 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
{
25
 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

26
 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>

27
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>

28
References

JavaScript references

Sys.Application class

Sys.Application Load event

Visio references

Visio Insights – Announcing Visio Services

29