Customizing Visio Web Drawings in the Visio Web Access Web Part

Articolo
07/24/2014

Applies to: SharePoint Server 2010

In this article
Getting Started Programming the Visio Web Access Web Part
Creating a Web Parts Page
Adding a Visio Web Access Web Part to the Web Parts Page
Adding a Content Editor Web Part to the Web Parts Page
Visio Services ECMAScript API
Objects in the Visio Services ECMAScript API
Samples in the SharePoint 2010 SDK

Note

The information in this topic applies to SharePoint 2013 as well as to SharePoint 2010. The samples provided in the SharePoint 2010 SDK also work in SharePoint 2013, but are not included in the SharePoint 2013 SDK.

Visio Services in Microsoft SharePoint Server 2010 enables you to load, display, and interact programmatically with Microsoft Visio 2010 documents that are hosted in an instance of the Visio Web Access Web Part on a Microsoft SharePoint Server 2010 page.

This article provides information about how to add a Visio Web Access Web Part to a SharePoint Server 2010 Web Parts page, display a Visio Web drawing in the Web Part, and interact with that drawing programmatically by using the Visio ServicesJavaScript API.

Getting Started Programming the Visio Web Access Web Part

Before your solution can interact programmatically with a Visio Web drawing on a SharePoint Server 2010 Web Parts page, you must add a Visio Web Access Web Part to the page, open a Visio drawing published as a .vdw file in the Web Part, and add a Content Editor Web Part to the page to contain your ECMAScript (JavaScript, JScript) code.

This procedure assumes you have the appropriate administrative rights as a page designer in SharePoint Server 2010.

To get started programming the Visio Web Access Web Part

In Visio, create the drawing you want to display, and then save it to a SharePoint document library as a .vdw file.
Create the JavaScript (.js) file that contains the code you want to use to interact with the Web drawing, and save it to the same document library that holds the .vdw file.
Create a SharePoint Server 2010 Web Parts page to display your drawing and contain your code.
Add a Visio Web Access Web Part to the page, and display the Web drawing in the Web Part.
Add a Content Editor Web Part to the page, and link it to the JavaScript file you created earlier.
Refresh the page in your browser.

The following sections provide more detail about some of these steps. You can find information about publishing Visio drawings as .vdw files in Visio Help. You can create an JavaScript file in Microsoft Visual Studio 2010 or any other text or code editor.

Note

There are many books and online articles available that provide general guidelines for coding in JavaScript, which is beyond the scope of this article.

Creating a Web Parts Page

After you have published your Visio drawing as a .vdw file, saved it to a document library, and created your JavaScript (.js) file and saved it to the same library, the next step is to create a Web Parts page.

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 Pages and Sites, click Web Part Page.
On the New Web Part 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.

Adding a Visio Web Access Web Part to the Web Parts Page

Before you can interact programmatically with a Web drawing on a SharePoint Server 2010 Web Parts page, you must add a Visio Web Access Web Part to the Web Parts page you created, and open a Visio drawing published as a .vdw file in the 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 arrow next to Web Part Menu, and then click Edit Web Part.
Type the URL of the Web drawing (.vdw file) you want to open, and then click OK.

Adding a Content Editor Web Part to the Web Parts Page

The Content Editor Web Part serves two purposes: it holds your JavaScript code, and it provides a display and control interface that enables you to interact in real time with the .vdw file in the Visio Web Access Web Part.

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 arrow next to Content Editor Web Part Menu, and then click Edit Web Part.
Type the URL of the .js file you want to open, and then click OK.
On the ribbon, click Stop Editing.

Visio Services ECMAScript API

The JavaScript object model in Visio Services gives you programmatic access to Visio drawings displayed as .vdw files in the Visio Web Access Web Part. Using the Visio ServicesJavaScript object model, you can access shape data, hyperlinks, and shape bounding box coordinates. You can also create mashups that target specific diagram pages, select and highlight shapes, place markup overlays on the diagram, respond to mouse events, and change the panning and zooming properties of the viewport. (A mashup is an application that enables you to combine functionality or data from multiple sources into a single, integrated service, application, or medium.)

As with many JavaScript APIs, the Visio Services ECMAScript API is event-based. To program the Visio Web Access Web Part, you write handlers that call functions in response to events raised in the diagram.

Objects in the Visio Services ECMAScript API

The Visio ServicesJavaScript API contains only four objects and their respective members:

In addition, the Visio ServicesJavaScript API contains four enumerations:

VwaControl Object

