Embedding the Widget

Use VideoWidget.js

In many cases, the easiest way to embed the widget is to use the wrapper VideoWidget.js, which takes care of dynamically creating and attaching an iframe element to a DOM node that you specify. There are performance benefits from this approach, since it defers the loading and initialization logic until you absolutely need it.

To make use of it, copy it into your web project, and in the source of your containing web page:

1. Add a DOM container with id="videowidget" (or customize your own in VideoWidget.js)

    <!-- The <iframe> will be inserted in this tag -->
    <div id="videowidget"></div>
   

2. Set a global videowidgetParams object (or customize your own in VideoWidget.js)

    window.videowidgetParams = {
   
        // a valid call link
        callUrl: callUrl,
   
        // Event will be 'CALLSTARTED' or 'CALLENDED'
        onEvent: function (e) { ... }
    };
   

3. Attach VideoWidget as a script element as needed via Javascript.

    var script, parentElem;
   
    // create a script element for VideoWidget.js
    script = document.createElement('script');
    script.type = 'text/javascript';
    script.async = true;
    script.src = "js/VideoWidget.js";
   
    // attach to DOM to trigger
    parentElem = (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]);
    parentElem.appendChild(script);
   

Live Demo

To see use of this wrapper in action, a live demo is available below. You can see how VideoWidget.js is used to dynamically recreate the iframe in the #videowidget DOM element for each valid call link.

Important: as this demo uses a host with a self-signed SSL certificate, please click through https://jabberc-dev.cisco.com and accept the security warning in your browser first before opening the demo.

↱ Open the demo.

Or roll your own

The VideoWidget.js is a fully-functional sample that can be dropped into an existing codebase with minimal changes required. However, for those that prefer to roll their own solution, here are the basic details of how to do that.

Use an iframe

To embed the widget, use an iframe element whose src is a valid call link, but with the additional parameter of widget=true in the querystring.

For example, a valid call link this:

  https://www.example.com/call/webmaster

...would become this:

  https://www.example.com/call/webmaster?widget=true

And so, the HTML of a page embedding the widget might look like this:

  <div id="widget-container">
      <iframe id="my-widget" src="https://www.example.com/call/webmaster?widget=true" />
  </div>

Again, it is advisable to mention that as this widget is meant to be used for dynamic calling, it is likely that you will only want to attach the iframe element to the DOM only as needed via Javascript.

Querystring parameters

Name	Value	Required
widget	true	Y
uselang	ex. en, fr, zh, en-US, ...	N (defaults to browser language setting)

Javascript Events

There are only two events emitted by the iframe once it has been initialized:

Event Name	Description
CALLSTARTED	Fired when the 'Call' button is clicked.
CALLENDED	Fired when an established call has ended, or a server error has occurred.

These events can be handled by listening to the message event in the containing page. For example:

// simple handler
var myHandler = function (e) {
    console.log('e.event: ', e.event);
    console.log('e.data: ', e.data);
}

// listen for the 'message' event
if (window.attachEvent) {
    window.attachEvent('onmessage', myHandler);
} else {
    window.addEventListener('message', myHandler, false);
}

Cleaning up

To tear down the widget, simply remove it from the DOM:

var elem = document.getElementById('my-widget');
if (elem) {
    elem.parentNode.removeChild(elem);
}