Export (0) Print
Expand All
Expand Minimize

Responding to User Mouse Clicks in Visio Services

SharePoint 2010

SharePoint Visual How To

Summary:  Learn how to add event handlers to mouse-click events in a Visio Web Access Web Part on a Microsoft SharePoint Server 2010 Web Parts page by using ECMAScript (JavaScript, JScript) code.

Last modified: September 12, 2012

Applies to: Office 2010 | SharePoint Foundation 2010 | SharePoint Server 2010 | Visio Services | Visual Studio | Visual Studio 2008 | Visual Studio 2010

Provided by:  Eric Schmidt, Microsoft Corporation

Overview

By using the JavaScript object model for Visio Services in Microsoft SharePoint Server 2010, you can generate custom messages when specific events occur in a Visio Web Access Web Part on a SharePoint Server 2010 Web Parts page. By using the following code sample (which is based on the code sample Mouse Interaction in the SharePoint 2010 SDK) you can create a custom debug window on a Web Parts page that displays messages when certain events occur to shapes in the Visio Web Drawing in the browser.

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

Code It

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 responds to in-browser events. 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 must 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

  1. In Visio, create the drawing that you want to display on the SharePoint site.

  2. On the File tab, click Save & Send.

  3. Under Save & Send, click Save to SharePoint.

  4. Under Save to SharePoint, select the Web Drawing (*.vdw) file type, and then click Save As.

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

  1. In the SharePoint site where you want to post your drawing, on the Site Actions menu, click More Options.

  2. Under Filter By, click Page, select Web Part Page, and then click Create.

  3. On the new Web Parts page, in the Name box, type a file name for the page.

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

  1. In the Server ribbon on the SharePoint Server 2010 Web Parts page, click Edit Page.

  2. In the zone where you want to place the Web Part, click Add a Web Part.

  3. In the Categories list, click Business Data.

  4. Click Visio Web Access, and then click Add.

  5. Click the Visio Web Access Web Part Menu arrow, and then click Edit Web Part.

  6. Type the URL of the Web Drawing (.vdw file) that 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

  1. If the page is not already in edit mode, on the Server ribbon on the SharePoint Server 2010 Web Parts page, click Edit Page.

  2. In the zone where you want to place the Content Editor Web Part, click Add a Web Part.

  3. In the Categories list, click Media and Content.

  4. In the Web Parts list, click Content Editor, and then click Add.

  5. Click the Content Editor Web Part Menu arrow, and then click Edit Web Part.

  6. Type the URL of the .js file that you want to open, and then click OK.

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

  1. In Visual Studio 2010, click File, point to New, and then click File.

  2. In the New File dialog box, under Installed Templates, click Web.

  3. In the list of templates, click JScript File, and then click Open.

  4. After the file opens, click File, and then click Save As.

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

  1. Add the following HTML tag to the beginning of the file.

    <script type="text/javascript">
    
    
  2. Use the following code to create a new HTML element in the Content Editor Web Part on the SharePoint page.

    // Create new text area element in the Content Editor Web Part.
    document.write("ECMA events debug window:");
    document.write("<textarea" + 
                   " id='MouseOutput'" + 
                   " style='width:350px;height:200px'>" + 
                   "</textarea>");
    
  3. Use the following code to declare the global variables for the JavaScript code.

    // Declare a variable for the text area HTML element.
    var textArea;   
    
    // Declare variables for the Visio Web Access Web Part, active Visio page,
    // and collection of shapes on the active Visio page, respectively.
    var vwaControl; 
    var vwaPage; 
    var vwaShapes;
    
    
  4. 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)
    
    
    
  5. 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 "VisioWebAccess", 
            // return the id attribute of the grandparent tag.
            if (node.className == "VisioWebAccess") {
                webPartElementID = node.parentNode.parentNode.id;
                break;
            }
        }
        return webPartElementID;
    }
    
    
  6. Use the following code to create the handler for the Vwa.diagramcomplete event. This function initializes the global variables, sets the zoom for the Visio Web Drawing, and adds handlers to the Vwa.shapemouseleave, Vwa.shapemouseenter, and Vwa.shapeselectionchanged events of the Vwa.VwaControl object.

    // Add handlers to the mouse-click events in the Web Drawing when the diagram finishes rendering.
    function onDiagramComplete()
    {
        try{
            // Define the vwaPage and vwaShapes variables for the current session of the Web Drawing.
            vwaPage = vwaControl.getActivePage();
            vwaShapes = vwaPage.getShapes();
    
            // Define the textArea variable as the debugging window HTML element.
            textArea = document.getElementById('MouseOutput');
    
            // Set the page zoom to "Fit page to view."
            vwaPage.setZoom(-1);
    
            // Add handlers to the shapemouseleave, shapemouseenter, and shapeselectionchanged events.
            vwaControl.addHandler("shapemouseleave", onShapeMouseLeave);
            vwaControl.addHandler("shapemouseenter", onShapeMouseEnter);
            vwaControl.addHandler("shapeselectionchanged", onShapeSelectionChanged);
    
            // Output text to the debugging window. 
            textArea.value += 'Drawing loaded from:\n' 
                + vwaControl.getDiagramUrl() + '\n';
    
        }
        catch(err){
        }
    }
    
    
  7. Use the following code to create the handlers for the Vwa.shapemouseleave, Vwa.shapemouseenter, and Vwa.shapeselectionchanged events. When called, each of these functions writes a line of text to the <textarea> HTML element in the Content Editor Web Part. The line of text identifies both the event that was triggered and the shape that triggered the event.

    // When the event is raised, it outputs text to the debugging window.
    onShapeSelectionChanged = function (source, args)
    {
        try{
            // Do not process the shapeselectionchanged event if the selection was cleared.
            if (args != null && args != Sys.EventArgs.Empty)
            {
                textArea.value += 'Selection changed to "' + 
                    vwaShapes.getItemById(args).getName() +'"\n';
                textArea.scrollTop = textArea.scrollHeight;
            }
        }
        catch(err){
        }
    }
    
    // When the event is raised, outputs text to the "debugging window."
    onShapeMouseEnter = function (source, args)
    {
        try{
            textArea.value += 'Mouse entered shape "' + 
                vwaShapes.getItemById(args).getName() + '"\n';
            textArea.scrollTop = textArea.scrollHeight;
        }
        catch(err){
        }
    }
    
    // When event is raised, outputs text to the "debugging window."
    onShapeMouseLeave = function (source, args)
    {
        try{
            textArea.value += 'Mouse exited shape "' + 
                vwaShapes.getItemById(args).getName() + '"\n';
            textArea.scrollTop = textArea.scrollHeight;
            }
        catch(err){
        }
    }
    
    
  8. 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

  1. On the SharePoint page, click the Content Editor Web Part Menu arrow, and then click Edit Web Part.

  2. Type the URL of the.js file that you want to insert, and then click OK.

