Visio JavaScript APIs reference

You can use the Visio JavaScript APIs to embed Visio diagrams in SharePoint Online. An embedded Visio diagram is a diagram that is stored in a SharePoint document library and displayed on a SharePoint page. To embed a Visio diagram, display it in an HTML <iframe> element. Then you can use Visio JavaScript APIs to programmatically work with the embedded diagram.

Visio diagram in iframe on SharePoint page along with script editor web part

You can use the Visio JavaScript APIs to:

  • Interact with Visio diagram elements like pages and shapes
  • Create visual markup on the Visio diagram canvas
  • Write custom handlers for mouse events within the drawing
  • Expose diagram data, such as shape text, shape data, and hyperlinks, to your solution.

This article describes how to use the Visio JavaScript APIs with Visio Online to build your solutions for SharePoint Online. It introduces key concepts that are fundamental to using the APIs, such as EmbeddedSession, RequestContext, and JavaScript proxy objects, and the sync(), Visio.run(), and load() methods. The code examples show you how to apply these concepts.

EmbeddedSession

The EmbeddedSession object initializes communication between the developer frame and the Visio Online frame.

       var session = new OfficeExtension.EmbeddedSession(url, { id: "embed-iframe",container: document.getElementById("iframeHost") });
       session.init().then(function () {     
               window.console.log("Session successfully initialized");
       });

Visio.run(session, function(context) { batch })

Visio.run() executes a batch script that performs actions on the Visio object model. The batch commands include definitions of local JavaScript proxy objects and sync() methods that synchronize the state between local and Visio objects and promise resolution. The advantage of batching requests in Visio.run() is that when the promise is resolved, any tracked page objects that were allocated during the execution will be automatically released. The run method takes in sesison and RequestContext object and returns a promise (typically, just the result of context.sync()). It is possible to run the batch operation outside of the Visio.run(). However, in such a scenario, any page object references needs to be manually tracked and managed.

RequestContext

The RequestContext object facilitates requests to the Visio application. Because the developer frame and the Visio Online application run in two different iframes, the RequestContext object (context in below example) is required to get access to Visio and related objects such as pages and shapes, from the developer frame.

    function hideToolbars()
    {
    Visio.run(session, function(context){
            var app = context.document.application;
            app.showToolbars = false;            
            return context.sync().then(function ()
            {
                window.console.log("Toolbars Hidden");
            });      
         }).catch(function(error)
        {
            window.console.log("Error: " + error);            
        });
    };

Proxy objects

The Visio JavaScript objects declared and used in an add-in are proxy objects for the real objects in a Visio document. All actions taken on proxy objects are not realized in Visio, and the state of the Visio document is not realized in the proxy objects until the document state has been synchronized. The document state is synchronized when context.sync() is run.

For example, the local JavaScript object getActivePage is declared to reference the selected page. This can be used to queue the setting of its properties and invoking methods. The actions on such objects are not realized until the sync() method is run.

var activePage = context.document.getActivePage();

sync()

The sync() method synchronizes the state between JavaScript proxy objects and real objects in Visio by executing instructions queued on the context and retrieving properties of loaded Office objects for use in your code. This method returns a promise, which is resolved when synchronization is complete.

load()

The load() method is used to fill in the proxy objects created in the add-in JavaScript layer. When trying to retrieve an object such as a document, a local proxy object is created first in the JavaScript layer. Such an object can be used to queue the setting of its properties and invoking methods. However, for reading object properties or relations, the load() and sync() methods need to be invoked first. The load() method takes in the properties and relations that need to be loaded when the sync() method is called.

The following shows the syntax for the load() method.

object.load(string: properties); //or object.load(array: properties); //or object.load({loadOption});
  1. properties is the list of properties and/or relationship names to be loaded, specified as comma-delimited strings or array of names. See .load() methods under each object for details.
  2. loadOption specifies an object that describes the selection, expansion, top, and skip options. See object load options for details.

Example: Printing all shapes text in active page

The following example shows you how to print shape text value from an array shapes object. The Visio.run() method contains a batch of instructions. As part of this batch, a proxy object is created that references shapes on the active document. All these commands are queued and run when context.sync() is called. The sync() method returns a promise that can be used to chain it with other operations.

