Application Packaging Standard

Last updated 18-Mar-2019

Advanced View-Plugin

In a case you are going to display more data of your application and add more actions on the home dashboard, use the mediator object declared in the home dashboard application and available for the embedded view-plugins. The application view-plugin should define the following mediator methods that the home dashboard will call:

  • The mediator.getWidget() method that the home dashboard calls to get a UI tile with presentation of the application service
  • The mediator.watch() method that is continuously watching for changes in customer resources to present up-to-date information in the UI tile

Both of the above methods are described in this document.

In this document:

Input

On screen refresh, the home dashboard updates the list of resources of all customer subscriptions. The list is available as an associative array mediator.resourceUsage. An element in the array contains resources of a single subscription as returned by the /aps/2/<subscriptionGUID>/resources REST request.

resourceUsage: {"subscription GUID": [
/* Resource usage in the format returned by "GET /aps/2/<subscription GUID>/resources" */
  ],
  "<another subscription GUID>": [...]
}

Due to this source, the embedded view-plugins are able to watch for updates in the resource usage in scope of the current customer.

Data Processing

The init(mediator) method must contain definition of the mediator.getWidget and mediator.watch methods.

Get Widget Method

Providing the mediator object to view-plugins, the dashboard calls the mediator.getWidget() method and expects to get a UI tile containing widgets that the application needs to present. Typical definition looks as follows:

define([
"dojo/_base/declare",
"dojo/Deferred",
"aps/Tile",
"aps/nav/ViewPlugin"
], function (declare, Deferred, Tile, Output, ViewPlugin) {
   return declare(ViewPlugin, {
      init: function (mediator) {

         var widget = new Tile({
            // Tile definition
         });

         mediator.getWidget = function () {
            //...
            return widget;
         };
         ...
      }
   });
});

The returned tile must be an object of the aps/Tile module. That is why, this approach allows using any properties and methods defined in that module. Important is that an application can change the tile state and branding properties as explained in the Service State Presentation section.

Note

mediator.getWidget is the method that identifies the advanced approach.

Warning

In a view-plugin, do not combine the basic and advanced approaches by using both the apsType and the mediator.getWidget in the same view-plugin definition declare(ViewPlugin, { ... }).

Watch Method

Updates of Resources

On screen refresh, the home dashboard service updates the list of resources of all customer subscriptions. The list is available as an associative array mediator.resourceUsage. An element in the array contains resources of a single subscription as returned by the resources operation defined in the standard Subscription APS type (/aps/2/<subscriptionGUID>/resources REST request).

resourceUsage: {"subscription GUID": [
/* Resource usage in the format returned by "GET /aps/2/<subscription GUID>/resources" */
  ],
  "<another subscription GUID>": [...]
}

Due to this source, the embedded view-plugins are able to watch for updates in the resource usage in scope of the current customer.

Method Structure

To provide the newest data, the view-plugin should watch for resource usage. The typical way is using the watch method. Since every application is interested in its own resources only, it is necessary to filter the resources as in the following example:

mediator.watch("resourceUsage", function (name, oldvalue, newvalue) {
   widget.removeAll();
   if(newvalue !== undefined) {

      /* Scan all customer's subscriptions */
      common.forEach(newvalue, function(subscriptionResources) {

         /* In each subscription, investigate every resource ... */
         subscriptionResources.forEach(function(resource) {

            /* ... and select own resources */
            if(resource.apsType === "http://aps-standard.org/samples/basic1p/vps/1.0") {
               /* Application specific code */
               // ...
            }
         });
      });
   }
   else {
      /* Application specific code */
      // ...
   }
   var output = new Output({
      /* Application specific code */
      // ...
   });
   widget.addChild(output);
});

Once a resource is changed, the above code updates the tile widget as well.

Output

A view-plugin returns a UI tile to present the application data in the dashboard.

../../../../../_images/adv-tile.png