Essentials Plugin Descriptor
At the core of Essentials' extensibility mechanism is the Plugin Descriptor. The plugin descriptor is a JSON-formatted file describing the plugin to Essentials. The Plugin Descriptor provides information how to (1) advertise the plugin in the Essentials Dashboard, how to (2) install the plugin (if it is of type feature) and how to (3) use the plugin, once fully installed.
Packaging
The typical mechanism for making Essentials aware of a plugin is to package the plugin descriptor file as a root-level resource in the JAR representing the Essentials plugin, and then adding that artifact as a dependency to your project's local Essentials module (essentials/pom.xml). If the Essentials plugin is organized as a Maven module, you put the plugin descriptor at /src/main/resources/plugin-descriptor.json. During bootstrapping, the Essentials web application will perform a classpath scan to detect these plugin descriptors and compile a list of available plugins.
Basic Structure
Each plugin descriptor is represented as a single, JSON-formatted object. Each plugin descriptor must declare at least the following information:
| Field | Description |
|---|---|
| id | Identifier (String) to uniquely identify this plugin among all (future) plugins you may want to use inside a single Essentials web application |
| type |
Either "feature" or "tool". Features are subject to the plugin installation process, tools are not, i.e. they are considered to be operational as soon as they have been included in the Essentials web application. |
Advertisement
In order to advertise an Essentials plugin to the user of the Essentials Dashboard, a plugin should provide information based on which the user can decide whether or not she want to use that plugin. Essentials has no localization support, all advertisement data should be in English. An Essentials plugin should provide the following fields in order to advertise itself:
| Field | Description |
|---|---|
| name | Human-readable name, conveying the intent of the plugin. |
| icon | Value for the <img> tag's src attribute to load and display a 76x76px icon next to the plugin name. Typically, the icon is packaged as a web fragment inside the plugin artifact (JAR). If so, the relative pathInfo to the plugin's image should be specified as the context-path of the Essentials application ('essentials') followed by the path to the web fragment. In order to avoid the collision of web fragments, as a best practice, fragments contributed by a plugin should be located at [pluginType]/[pluginId]/[pluginSpecificNamespace]. For example, if the plugin packages its icon at /src/main/resources/META-INF/resources/feature/myPluginId/icon.png, the value for the icon field would be essentials/feature/myPluginId/icon.png. |
| introduction | HTML fragment introducing the plugin to the Dashboard user. We recommend no more than 3 lines of text when rendered in the Dashboard. |
| description | Optional HTML fragment to provide additional info, which is displayed to the Dashboard user in an initially collapsed section of the plugin. |
| documentationLink | Optional URL of the entry-point to external documentation for this plugin. |
| vendor | Nested object, specifying the name and url of the vendor/developer of the plugin. |
| imageUrls | Optional list of image URLs, using the same format as the icon field described above. If provided, images should have a resolution of 1280x720px. The Dashboard will display them in a carousel when the (additional) description part of the plugin is expanded. |
Installation
In case of a feature plugin, which undergoes installation, the following plugin descriptor fields control the installation of the plugin. The Installation process is described in more detail on the Plugin Installation page.
| Field | Description |
|---|---|
| packageFile | Classloader path where the packaged XML file, describing the actions to execute during installation, is located. Since all plugins are packaged into the Essentials web application, this path must be unique across all plugins bundled in the web application. For example, if the file is located at src/main/resources/instructions/myPluginId_instructions.xml, the value of the packageFile field should be instructions/myPluginId_instructions.xml. |
| installWithParameters | Optional boolean flag indicating that the installation of a plugin uses parameters, such as whether or not to install sample content. By default (when absent), the flag is set to true, so you only have to specify the field in order to indicate that your plugin has no installation parameters (false). |
| rebuildAfterInstallation | Optional boolean flag indicating that the installation of a plugin requires a rebuild and restart before the plugin is considered fully installed. By default (when absent), the flag is set to true, so you only have to specify the field in order to indicate that your plugin does not require a rebuild and restart to complete the installation process. |
| pluginDependencies | Optional list of plugin dependencies. For each plugin this plugin depends on, a nested object indicates which plugin this plugin depends on, and how it depends on it. More detailed information about inter-plugin dependencies is provided on the Plugin Installation page. |
Usage
When a plugin provides configuration-related functionality beyond the plain installation of a feature (which should always be the case for tools), the following descriptor fields instruct the Essentials web application what to do:
| Field | Description |
|---|---|
| restClasses | Optional list of fully qualified class names, each entry referring to a class implemented and packaged in the plugin, which represents a JAX-RS 2.0 REST resource. The Essentials web application will instantiate this class, inject SDK API dependencies and register it as a singleton with the back-end JAX-RS REST application. |
| hasConfiguration | Optional boolean flag indicating that a feature plugin provides configuration functionality on top of the feature's typical installation logic. |
Example Plugin Descriptor
To make plugin descriptors more tangible, here's the content of a sample plugin descriptor:
{
"id": "bannerPlugin",
"type": "feature",
"name": "Banners",
"icon": "/essentials/feature/images/banner-plugin-icon.png",
"introduction": "With Banners, you add banners and carousels to your project. Two drag-and-drop components will be added to the component library in the Channel Manager: a Banner component and a Carousel component. Furthermore, a 'Banner' document type and some sample banner documents and images will be installed.",
"documentationLink": "https://www.onehippo.org/library/setup/hst-components/document-component.html",
"imageUrls": [
"/essentials/feature/images/screenshots/banner01.png",
"/essentials/feature/images/screenshots/banner02.png",
"/essentials/feature/images/screenshots/banner03.png",
"/essentials/feature/images/screenshots/banner04.png"
],
"vendor": {
"name": "BloomReach",
"url": "https://www.bloomreach.com"
},
"packageFile": "/META-INF/banner_instructions.xml",
"pluginDependencies": [
{
"pluginId": "skeleton"
}
]
}