Visio.run(session, function (context) {
   var page = context.document.getActivePage();
   var shapes = page.shapes;
   shapes.load();
   return context.sync().then(function () {
        for(var i=0; i<shapes.items.length;i++)
 {
            var shape = shapes.items[i];
     window.console.log("Shape Text: " + shape.text );
 }
});
}).catch(function(error) {
  window.console.log("Error: " + error);
  if (error instanceof OfficeExtension.Error) {
       window.console.log ("Debug info: " + JSON.stringify(error.debugInfo));
  }
});

Error messages

Errors are returned using an error object that consists of a code and a message. The following table provides a list of possible error conditions that can occur.

error.code error.message
InvalidArgument The argument is invalid or missing or has an incorrect format.
GeneralException There was an internal error while processing the request.
NotImplemented The requested feature isn't implemented.
UnsupportedOperation The operation being attempted is not supported.
AccessDenied You cannot perform the requested operation.
ItemNotFound The requested resource doesn't exist.

Get started

You can use the example in this section to get started. This example shows you how to programmatically display the shape text of the selected shape in a Visio diagram. To begin, create a classic page in SharePoint Online or edit an existing page. Add a script editor webpart on the page and copy-paste the following code.

<script src='https://appsforoffice.microsoft.com/embedded/1.0/visio-web-embedded.js' type='text/javascript'></script>

Enter Visio File Url:<br/>
<script language="javascript">
document.write("<input type='text' id='fileUrl' size='120'/>");
document.write("<input type='button' value='InitEmbeddedFrame' onclick='initEmbeddedFrame()' />");
document.write("<br />");
document.write("<input type='button' value='SelectedShapeText' onclick='getSelectedShapeText()' />");
document.write("<textarea id='ResultOutput' style='width:350px;height:60px'> </textarea>");
document.write("<div id='iframeHost' />");

let session; // Global variable to store the session and pass it afterwards in Visio.run()
var textArea;
// Loads the Visio application and Initializes communication between devloper frame and Visio online frame
function initEmbeddedFrame() {
        textArea = document.getElementById('ResultOutput');
    var url = document.getElementById('fileUrl').value;
    if (!url) {
        window.alert("File URL should not be empty");
    }
    // APIs are enabled for EmbedView action only.   
    url = url.replace("action=view","action=embedview");
    url = url.replace("action=interactivepreview","action=embedview");
    url = url.replace("action=default","action=embedview");
    url = url.replace("action=edit","action=embedview");
  
       session = new OfficeExtension.EmbeddedSession(url, { id: "embed-iframe",container: document.getElementById("iframeHost") });
       return session.init().then(function () {
        // Initilization is successful 
        textArea.value  = "Initilization is successful";
    });
     }

// Code for getting selected Shape Text using the shapes collection object
function getSelectedShapeText() {
    Visio.run(session, function (context) {     
       var page = context.document.getActivePage();
       var shapes = page.shapes;
       shapes.load();
           return context.sync().then(function () {
               textArea.value = "Please select a Shape in the Diagram";
               for(var i=0; i<shapes.items.length;i++)
            {
              var shape = shapes.items[i];
                  if ( shape.select == true)
               {
                textArea.value = shape.text;
                    return;
                   }
            }
      });
     }).catch(function(error) {
        textArea.value = "Error: ";
        if (error instanceof OfficeExtension.Error) {
            textArea.value += "Debug info: " + JSON.stringify(error.debugInfo);
        }
    });
}
</script>

After that, all you need is the URL of a Visio diagram that you want to work with. Just upload the Visio diagram to SharePoint Online and open it in Visio Online. From there, open the Embed dialog and use the Embed URL in the above example.

Copy Visio file URL from Embed dialog If you are using Visio Online in Edit mode, open the Embed dialog by clicking on File > Share > Embed. If you are using Visio Online in View mode, open the Embed dialog by clicking on '...' and then 'Embed'.

Open API specifications

As we design and develop new APIs, we'll make them available for your feedback on our Open API specifications page. Find out what new features are in the pipeline, and provide your input on our design specifications.