Displaying Custom HTML Messages in Visio Services in SharePoint Server 2010

Article
07/24/2014

Office Visual How To

Summary: Learn how to display custom HTML content 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 display customized HTML messages within 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 Custom Error Messages in the SharePoint 2010 SDK) you can create HTML instructions that can be displayed or hidden by the user.

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 displays or hides custom HTML text in the Web Part when the user clicks a button. 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

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

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 the code sample that is shown in this Visual How To, 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 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 begin 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 a name 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 button that displays or hides the custom HTML instructions.

// Use the document.write method to write HTML to the Content Editor Web Part.
document.write('<br><input type="button" id="instructions"' +
    'value="Show instructions" style="width:200px" ' +
    'onclick="toggleInstructions();">');

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

// Declare variables for the Visio Web Access Web Part, the currently 
// displayed page, and the current status of the HTML instructions.
var vwaControl;
var vwaPage;
var instructionsDisplayed;

Use the following code to add a handler to 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 "VisioWebAccess", 
        // 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 shown page in the diagram. The global variable, instructionsDisplayed, is set to false to indicate that the instructions are hidden.

// Assign values to the global variables when the drawing finishes rendering.
function onDiagramComplete() {
    try {
        vwaPage = vwaControl.getActivePage();
        vwaPage.setZoom(-1);
        instructionsDisplayed = false;
    }
    catch(err){
    }
}

Use the following code to display or hide a custom HTML message in the Visio Web Access Web Part.

// Display or hide the custom HTML message over the Visio Web Access Web Part.
function toggleInstructions()
{
    // Check the state of the instructions.
    if (instructionsDisplayed) {

        // If the instructions are displayed, hide them and change the state variable.
        vwaControl.hideCustomMessage();
        instructionsDisplayed = false;
        document.getElementById("instructions").value = "Show instructions";
    }
    else {
        // The instructions are hidden, so display them and change the state variable.
        vwaControl.displayCustomMessage(
            "<h1> Instructions for using this Web Part: </h1>"
            /* Insert your instructions here. */);
        instructionsDisplayed = true;
        document.getElementById("instructions").value = "Hide instructions";
    }
}

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 need 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 display and share diagrams and data on a SharePoint 2010 site. You can customize how these diagrams are displayed on the SharePoint Web Parts page. The JavaScript object model for Visio Services includes methods that allow you to display your own HTML content within the Visio Web Access Web Part.

Writing Content in a Content Editor Web Part

The code sample that is shown in this Visual How To creates an HTML button for showing or hiding the viewing instructions for the Visio Web Access Web Part. To do this, the sample uses the document.write method of the Content Editor Web Part to create an <input> HTML input with the attribute type="button". (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.) When the onclick event of the button is raised, the code sample calls the toggleInstructions function that displays or hides the custom HTML message.

Although the input button is not necessary for displaying or hiding a custom HTML message in the Visio Web Access Web Part, 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 need 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 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 a couple of 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 initializes most of the global variables and sets the zoom for the currently displayed page in the drawing.

The function creates instances of the Vwa.Page class and captures a reference to the page in the vwaPage variable. It also sets the initial value of the instructionsDisplayed variable to indicate that the instructions are not displayed when the drawing first renders.

Although this code sample leaves the custom HTML message hidden when the drawing finishes rendering, you could add code to this onDiagramComplete function so that the custom HTML message is displayed when the drawing finishes rendering in the browser. To do this, you would need to call the VwaControl.displayCustomMessage method of the vwaControl object within the handler function for the Vwa.diagramcomplete event. The VwaControl.displayCustomMessage method is discussed in the next section.

Displaying Custom HTML Messages in the Visio Web Access Web Part

In the code sample, clicking the HTML button in the Content Editor Web Part calls the toggleInstructions function, which either displays or hides the instructions depending on their current state.

The function first determines whether the custom HTML message is being displayed by checking the value of the instructionsDisplayed variable. If the message is displayed, the function calls the VwaControl.hideCustomMessage method to dismiss the custom HTML message. The function then changes the value of the instructionsDisplayed variable to false and changes the text shown on the button in the Content Editor Web Part.

If the custom HTML is not currently displayed (that is, the instructionsDisplayed variable is set to false), the toggleInstructions function calls the VwaControl.displayCustomMessage method to write and display the HTML message. The VwaControl.displayCustomMessage method has one required parameter, HTML, which must be a string that contains the message to be displayed in well-formed HTML. The content can include many different types of HTML elements, including lists, images, or links. After displaying the HTML message, the toggleInstructions function sets the instructionsDisplayed variable to true and changes the text shown on the button in the Content Editor Web Part.

Watch the video

> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/33787c67-c8c2-4ac9-947c-51835976c016]

Length: 00:8:42