The VwaControl object represents an instance of the Visio Web Access Web Part. By using the methods of the VwaControl object, you can access information about the Web Part and about the Visio drawing rendered in the Web Part. In addition, by using these methods you can perform various actions, such as opening a Visio document in the Web Part, getting and setting the active page being displayed, adding or deleting event handlers, and displaying or hiding custom messages.

In your JavaScript code, you can get a reference to the VwaControl object by attaching a handler to the load event of the ASP.NET AJAX Sys.Application class. In the function that implements that handler, you can initialize the object by passing it the HTML identifier (ID) of the Visio Web Access Web Part that you want to host the object. You can obtain that ID by examining the source code of the HTML page that hosts the Web Part, and searching for the phrase class="VisioWebAccess". The ID is in the format "WebPartWPQ*#*", where # represents the identifying number of the Web Part. The following code example shows how to do this. It assumes that you have determined that the Web Part ID is WebPartWPQ3, and that you have opened a Visio drawing that is published as a .vdw file in the Web Part.

Sys.Application.add_load(onApplicationLoad)

var webPartElementID = "WebPartWPQ3";
var vwaControl;

function onApplicationLoad() {
        try{
                vwaControl= new Vwa.VwaControl(webPartElementID)
                vwaControl.addHandler("diagramcomplete", onDiagramComplete);
        }
        catch(err){
        }
}

When you get a reference to an instance of the VwaControl object, you can use its openDiagram method to open a new diagram, based on a published Visio .vdw file, in the Visio Web Access Web Part. However, after you call the openDiagram method, you cannot subsequently address the same instance of the VwaControl or any other object in the Vwa namespace. That is because the openDiagram method is an asynchronous operation, which opens the diagram on the server and then returns immediately. In addition, the asynchronous operation also makes the current VwaControl object invalid. For information, see Vwa.VwaControl.openDiagram Method.

The best way to follow up on a call to openDiagram is to create a handler for the Vwa.diagramcomplete Event, which occurs when the Visio Web Access Web Part has finished loading the Visio diagram, and to put your code in that event handler. You can use the Vwa.VwaControl.addHandler Method to add an event handler for the diagramcomplete event. Best practice is to program the VwaControl object by writing these event handlers to respond to events raised by user actions in the control. Other events exposed by the VwaControl object include Vwa.shapemouseenter Event, Vwa.shapemouseleave Event, and Vwa.shapeselectionchanged Event, which enable you to respond to user mouse actions; and the Vwa.diagramerror Event, which enables you to respond to errors that SharePoint Server 2010 returns.

In the handler for the diagramcomplete event, you can get references to the other objects exposed by the API, including the Page object and Shape object, and the ShapeCollection collection. In the same handler, you can also create handlers for other events, as shown in the following code example.

function onDiagramComplete() {
        try {
                vwaPage = vwaControl.getActivePage();
                vwaShapes = vwaPage.getShapes();
                vwaShape = vwaShapes.getItemAtIndex(0);
                vwaControl.addHandler("shapeselectionchanged", onShapeSelectionChanged);
        }
        catch(err) {
        }
}

This code example shows how to accomplish the following programming tasks:

How to use the Vwa.VwaControl.getActivePage Method to get a reference to an instance of the Page object that represents the active page.
How to use the Vwa.Page.getShapes Method of the Page object to get an instance of the ShapeCollection collection that represents the collection of shapes on the active page.
How to use the Vwa.ShapeCollection.getItemAtIndex Method of that collection to get an instance of the first shape in the collection of shapes on the active page.
How to add a handler for the shapeselectionchanged event.

To get more information about the drawing that is displayed in the Web Part, you can use several methods of the VwaControl object. For example, you can use the Vwa.VwaControl.getAllPageIds Method to get the names of all the pages contained in the diagram. You can use the Vwa.VwaControl.getDiagramUrl Method to get the URL of the diagram that is currently displayed in the Web Part, and the Vwa.VwaControl.getDisplayMode Method to determine whether the current Web drawing page is displayed by using raster technology or Microsoft Silverlight technology. You can also use the Vwa.VwaControl.getVersion Method to get the version of the Web Part.

The Vwa.VwaControl.removeHandler Method lets you remove an event handler you added, and the Vwa.VwaControl.clearHandlers Method removes all handlers. To display and hide custom HTML error message pages, use the Vwa.VwaControl.displayCustomMessage Method and Vwa.VwaControl.hideCustomMessage Method. You can also use the Vwa.VwaControl.setActivePage Method to change the page that is currently displayed in the Web Part, and the Vwa.VwaControl.refreshDiagram Method to refresh the current Web drawing page with data from the server.

