Adding Overlays to Drawings in Visio Services in SharePoint Server 2010

Article
07/24/2014

Office Visual How To

Summary: Learn how to add overlays to shapes in a Visio Web Access Web Part on a Microsoft SharePoint Server 2010 Web Parts page by using ECMAScript (JavaScript, JScript) code.

Provided by: Eric Schmidt, Microsoft Corporation

By using the JavaScript object model for Visio Services in Microsoft SharePoint Server 2010, you can add text, HTML, or Silverlight overlays to shapes displayed in a Visio Web Access Web Part on a SharePoint Server 2010 Web Parts page. By using the code sample that is shown in this Visual How To (which is based on the code sample Annotations.js in the SharePoint 2010 SDK) you can update a Visio Web Drawing to display an overlay in relation to a shape that you select.

Note

You must have appropriate administrative permissions as a page designer in SharePoint Server 2010 to add this code sample to a SharePoint Server 2010 Web Parts page. In addition, Visio Services must be installed and enabled on the SharePoint Server 2010 site.

This Visual How To describes how to use the JavaScript object model for Visio Services to create a Visio Web Access Web Part on a SharePoint Server 2010 Web Parts page that has controls to add different types of overlays on the shapes in the displayed drawing. To use the code sample that is shown in this Visual How To, you should already be familiar with JavaScript.

Before you can use JavaScript to interact with a Visio diagram on a SharePoint site, you have to save the diagram as a Visio Web Drawing (.vdw file) to a document library on the site.

To save a Visio drawing as a .vdw file on a SharePoint site

In Visio, create the drawing that you want to display on the SharePoint site.
On the File tab, click Save & Send.
Under Save & Send, click Save to SharePoint.
Under Save to SharePoint, select the Web Drawing (*.vdw) file type, and then click Save As.
Browse to the document library on the SharePoint site where you want to display the file, name the file, and then click Save.

After you have published your Visio Web Drawing to the SharePoint site, you must create a SharePoint Server 2010 Web Parts page to contain your Visio Web Access Web Part.

To create a Web Parts page

In the SharePoint site where you want to post your drawing, on the Site Actions menu, click More Options.
Under Filter By, click Page, select Web Part Page, and then click Create.
On the new Web Parts page, in the Name box, type a file name for the page.
Choose a layout template and the location where you want to save the page file, and then click Create.

Once you have created a Web Parts page on the SharePoint site, you can add a Visio Web Access Web Part to the Web Parts page and open the Visio Web Drawing in that Web Part.

To add a Visio Web Access Web Part to a Web Parts page

In the Server ribbon on the SharePoint Server 2010 Web Parts page, click Edit Page.
In the zone where you want to place the Web Part, click Add a Web Part.
In the Categories list, click Business Data.
Click Visio Web Access, and then click Add.
Click the Visio Web Access Web Part Menu arrow, and then click Edit Web Part.
Type the URL of the Web Drawing (.vdw file) you want to open, and then click OK.

Your SharePoint Server 2010 page must also include a Content Editor Web Part to hold your JavaScript code. In this code sample, the Content Editor Web Part also provides a display interface for output from your JavaScript code.

To add a Content Editor Web Part to a Web Parts page

If the page is not already in edit mode, on the Server ribbon on the SharePoint Server 2010 Web Parts page, click Edit Page.
In the zone where you want to place the Content Editor Web Part, click Add a Web Part.
In the Categories list, click Media and Content.
In the Web Parts list, click Content Editor, and then click Add.
Click the Content Editor Web Part Menu arrow, and then click Edit Web Part.
Type the URL of the .js file that you want to open, and then click OK.
On the ribbon, click Stop Editing.

With the Visio Web Access and Content Editor Web Parts added to your Web Parts page, you can start creating the file to contain your JavaScript code.

To create a new JavaScript file in Microsoft Visual Studio 2010

In Visual Studio 2010, click File, point to New, and then click File.
In the New File dialog box, under Installed Templates, click Web.
In the list of templates, click JScript File, and then click Open.
After the file opens, click File, and then click Save As.
In the Save File As dialog box, do the following:
1. Browse to the document library on the SharePoint site where the Visio Web Drawing is located.
2. In the File name box, type the name that you want to use for the JavaScript file.
3. Click Save.

Now you can add the JavaScript code to the JavaScript (.js) file.

To add JavaScript to the JavaScript file

Add the following HTML tag to the beginning of the file.
```
<script type="text/javascript">
```

