Widgets for services

A service widget is a web application shown in an iframe as a replacement for a generic service instance UI. Service widgets are stored on a customer-controlled web server, along with a JavaScript file in the following format:

  'builtin:static_resource_pool' : 'http://example.com/widgets/resource-pool/index.html',
  'builtin:static_example' : 'http://example.com/widgets/example/',

The left side of the mapping is service type ids; the right side is corresponding widget URLs.

Developing Widgets

Widgets are standalone applications that can rely on any external libraries; however, there are several callbacks you must implement to interact with the platform. The following script references the widget page:

<script type="text/javascript" src="http://...tonomi.com/assets/widgets/widgetapi-0.2.0.js"></script>

WidgetAPI object

Public functions  
WidgetAPI(options = {})

The constructor. The options object has two properties that configure logging destinations

The log property can take following values:

  • none — no logging
  • console (default) — browser console

The warning property:

  • console — browser console
  • alert (default) — modal alert


var widgetAPI = new WidgetAPI({ log: 'none', warning: 'console' });
send(action, data?, callback?)

Sends the action event to the platfrom web site.

data — any data

callback — a function that will be called once the platfrom responds to the action. Callback can accept one parameter: response from the action (f.e. true for “setModel” action or object for “getModel”)

Available action types:

getModel — returns the object representing the current model. For example:

  configuration.resources: "yaml-configuration"
  id: "…"
  interfaces: ["Resource pool"]
  internalId: "…"
  name: "Resource Pool"
  organizationId: "…"
  parameters: {  }
  status: {  }
  typeId: "builtin:static_resource_pool"
  typeName: "Resource Pool"
  zoneId: "…"
  zoneName: "Qubell/us-east"

setModel — sets data as the new model and refreshes the widget frame.

error — Ask web site to render an error.


widgetAPI.error('Error message');
widgetAPI.send('setModel', { name: 'New name' });
widgetAPI.send('getModel', null, function(model) {
  // Do something with 'model'
error(msg) Shortcut for send(‘error’, msg) method
Public variables  

The parent application will call this once the Save button is clicked. The function has to return current configuration.

widgetAPI.onGetModel = function() {
  return { 'configuration' : editor.getValue() };

Example: A different resource pool widget.

The example below depicts a simple resource pool widget with a slight improvement over the generic screen: a configuration editor with syntax highlighting.


Let’s first update the widgets configuration. We assume that the configuration URL has been previously passed to the portal support team and the portal knows where to look for it.

  'builtin:static_resource_pool' : 'http://localhost/widget-example/index.html'

Example of index.html:

<!DOCTYPE html>

  <title>Resource pool example</title>
  <meta http-equiv="content-type" content="text/html; charset=utf-8">

  <script type="text/javascript" src="https://...tonomi.com/assets/widgets/widgetapi-0.2.0.js"></script>
  <script type="text/javascript" src="/ace/ace.js"></script>
  <script type="text/javascript" src="widget-example.js"></script>

  <style type="text/css">
    html, body, #editor { margin: 0; padding: 0; overflow: hidden; height: 100%; }

<body onload="init()">

  <div id="editor"></div>


The /ace/ folder must contain the unpacked source code for the ACE editor: http://ace.c9.io/.

The widget-example.js file looks like this:

function init() {

  // Initializing editor
  var editor = ace.edit("editor");

  // Initializing app
  var widgetAPI = new WidgetAPI();
  var model = null;

  widgetAPI.onGetModel = function() {
    model['configuration.resources'] = editor.getValue();
    return model;

  widgetAPI.send('getModel', null, function(m) {
    model = m;