Lab4 Glue API Web Intro JS

(This is a continuation from the previous post: Lab3 “Glue API Web Intro”)

The last piece of API functionality that we want to add to our Intro Labs app is an ability to select an element in the viewer and to obtain its property. To do this, Glue API provides a thin layer of JavaScript API. It is written on top of jQuery library, which is very popular public JavaScript library and greatly simplifies querying of document parts or accessing web document objects.

JavaScript API Layer

If you look at the accompanying sample project for Lab4, you see three JavaScript (.js) files under Scripts folder:

  • jquery-1.11.0.min.js
  • glue-embedded.js
  • viewer.js

The image below shows how it looks within the visual studio:

2015_0120_Lab4GlueApiWebIntroJS

Let’s take a look at them one by one.

jquery-xxx.min.js

This is the jQuery library that we have just mentioned above. The number in the name “-xxx” indicates the version of jQuery (in our case -1.11.0). You can download the latest jQuery from jquery.com. The file is included in the accompanying sample, too.

To use it with our application, we include it in HTML tag. e.g.,
http://Scripts/jquery-1.11.0.min.js
</head>

(Note: in our exercise, we placed all the javascript files under Scripts folder.)

Alternatively, you can include it from a hosted location, such as ones by Google and Microsoft.e.g.,

http://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js

http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.11.0.min.js

glue-embedded.js

glue-embedded.js contains the most important piece of code to implement element selection and property data access features in Glue API. The file is included in the sample project. For the sake of completeness and a quick view, I also put it here: Glue-embedded.js  We can include this file as a library to your HTML page, e.g.,  

GlueEmbedded

glue-embedded.js contains GlueEmbedded object that defines a set of member functions including:

  • init(iframe)
  • setSelection(objectPaths)
  • getProperties(objectPath)
  • getSelectedProperties()
  • zoomSelection()

init(iframe) sets the target iframe window for the viewer and initializes the viewer event handlers. You need to call this before you use the embedded viewer. setSelection(objectPaths) sets the selected objects in the viewer to the specified objectPaths. getProperties(objectPath) sends a request to the viewer to retrieve the properties of the specified object. getSelectedProperties() sends a request to the viewer to retrieve the properties of the currently selected object. zoomSelection() triggers the viewer to zoom in on the current selected objects.

When these functions are called, a message is posted to the viewer, and the viewer responses accordingly. In case of getProperties() and getSelectedProperties(), the viewer trigger an event ‘gotproperties’ with the property data of the specified object, which we will need to catch to further process.

Event Triggered by the Viewer

There are two message events triggered by the viewer:

  • ‘selectionchanged’
  • ‘gotproperties’

‘selectionchanged’ is triggered when the user selects an element in the model on the viewer. ‘gotproperties’ is triggered when the application called getProperties() and getSelectedProperties() as mentioned above.

Using GlueEmbedded functions to post message to the viewer and document event handlers on your web page to catch the event from the viewer, you can interface between your web page and the embedded viewer. The following diagram illustrates flow of the messages.

2015_0120_Lab4GlueApiWebIntroJS_Diagram.png

view.js 

Now, time for our coding. In our exercise, we use the following four methods to select an element, get properties, and zoom:

  • $(document).on(‘selectionchanges’, function(e))
  • $(document).on(‘gotproperties’, function(e))
  • GlueEmbedded.getSelectedProperties()
  • GlueEmbedded.zoomSelection()

The first two using $(document).on( message, function(e) {}) are event handlers.

Below is the JavaScript code for user interaction portion. Here we set id for a text area to display messages as “messages” in the web page, and “Get Properties”, and “Zoom Selection” buttons as “get_properties” and “zoom_selection” respectively.

view.js

//==============================================================
// Welcome to the Glue API intro.  
// This is a minimum sample that demonstrates Glue viewer API.
//==============================================================

$(document).ready(function () {

    // initialize the embedded viewer passing in the target iframe window
    GlueEmbedded.init(window.frames[0]);

    // ———————————————————
    // Setting event handlers to get a messages from the viewer.
    // ———————————————————
    // an event handler on the document for the “selectionchanged” from the viewer.
    // The eventData property will be set to the array of selected objects
    $(document).on(‘selectionchanged’, function (e) {
        $(“#messages”).val(“object selected: “ + JSON.stringify(e.eventData));
    });

    // an event handler on the document for the “gotproperties” event from the viewer.  
    // The eventData property will be set to the collection of object properties
    $(document).on(‘gotproperties’, function (e) {
        $(“#messages”).val(“got properties: “ + JSON.stringify(e.eventData));
    });

    // ———————————
    // Posting a message to the viewer.
    //———————————-
    // When the user click get_properties button, this is called.
    $(‘#get_properties’).on(‘click’, function () {
        GlueEmbedded.getSelectedProperties();
    });

    // This is for zooming in a currently selected element.
    $(‘#zoom_selection’).on(‘click’, function () {
        GlueEmbedded.zoomSelection();
    });

});

The above code is executed when a web page is all loaded. It first initializes the GlueEmbedded, passing the iframe. We then set two event handlers to receive message from the embedded viewer: ‘selectionchanged’ and ‘gotproperties’. Two buttons whose ids we named as ‘get_properties’ and ‘zoom_selection’ are set to post messages to the viewer on the user’s click event.

Putting Together 

In the head section of your web page, include script files we have discussed above, for example, like the following to reflect this additional features:

http://Scripts/jquery-1.11.0.min.js
http://Scripts/glue-embedded.js
http://Scripts/viewer.js

Add two buttons on your web page, for example:

<button type=”button” id=”get_properties”>Get Properties</button>
<button type=”button” id=”zoom_selection”>Zoom Selection</button>

An example of final web page will looks like this:

2015_0106_GlueApiIntroLabsOverview

You can download the full code project for the Glue API Intro Labs from here.

This concludes the tour of our Glue API Intro Labs (at least for now). I hope you will find this helpful to jump start with Glue API.

Mikako

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s