Use the following code to create the HTML <input> elements for the user controls in the Content Editor Web Part.

// Create a list of target shapes that can receive an annotation.
document.write('<br>Target shape:');
document.write('<br><select id-"shapelist"' +
        'size="5" style="width:200px"></select>'); 

// Create a list of annotation types.
document.write('<br>Type of annotation:');
document.write('<br><select id="annotationTypeList">' +
        '<option value="highlight">Highlight Shape</option>' +
        '<option value="overlayImage">Overlay Image</option>' +
        '<option value="overlayText">Overlay Text</option>' +
        '<option value="overlayCustomXAML">Overlay Custom XAML (Silverlight only)</option>' +
        '<option value="overlayCustomHTML">Overlay Custom HTML (PNG only)</option>' +
        '</select>');

//  Create a list of possible horizontal positions for annotations.
//  This parameter does not apply to the highlight annotation. 
document.write('<br>Horizontal Position of overlays (overlay annotations only):');
document.write('<br><select id="hPositionList">' +
        '<option value="0">Horizontal Left</option>' +
        '<option value="1">Horizontal Center</option>' +
        '<option value="2">Horizontal Right</option>' +
        '</select>');

//  Create a list of possible vertical positions for annotations.  
//  This parameter does not apply to the highlight annotation. 
document.write('<br>Vertical position of overlays (overlay annotations only):');
document.write('<br><select id="vPositionList">' +
        '<option value="0">Vertical Top</option>' +
        '<option value="1">Vertical Middle</option>' +
        '<option value="2">Vertical Bottom</option>' +
        '</select>');

//  Create a button to update the Web Drawing with the selected annotations.
document.write('<br>');
document.write('<input id="UpdateDiagram" type="button" ' + 
        'value="Update Diagram" onclick="updateDiagram()">');

Use the following code to declare a global variables for the code.

// Declare a global variable for the Visio Web Access Web Part,
// the current page displayed in the Web Part, the shapes on the page,
// and the currently highlighted page.
var vwaControl;
var vwaPage;
var vwaShapes;
var currentlyAnnotatedShape;

Use the following code to create a handler for the AJAX Sys.Application.load event.

// Add the onApplicationLoad handler to the Sys.Application.load event.
Sys.Application.add_load(onApplicationLoad)

Use the following code to create the onApplicationLoad handler function. The function creates a reference to the Visio Web Access Web Part by creating an instance of the Vwa.VwaControl class and adds a handler to the Vwa.diagramcomplete event of that Vwa.VwaControl object.

// Capture a reference to an instance of the Visio Web Access Web Part.
function onApplicationLoad() {
    try{
        vwaControl= new Vwa.VwaControl(getVWAWebPartID());
        vwaControl.addHandler("diagramcomplete", onDiagramComplete);
    }
    catch(err){
    }
}

// Get the Web Part ID for the Visio Web Access Web Part.
function getVWAWebPartID() {
    // Iterate through each <div> tag on the page.
    var divArray = document.getElementsByTagName("div");
    var webPartElementID;
    for (var i = 0; i < divArray.length; i++) {
        var node = divArray[i];

        // If the class attribute of the tag is "Visio Web Access", 
        // return the id attribute of the grandparent tag.
        if (node.className == "VisioWebAccess") {
            webPartElementID = node.parentNode.parentNode.id;
            break;
        }
    }
    return webPartElementID;
}

Use the following code to create the handler for the Vwa.diagramcomplete event. This function initializes the global variables and sets the zoom for the currently displayed page in the diagram. The onDiagramComplete function also calls the populateShapeList function, which adds an <option> element to the <select id='shapelist'> element for each shape in the drawing.

// Define the global variables, set the zoom, and call the populateShapeList function.
function onDiagramComplete() {
    try{
        vwaPage = vwaControl.getActivePage(); 
        vwaShapes =  vwaPage.getShapes(); 
        vwaShapeCount = vwaShapes.getCount();
        vwaPage.setZoom(-1); 
        populateShapeList();
        
    }
    catch(err){
    }
}

// Add each shape in the drawing as an option in the Target shape list in the 
// Content Editor Web Part.
function populateShapeList() {
    try{
        var shapeSelect = document.getElementById("shapeList");

        // Iterate through each shape in the vwaShapes collection.
        for (var i = 0; i < vwaShapeCount; i++) {

            // Get the name and ID of the shape.
            var shapeName = vwaShapes.getItemAtIndex(i).getName();
            var shapeId = vwaShapes.getItemAtIndex(i).getId();

            // Create a new <option> element, append it to the <select> element, 
            // and set the value and text of the <option> element.
            var optionElement = document.createElement("option");
            shapeSelect.appendChild(optionElement);
            optionElement.value = shapeId;
            optionElement.text = shapeName;
        }
    }
    catch(err){
    }
}

