Essentials Plugin Descriptor

The Plugin Descriptor is a JSON file that defines an Essentials plugin for Essentials. It enables Essentials to recognize, advertise, install, and use the plugin within the Essentials Dashboard.

Packaging

To register a plugin with Essentials, include the plugin descriptor file at the root of the JAR that represents your Essentials plugin. Add this JAR as a dependency in your project's local Essentials module (essentials/pom.xml). If your plugin is a Maven module, place the descriptor at /src/main/resources/plugin-descriptor.json. During startup, the Essentials web application scans the classpath for plugin descriptors and compiles a list of available plugins.

Basic Structure

Each plugin descriptor is a single JSON object. The following fields are required:

Field	Description
id	Unique string identifier for the plugin within the Essentials web application.
type	Plugin type: "feature" or "tool". Features require installation; tools are available immediately after inclusion in the web application.

Advertisement

To display a plugin in the Essentials Dashboard, provide the following fields. All advertisement data must be in English, as Essentials does not support localization.

Field	Description
name	Human-readable name that describes the plugin’s purpose.
icon	Path for the <img> tag's src attribute to display a 76x76px icon. Typically, the icon is packaged as a web fragment in the plugin JAR. Use the Essentials application context-path (essentials) followed by the path to the web fragment. To prevent conflicts, store fragments at [pluginType]/[pluginId]/[pluginSpecificNamespace]. For example, if the icon is at /src/main/resources/META-INF/resources/feature/myPluginId/icon.png, set icon to essentials/feature/myPluginId/icon.png.
introduction	HTML fragment introducing the plugin. Limit to three lines when rendered in the Dashboard.
description	(Optional) HTML fragment with additional information, shown in a collapsed section in the Dashboard.
documentationLink	(Optional) URL to external documentation for the plugin.
vendor	Object with name and url fields for the plugin vendor or developer.
imageUrls	(Optional) List of image URLs, using the same format as icon. Images should be 1280x720px. The Dashboard displays them in a carousel when the description is expanded.

Installation

For plugins of type feature, the following fields control the installation process. For more details, see Plugin Installation.

Field	Description
packageFile	Classloader path to the XML file that describes installation actions. This path must be unique across all plugins in the web application. For example, if the file is at src/main/resources/instructions/myPluginId_instructions.xml, set packageFile to instructions/myPluginId_instructions.xml.
installWithParameters	(Optional) Boolean flag. If false, the plugin does not require installation parameters. If omitted, defaults to true.
rebuildAfterInstallation	(Optional) Boolean flag. If false, the plugin does not require a rebuild and restart after installation. If omitted, defaults to true.
pluginDependencies	(Optional) List of dependencies. Each dependency is an object specifying the required plugin and the dependency type. For more information, see the Plugin Installation documentation.

Usage

If a plugin provides configuration functionality beyond installation (required for tools), use the following fields:

Field	Description
restClasses	(Optional) List of fully qualified class names for JAX-RS 2.0 REST resources implemented in the plugin. The Essentials web application instantiates these classes, injects SDK API dependencies, and registers them as singletons in the back-end JAX-RS REST application.
hasConfiguration	(Optional) Boolean flag. Indicates that a feature plugin provides configuration functionality in addition to installation logic.

Example Plugin Descriptor

The following example shows 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 Experience 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"
    }
  ]
}