Page Object

The Page object represents the active Web drawing page that is currently displayed in the rendering area of the Visio Web Access Web Part. You can use the methods of the Page object to select shapes on the page and to access information about shapes, including the ID of a shape, the position of the shape, and the size of the bounding box around the shape. You can also get and set the zoom level and the position of the page in the view.

Methods of the Page object include the following:

In addition to the getShapes method shown in the previous code example, the Vwa.Page.getSelectedShape Method, Vwa.Page.setSelectedShape Method, Vwa.Page.centerViewOnShape Method, and Vwa.Page.isShapeInView Method enable you access information about or interact with shapes on the page.
The Vwa.Page.getZoom Method enables you to get the zoom level of the page, and the Vwa.Page.setZoom Method enables you to set the zoom level of the page.
The Vwa.Page.getPosition Method enables you to get the position of the page in the view, and the Vwa.Page.setPosition Method enables you to set the position of the page in the view.
The Vwa.Page.getId Method gets the ID of the currently displayed page, and the Vwa.Page.getSize Method gets the height and width of the rendered page.

ShapeCollection object

The ShapeCollection object represents the collection of shape objects on the active page in the Web drawing that is currently displayed in the rendering area of the Visio Web Access Web Part.

Methods of the ShapeCollection object include the following:

The Vwa.ShapeCollection.getCount Method, which returns the number of shapes on the active page.
Four methods that enable you to get specific shapes in the collection by their Visio shape names (Vwa.ShapeCollection.getItemByName Method), their Web drawing shape IDs (Vwa.ShapeCollection.getItemById Method), their Visio unique IDs (Vwa.ShapeCollection.getItemByGuid Method), and their index position in the collection (Vwa.ShapeCollection.getItemAtIndex Method).

Shape Object

The Shape object represents a single shape on the active Web drawing page. Methods of the Shape object enable you get information about and interact with a specific shape on the active page:

Methods that provide shape information include the Vwa.Shape.getName Method, which returns the name of the shape in Visio; the Vwa.Shape.getId Method, which returns the ID of the shape within the Web drawing; the Vwa.Shape.getGuid Method, which returns the GUID of the shape in Visio; the Vwa.Shape.getHyperlinks Method, which returns an array of any hyperlinks associated with the shape; the Vwa.Shape.getBounds Method, which returns the position, height, and width of the bounding box of the shape; and the Vwa.Shape.getShapeData Method, which returns an array of any shape data items associated with the shape.
Methods that enable you to interact with a shape include the Vwa.Shape.addHighlight Method and Vwa.Shape.removeHighlight Method, which enable you to add and remove highlights associated with the shape; and the Vwa.Shape.addOverlay Method, Vwa.Shape.addPredefinedOverlay Method, and Vwa.Shape.removeOverlay Method, which enable you to add and remove visual shape overlays.

Samples in the SharePoint 2010 SDK

The SharePoint 2010 SDK download file (SharePoint 2010 Reference: Software Development Kit) provides three sample JavaScript files that show best practices for programming the Visio Web Access Web Part, and that you can use on your own Web Parts pages. Each sample has a corresponding topic in the SDK that explains how to use the sample, and the code in each sample file includes extensive explanatory comments. To download the SharePoint 2010 SDK, including these samples, see SharePoint 2010 Reference: Software Development Kit. After you install the SDK, you can find the samples in a compressed (.zip) file in the following path: C:\Program Files (x86)\Microsoft SDKs\SharePoint Server 2010\Samples\Visio Services.

Annotations Sample

The Annotations sample shows how to annotate a Web drawing page in two ways: by using shape overlays and by using shape highlights. In a Content Editor Web Part, the sample code adds four list controls that enable users to choose drawing parameters for the annotations. It also adds a button that enables users to submit their choices and draw the annotation.

Custom Error Messages Sample

The Custom Error Messages sample shows how to use the Visio Web Access Web Part to display or hide custom HTML error messages. It creates a user interface for the code sample that consists of two text boxes that are used to capture the error message title and body, and two buttons to show or hide the error message.

Mouse Interaction Sample

The Mouse Interaction sample shows how to declare event handlers for the various Visio Web Access mouse-related events, and how to handle these events when they occur. It displays notifications of mouse actions that occur in a Content Editor Web Part, such as entering a shape, leaving a shape, or changing the selected shape.

Condividi tramite