Use the following code to add the selected overlay to a specific shape in the drawing.

// Add the selected overlay to the drawing.
function updateDiagram() {
    try{
        var shapeSelect = document.getElementById("shapeList");

        // Check whether a target shape was selected.
        if (shapeSelect.selectedIndex < 0) {
            alert("Please select a target shape.");
            return;
        }
        else{
            // If a shape is selected, retrieve a reference to the selected shape.
            var targetShapeId = shapeSelect.options[shapeSelect.selectedIndex].value;
            var targetShape = vwaShapes.getItemById(targetShapeId);
        }

        // Get the selected annotation type.
        var annotationTypeSelect = document.getElementById("annotationTypeList");
        var annotationType = annotationTypeSelect.options[annotationTypeSelect.selectedIndex].value;

        // Get the selected horizontal position.
        var hPositionSelect = document.getElementById("hPositionList");
        var horizontalPosition = parseInt(hPositionSelect.options[hPositionSelect.selectedIndex].value);

        // Get the selected vertical position.
        var vPositionSelect = document.getElementById("vPositionList");
        var verticalPosition = parseInt(vPositionSelect.options[vPositionSelect.selectedIndex].value);

        // Remove the current annotation.
        removeAnnotation(); 

        // Draw the annotation specified by the user.
        switch (annotationType) {

            // Draws a highlight. 
            case ("highlight"):
                targetShape.addHighlight(5,"#00FF00");
                break; 

            // Draws a text overlay.
            case ("overlayText"):
                targetShape.addPredefinedOverlay(
                    Vwa.OverlayType.text,
                    "Overlay",
                    "Here is some text.",
                    horizontalPosition, 
                    verticalPosition);
                    break;

            // Draws an image overlay.
            case ("overlayImage"):
                targetShape.addPredefinedOverlay(
                    Vwa.OverlayType.image,
                    "Overlay",
                    "http://someSharePointSite/someLibrary/someImage.png",
                    horizontalPosition, 
                    verticalPosition);
                    break;

            // Draws a XAML overlay.
            case ("overlayCustomXAML"):
                targetShape.addOverlay(
                    "Overlay", 
                    "<Rectangle Height=\"" + targetShape.getBounds().height + "\"" + 
                    " Width=\"" + targetShape.getBounds().width + "\"" + 
                    " Stroke=\"Black\" StrokeThickness=\"1\" Fill=\"#88FF0000\"" + 
                    " RadiusX=\"0.0\" RadiusY=\"0.0\"\/>",
                    horizontalPosition, 
                    verticalPosition,
                    targetShape.getBounds().width,
                    targetShape.getBounds().height);
                    break;

            // Draws an HTML overlay.
            case ("overlayCustomHTML"):
                targetShape.addOverlay(
                    "Overlay", 
                    "<div id=\"HTMLDiv\" style=\"width: 100%; height:" + 
                    "100%;background-color:#FF0000;z-order:32;" + 
                    "filter:alpha(opacity=30);\"><\/div>", 
                    horizontalPosition, 
                    verticalPosition,
                    targetShape.getBounds().width,
                    targetShape.getBounds().height);
                    break;
        }

        // Update currentlyAnnotatedShape so that the annotation can be 
        // cleared the next time the user clicks Update.
        currentlyAnnotatedShape= targetShape;
    }
    catch(err){
        alert(err);
    }
}

Use the following code to remove the overlay from the currently annotated shape.

// Remove the annotation from the currentlyAnnotateShape.
function removeAnnotation() {
    try{
         if (typeof(currentlyAnnotatedShape)!="undefined") {
             currentlyAnnotatedShape.removeHighlight();
             currentlyAnnotatedShape.removeOverlay("Overlay");
         } 
    }
    catch(err){
    }
}

Below the JavaScript code, add a closing </script> HTML tag.

After you have finished editing the JavaScript file and saved it to the SharePoint site, you have to insert the file into the Content Editor Web Part on the Web Parts page.

To insert the JavaScript file into the Content Editor Web Part

On the SharePoint page, click the Content Editor Web Part Menu arrow, and then click Edit Web Part.
Type the URL of the .js file that you want to insert, and then click OK.

