Essentials Plugin Front End

An Essentials plugin can contibute its part to the front-end Dashboard application. For that, contributions made by the plugin have to integrate with the AngularJS Dashboard application.

Use Cases

There are basically two use cases for which an Essentials plugin might want to make a contribution to the Dashboard:

1. The installation of a feature plugin depends in installation parameters the Dashboard user may want to control. The plugin SDK API includes the AngularJS directive <essentials-simple-install-plugin> a plugin can use to control the built-in installation parameters. See below for more details about this directive.
2. The configuration options offered by a plugin requre exposing a UI fragment. This is always true for plugins of type tool, and optional for plugins of type feature.

Packaging

A plugin may need to contribute HTML fragments and/or JS code to the Dashboard. Essentials uses the Servlet specification 3.0 Web fragment mechanism for making these resources, contributed by plugin JARs, available to the front-end. In short, this means that an Essentials plugin must package a META-INF/web-fragment.xml file, any resource to be requested by the front-end must be located under META-INF/resources (see also the icon and imageUrls fields of the Plugin Descriptor). In order to avoid namespace collisions between plugins, and in order to automatically detect and load these resources, Essentials implements the convention that contributions to the Dashboard are located at <pluginType>/<pluginId>/<pluginId>.[html|js] inside the web fragment.

For example, the JS resource contributed by the feature plugin with ID "myPluginId" would be located in your Maven module at src/main/resources/META-INF/resources/feature/myPluginId/myPluginId.js.

Functionality

Since the Dashboard is implemented as an AngularJS single page application, the functionality contributed to it by an Essentials plugin is integrated by registering a controller with the hippo.essentials AngularJS module. Each controller must have a unique name. Typically, this is actieved by concatenating the plugin ID with the suffix Ctrl. The controller can request the AngularJS application to inject any standard AngularJS services such as the frequently-used $scope (for interacting with the HTML fragment) and $http (for interacting with the REST endpoints of the back-end). On top of these standard services, the Dashboard exposes a few Essentials-specific services, which are included as web fragments in the Plugin SDK API JAR. We give a short introduction to these services in the table below. For more information, please examine the inline documentation of the Plugin SDK's META-INF/resources/dashboard/api/services.js.

Here is an example of a plugin's contribution to the functionality of the Dashboard. It makes a function available to the HTML fragment through which it can request the plugin's dynamic REST endpoint to provide plugin-specific data. If the plugin is of type tool or if it indicates hasConfiguration, and if the JS resources is packaged in a web fragment as explained above, the Dashboard will automatically detect, load and register it.

(function () {
  "use strict";
  angular.module('hippo.essentials')
    .controller('myPluginCtrl', function ($scope, $http, essentialsRestService) {
      $scope.getMyStuff = function () {
        $http.get(essentialsRestService.baseUrl + '/myPlugin').success(function(data) {
          $scope.data = data;
        });
      };
    });
})();

Presentation

While the AngularJS controller above takes care of the plugin's front-end functionality, a HTML fragment takes care of the presentation of that functionality. A plugin's HTML fragment can use a number of AngularJS directives provided by the Plugin SDK API, and/or it can interact with its AngularJS controller. The controller is only created if the HTML fragment explicitly requires it. If the HTML fragment doesn't require the controller, no Javascript resource needs to be packaged with the plugin.

Just like the Javascript resource, the HTML fragment must be packaged as web fragment. The Dashboard automatically loads the fragment when necessary. If a feature plugin has no installation parameters and no configuration, no HTML fragment will ever be needed, so the plugin doesn't need to package one.

The Plugin SDK API provides plugins with a set of Essentials-specific directives, which HTML fragments can use. We give a short introduction to these directives in the table below. For more information, please examine the AngularJS code of the PluginSDK's META-INF/resources/dashboard/api/directives.js.

Here is an example of a plugin's HTML fragment. It simply renders the "confirmed" installation form to specify the template language (Freemarker or JSP) and whether or not to install sample data, while there are no extra templates available.

<essentials-simple-install-plugin plugin-id="myPluginId" has-sample-data="true"></essentials-simple-install-plugin>

The Essentials Dashboard application uses bootstrap-like styling.