Read It

Visio Services introduces a new way to share diagrams and data throughout an organization. You can create interactive diagrams, where users can explore the Visio drawing and its underlying data in their browser. The JavaScript object model for Visio Services exposes several mouse-click events in the browser that you can add handlers to.

Displaying the Output for Mouse-Click Events

You can display messages that were generated by events in a Visio Web Access Web Part in a number of ways, depending on the needs of your solution. For example, you could use an alert() window to display a pop-up message or use the Vwa.VwaControl.displayCustomMessage method to replace the Visio Web Access Web Part with a custom HTML message.

The code sample that accompanies this Visual How To creates a debugging window in the Content Editor Web Part for displaying the output of the mouse-click events. To do this, the sample uses the document.write method of the Content Editor Web Part to create a <textarea> HTML element in the Web Part. (Like a <frame> HTML element, the Content Editor Web Part contains a document object that you can use to access the content within the scope of the Web Part itself.) The sample captures a global reference to that <textarea> element when the onDiagramComplete function is called, and the mouse-event handlers can later access that element and write the output that they generate to it (in the debugging window).

Although the debugging window is not necessary for displaying output from mouse events, you must 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 must 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 in this Visual How To 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 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 with 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 adds the handlers to the mouse-click events in the Visio Web Access Web Part and initializes most of the global variables.

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

After defining the global variables, the function registers handlers for three in-browser events of the vwaControl object:

  • The Vwa.shapemouseleave event, which occurs when the mouse leaves the bounding box of a shape. This event has the onShapeMouseLeave handler function added to it.

  • The Vwa.shapemouseenter event, which occurs when the mouse enters the bounding box of the shape. This event has the onShapeMouseEnter handler function added to it.

  • The Vwa.shapeselectionchanged event, which occurs when the active selection in the drawing is changed from one shape to another. This event has the onShapeSelectionChanged handler function added to it.

Creating Handlers for the Vwa.shapeselectionchanged, Vwa.shapemouseenter, and Vwa.shapemouseleave Events

The three functions that handle the in-browser mouse-click events—onShapeSelectionChanged, onShapeMouseEnter, and onShapeMouseLeave—behave very similarly. When the event is raised and the function is called, the event supplies two arguments to the functions: the source of the event (the event object) and an argument (the Visio shape ID of the shape that raised the event). In each case, the function uses the Vwa.ShapeCollection.getItemById method of the vwaShapes object to retrieve the Visio shape (an instance of the Vwa.Shape class) and then gets the name of the shape by calling the Vwa.Shape.getName method. The function then outputs a line of text to the textArea element that includes the name of the shape and the event that was raised.

Unlike the other two functions, the onShapeSelectionChanged function also has to distinguish between when a shape is selected and when the selection is cleared. When a shape in the drawing is selected, either with the mouse or by pressing the Tab key, the event should occur and the handler should output a line of text to the textArea element. However, if a selection is cleared (and, therefore, no shape is selected), the event still occurs, but the function does not output any text to the textArea element.

See It

Watch the video

Watch video

Length: 00:9:58

Explore It
Show:
© 2014 Microsoft