Visio Services introduces a new way to share and explore Visio drawings. You can add code to a Visio Web Drawing that will dynamically annotate shapes in the drawing in response to events in the browser. The JavaScript object model for Visio Services exposes several methods that you can use to add overlays to shapes that are displayed in a Visio Web Access Web Part.

Writing HTML in a Content Editor Web Part

The code sample that accompanies this Visual How To creates several HTML selection lists for selecting shapes in the drawing and specifying the type of annotation to apply to the shape. To do this, the sample uses the document.write method of the Content Editor Web Part to create a button and several <select> HTML elements inside the Content Editor Web Part. (Like a <frame> HTML element, the Content Editor Web Part contains a document object that you can use to access the content in the scope of the Web Part itself.) When the onclick event of the button is raised, the code calls the updateDiagram function that annotates a shape in the diagram.

Although neither the HTML button nor the HTML lists are necessary to add an overlay to shapes in a Visio Web Access Web Part, you have to use a Content Editor Web Part to access the JavaScript object model for Visio Services. The Content Editor Web Part acts as a container for your script and inserts your script into the page when the SharePoint page loads.

Adding a Handler to the AJAX Sys.Application.load Event

To load your script when the page loads, you have to add a handler to the AJAX Sys.Application.load event, which is raised after all other scripts have been loaded and the objects in the application have been created and initialized. In the code sample, the Sys.Application.load event calls the onApplicationLoad function.

The onApplicationLoad function first captures a reference to the Visio Web Access Web Part by creating a new Vwa.VwaControl object and assigning it to the vwaControl variable. Then, the onApplicationLoad function registers the onDiagramComplete function as a handler for the Vwa.diagramcomplete event of the vwaControl object. (The Vwa.diagramcomplete event is raised when the diagram is loaded, refreshed, or changed.)

Capturing a Reference to the Visio Web Access Web Part

Before you can access most of the JavaScript object model for Visio Services, you have to first capture a reference to the current instance of the Visio Web Access Web Part by creating an instance of the Vwa.VwaControl class. The code sample uses the handler for the AJAX Sys.Application.load event to capture that reference by creating an instance of the Vwa.VwaControl class.

