This tutorial will show you how to use the Dashboard Management API from widgets and operators by providing some examples of what can be done by using it.

Widgets and operators using the Dashboard Management API will be able to add new widgets/operators to the current dashboards. Widget and operators using the Dasbhaord Management API will have full control over the created widgets and operators. For example, they will be able to configure the wiring connections, close them, assigning custom values to their preferences, etc.

You can find the reference documentation of the Dashboard Management API on the WidgetAPI documentation (Search DashboardManagement to discover the relevant documentation sections).

The first step for being able to use the Dashboard Management API is to add the DashboardManagement feature as a requirement of the widget/operator.

For example, if you use the xml version of the MACDL this is done by adding the following code inside the <widget> or <operator> element (depending if you are adding this feature into a widget or an operator):

<requirements>
    <feature name="DashboardManagement"/>
</requirements>

Introduction

This example will show you how to use the Kurento one2one widget for providing videoconferece support into a thrid party widget.

The steps for adding that functionallity are:

1. Enable the Dasbhoard Management API (as shown in the previous section)
2. Add the Kurento One2one widget into the current dashboard
3. Create some dynamic endpoints on the thrid party widget/operator
4. Connect those endpoints with the ones provided by the Kurento One2one widget
5. Wait until the Kurento One2one connects with the kurento service
6. Start the videoconference by sending a call event to the Kurento One2one widget

Adding the one2one widget

You can add the Kurento One2one widget to the current dashboard using the addWidget method. For example, using the following code:

var widget = MashupPlatform.mashup.addWidget('CoNWeT/kuernto-one2one/1.0', {
    "permissions": {
        "close": false,
        "configure": false
    },
    "preferences": {
        "stand-alone": {
            "value": false
        }
    },
    "top": "0px",
    "left": "66%"
});

Adding the one2one widget

The previous code will add the Kurento One2one widget placed it at an static position: 0px, 66%. Also, we are using the permissions option to block users to configure and close the Kurento One2one widget. By using the preferences options, we are configuring it in non-standalone mode.

If you are adding the videoconference support into a widget, probably you are creating the videoconference because the user has clicked some button. A better alternative to to use the top and left options, in this case, is to use the refposition option. This way, the Kurento One2one widget will be placed near the button the user has clicked.

Adding the one2one widget

To use the refposition option, you have to obtain a ClientRect instance representing your button, you can obtain such an object by using the getBoundingClientRect method:

var one2one_widget = MashupPlatform.mashup.addWidget('CoNWeT/kuernto-one2one/1.0', {
    "permissions": {
        "close": false,
        "configure": false
    },
    "preferences": {
        "stand-alone": {
            "value": false
        }
    },
    "refposition": button.getBoundingClientRect()
});

Wiring configuration

We can make use the enpoints defined in the widget/operator description (config.xml file) for connecting with the Kurento One2one widget, so it's not mandatory to create new endpoints in a dynamic way. However, by creating them using the Dashboard Management API we are declaring that they are going to be used exclusively from the widget/operator code: Users won't be able to create connections using those endpoint in the Wiring Editor view.

Wiring configuration

The needed endpoints can be created using this code:

var call_endpoint = MashupPlatform.widget.createOutputEndpoint();
var state_endpoint = MashupPlatform.widget.createInputEndpoint(function (state) {
    if (state === 'REGISTERED') {
        // Update the call button that tiggered the videoconference to become a
        // hang button. This button should call one2one_widget.remove() to end
        // the videoconference

        // By sending this event, the one2one widget will start the videoconferece
        call_endpoint.pushEvent(information.username);
    } else if (state === 'ENABLED_CALL') {
        one2one_widget.remove();
    }
});

Note: If you are developing an operator you should use MashupPlatform.operator.createOutputEndpoint and MashupPlatform.operator.createInputEndpoint instead.

Wiring configuration

The connection between those dynamic endpoint and the endpoints of the Kurento One2one widget can be established using the following code:

call_endpoint.connect(one2one_widget.inputs['call-user']);
one2one_widget.outputs['call-state'].connect(state_endpoint);

Introduction

This example will show you how to use the Map viewer widget for displaying some Point of Interest in a map in a dynamic way (without displaying a map viewer widget all the time).

The main difference with the previous example is that in this case, we are going to use a NGSI Entity 2 PoI operator for transforming the event data to be compatible with the one expected by the Map Viewer widget.

Adding the Map viewer widget

This step can be accomplished in the same way as we did with the Kurento One2one widget:

var map_widget = MashupPlatform.mashup.addWidget('CoNWeT/map-viewer/2.5.7', {
    "permissions": {
        "close": false,
        "configure": false
    },
    "preferences": {
        "stand-alone": {
            "value": false
        }
    },
    "top": "0px",
    "left": "66%"
});

Remember to use refposition in replacement of the top and left options if applicable.

Adding the NGSI entity to PoI operator

The addOperator method works in a very similar way to the addWidget operator. E.g. for adding the NGSI Entity 2 PoI operator, we can make use of the following code:

var operator = MashupPlatform.mashup.addOperator('CoNWeT/ngsientity2poi/3.0.3', {
    "preferences": {
        "coordinates_attr": {
            "value": "position"
        }
    }
});

Note: Rembember to change the coordinates_attr value according to your requirements.

Wiring configuration

var poi_endpoint = MashupPlatform.widget.wiring.createOutputEndpoint();

poi_endpoint.connect(operator.inputs['entityInput']);
operator.outputs['poiOutput'].connect(map_widget.inputs['poiInput']);

Now you can send events using poi_endpoint. E.g.:

poi_endpoint.pushEvent(JSON.stringify({
    "id": "Big Ben",
    "position": "51.5008715, -0.1259872"
});