The constructor method for the Vwa.VwaControl class has one required parameter: the Web Part ID for the Visio Web Access Web Part. The Web Part ID of the Visio Web Access Web Part (which is in the format WebPartWPQ#) is contained in the id attribute of the grandparent <div> tag of the <div> tag that contains the attribute class="VisioWebAccess" on the Web Parts page.

Note

If there is more than one Visio Web Access Web Part on the Web Parts page, there will be corresponding <div> tags that have the attribute class="VisioWebAccess".

There are several ways to find the Web Part ID of the Visio Web Access Web Part:

In your browser, you can view the HTML source code of the SharePoint Web Parts page and search for the phrase class="VisioWebAccess".
You can have your JavaScript code get the Web Part ID when the script loads.

The code sample uses the getVWAWebPartID function to get the Web Part ID of the Visio Web Access Web Part. The function uses the document.getElementsByTagName method to create an array of all the <div> tags on the page. (You could also use the document.getElementsByClassName method if your browser supports that method.) The function iterates through each item in the array until it finds the first item that has the attribute class="VisioWebAccess" and returns the grandparent node of that item.

Creating the Handler for the Vwa.diagramcomplete Event

In the code sample, the onDiagramComplete function initializes most of the global variables, sets the zoom for the currently displayed page in the drawing, and calls the populateShapeList function.

The function creates instances of the Vwa.Page and the Vwa.ShapeCollection classes—the global variables vwaPage and vwaShapes, respectively—to refer to the active page in the drawing and the shapes collection on that page.

The populateShapeList function adds new <option> HTML elements to the <select> element with the attribute id="shapelist" in the Content Editor Web Part. For each shape in the vwaShapes collection, the function gets the name and ID of the shape from the drawing, creates a new <option> element, adds the new element to the list, and sets the text and value attributes of the new element to the name and ID of the shape, respectively.

Adding and Removing Highlights and Overlays to Shapes

The JavaScript object model for Visio Services includes three methods for annotating a shape in a Visio Web Access Web Part: the VwaShape.addHighlight method, the VwaShape.addPredeterminedOverlay method, and the VwaShape.addOverlay method. A shape can have more than one overlay, and the overlay resizes or moves with the shape when the user pans or zooms in the Visio Web Access Web Part. The code sample uses the updateDiagram function to remove any current annotation and to add a single overlay to a single shape in the drawing.

The VwaShape.addHighlight method adds a rectangular highlight around the bounding box of the shape. It has two required parameters:

width—A positive integer value that determines the width, in pixels, of the highlight.
color—A string that specifies the color of the highlight in an RGB format "#RRGGBB" where the red, green, and blue values are expressed as hexadecimal numbers between 00 (0) and FF (255).

The code sample uses the value #00FF00, which is equal to red 0, green 255, and blue 0.

Note

A shape can have only one highlight.

The VwaShape.addPredefinedOverlay method adds a specific overlay—image or text—to the shape. The method has three required and four optional parameters:

overlayType—A constant from the Vwa.OverlayType enumeration that specifies the type of the overlay. A text overlay has the value VwaOverlayType.text. An image overlay has the value VwaOverlayType.image.
overlayID—A string that specifies the unique ID of the overlay. It must be unique among all the currently displayed overlay identifiers.
content—A string that determines the content of the overlay. For a text overlay, this string is the exact text of the overlay. For an image overlay, this parameter is the URL of the image file that is stored on the SharePoint site.
horizontalPosition—An optional constant from the Vwa.HorizontalAlignment enumeration that sets the horizontal position of the center of the overlay, relative to the bounding box of the shape. The default value is Vwa.HorizontalAlignment.center.
verticalPosition—An optional constant from the Vwa.VerticalAlignment enumeration that sets the vertical position of the center of the overlay, relative to the bounding box of the shape. The default value is Vwa.VerticalAlignment.middle.
overlayWidth—An optional positive integer that sets the width, in pixels, of the overlay. The default value is 100.
overlayHeight—An optional positive integer that sets the height, in pixels, of the overlay. The default value is 50.

The VwaShape.addOverlay method adds a new overlay to the shape based on the content of the shape. The code sample uses this method twice to create two different overlays: an overlay created by a <div> HTML element and an overlay created by a <Rectangle> XAML element (Silverlight).

Note

The type of overlay to use—HTML or Silverlight—depends on the display mode of the Visio Web Access Web Part. You have to use an HTML element for the overlay if the current display mode is Vwa.DisplayMode.raster, or use a XAML element if the current display mode is Vwa.DisplayMode.silverlight. You can get the current display mode for the Visio Web Access Web Part by calling the VwaControl.getDisplayMode method.

To change the current display mode of the Visio Web Access Web Part, do the following:

Click Visio Web Access Web Part Menu arrow, and then click Edit Web Part.
In the Visio Web Access tool pane, under Web Drawing Display, do one of the following:
- To set the Visio Web Access Web Part display mode to Vwa.DisplayMode.raster, select Force raster rendering.
- To set the Visio Web Access Web Part display mode to Vwa.DisplayMode.silverlight, clear Force raster rendering.

The VwaShape.addOverlay method has six required parameters:

overlayID—A string that specifies the unique ID of the overlay. It must be unique among all the currently displayed overlay identifiers.
content—A string that determines the content of the overlay. For a text overlay, this string is the exact text of the overlay. For an image overlay, this parameter is the URL of the image file that is stored on the SharePoint site.
horizontalPosition—A constant from the Vwa.HorizontalAlignment enumeration that sets the horizontal position of the center of the overlay, relative to the bounding box of the shape. The default value is Vwa.HorizontalAlignment.center.
verticalPosition—A constant from the Vwa.VerticalAlignment enumeration that sets the vertical position of the center of the overlay, relative to the bounding box of the shape.
overlayWidth—A positive integer that sets the width, in pixels, of the overlay.
overlayHeight—An optional positive integer that sets the height, in pixels, of the overlay.

The code sample uses the removeAnnotation function to clear any highlights or overlays from the drawing. The function calls the VwaShape.removeHighlight method, which removes the highlight from the shape. The function also calls the VwaShape.removeOverlay method, which removes the overlay that has the specific overlay identifier passed in for the overlayID parameter.

Watch the video

> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/703fa2b6-4b00-4876-8a07-ab221ee15471]

Length: 11:46

Adding Overlays to Drawings in Visio Services in SharePoint Server 2010

To save a Visio drawing as a .vdw file on a SharePoint site

To create a Web Parts page

To add a Visio Web Access Web Part to a Web Parts page

To add a Content Editor Web Part to a Web Parts page

To create a new JavaScript file in Microsoft Visual Studio 2010

To add JavaScript to the JavaScript file

To insert the JavaScript file into the Content Editor Web Part

Additional resources