Essentials Plugin Descriptor
The Essentials setup application is extensible by means of Essentials Plugins. For Essentials to be able to deal with a plugin, each Essentials plugin is described by a Plugin Descriptor. The Plugin Descriptor contains all information necessary for the setup application to install and use the plugin, including any plugin-related information you find on the setup application's Library page.
Essentials comes with a set of plugins available by default. The plugin descriptors for these plugins are embedded in the essentials.war web application. Your project can add additional, custom plugins by putting their descriptors into the file /essentials/src/main/resources/project_plugin_descriptor.json of your Hippo project.
In the future, Essentials might also try to collect plugin descriptors from external locations such as the Essentials Marketplace.
Once a valid plugin descriptor has been retrieved, the actual plugin, represented by a JAR file available through a Maven repository, can be installed.
Descriptor Format
The plugin descriptor is represented by a JSON string. Here is an example plugin descriptor:
{
"@type": "plugin",
"id": "newsPlugin",
"name": "News",
"icon" : "/essentials/images/icons/news.png",
"type": "feature",
"introduction": "With News, you can easily integrate news functionality in the CMS.",
"description": "This feature installs a new document type 'newsdocument' in the CMS, containing fields for Title, Introduction, Content, News date, Author, Source, Location and News Image.",
"documentationLink": "http://www.onehippo.org/library/essentials/hst-components/news-component.html",
"imageUrls": [
"/essentials/images/screenshots/news01.png",
"/essentials/images/screenshots/news02.png"
],
"packageFile": "/META-INF/news_package_instructions.xml",
"vendor": {
"@type": "vendor",
"name": "Hippo",
"url": "https://www.onehippo.com"
}
}
You can find more examples in the current plugin descriptor list plugin_descriptor.json in the Essentials project's dashboard module.
Descriptor Fields
Here's an alphabetical list of all available Essentials plugin descriptor fields.
| Field | Multiplicity | Description |
|---|---|---|
| dependencies | * | A list of Maven dependencies that will be added to the specified target POM file(s) of your project during the boarding installation phase. Essentials makes sure that dependencies already present will not be installed twice. The structure of a single dependency is documented below. |
| description | ? | Additional descriptive text to show in the "read more" section of the plugin in the Library tab of the setup dashboard. HTML-tags are allowed. See also: introduction. |
| icon | ? | URL of icon/logo representing the plugin in the setup dashboard. Dimensions should be 78 by 78 pixels. |
| imageUrls | * | List of URLs of images / screenshots visualizing the plugin. The current dashboard styling supports a maximum of 4 images, and requires an image size of 900 by 500px. |
| introduction | 1 | Descriptive text to show in the Library tab of the setup dashboard. HTML-tags are allowed. See also: description. |
| libraries | * | List of Javascript resources to be included in the setup dashboard to make the plugin's UI work. The structure of a single "library" is documented below. |
| name | 1 | Descriptive name of the plugin, displayed at several locations in the setup dashboard. |
| packageClass | ? | Fully qualified name of a Java class included in the plugin JAR, which represents the setup instructions for this plugin. Don't use packageClass and packageFile in the same descriptor. |
| packageFile | ? | Location and name of the XML file inside the plugin JAR, containing the setup instructions for this plugin. Don't use packageFile and packageClass in the same descriptor. |
| parameterServiceClass | ? | Fully qualified name of a Java class included in the plugin JAR, which specifies additional plugin parameters to guide the plugin installation process by implementing org.onehippo.cms7.essentials.dashboard.config.PluginParameterService. |
| pluginId | 1 | Unique identifier of the plugin. The identifier must be unique across all plugins used in the setup application. One of the things the pluginId is used for is to load the plugin UI HTML fragment. The setup dashboard will try to load it from META-INF/resources/<type>/<pluginId>/<pluginId>.html within the plugin JAR. |
| repositories | * | List of Maven repository descriptions indicating which additional repositories should be checked when including this plugin in your Hippo project. The structure of a single repository is documented below. |
| restClasses | * | List of fully qualified names of Java classes which implement REST resources and should be dynamically mounted by the setup application in order to serve REST calls made by the plugin's front-end. |
| @type | 1 | The value must be "plugin". This field is required to make the mapping between a JSON plugin descriptor and the corresponding PluginRestful Java class work. |
| type | Plugin type. Either feature or tool. Influences where/how the plugin will show up in the dashboard. | |
| vendor | 1 | Information about the plugin vendor. The structure of the vendor tag is documented below. |
Dependencies
Each dependency is represented by a JSON string with the following fields.
| Field | Multiplicity | Description |
|---|---|---|
| artifactId | 1 | Maven dependency artifactId. |
|
groupId |
1 | Maven dependency groupId. |
| scope | ? | Maven dependency scope. |
| targetPom | 1 | Name of the module for which the dependency should be added. For example, site if the dependency should be added to the site/pom.xml file of your Hippo project. |
| @type | 1 | The value must be "dependency". This field is required to make the mapping between the JSON string and the corresponding DependencyRestful Java class work. |
| type | ? | Maven dependency type. |
| version | ? | Maven dependency version. |
Libraries
The value of the libraries field is a JSON object with the single field "items", which takes as value an array of JSON objects with the following fields:
| Field | Multiplicity | Description |
|---|---|---|
| component | 1 | Name of directory "representing the component" which contains the Javascript resource. When co-locating the JS file with the corresponding HTML fragment, to make up the front-end part of the plugin, the directory name would be equal to the value used for the plugin descriptor's pluginId. |
| file | 1 | Name of the Javascript resource file (including extension), inside the component directory. |
A typical example for the libraries field of a plugin with pluginId "abc" would be
"libraries": [
{
"items": [
{
"component": "abc",
"file": "abc.js"
}
]
}
]
Above example indicates that the Javascript resource is loaded from the plugin JAR at META-INF/resources/<type>/abc/abc.js.
Repository
Each repository is represented by a JSON string with the following fields.
| Field | Multiplicity | Description |
| id | 1 | Maven repository id. |
|
layout |
? | Maven repository layout. |
| name | ? | Maven repository name. |
| snapshots | ? | Maven Repository snapshots. Only the enabled policy is supported, the corresponding value is { "@type": "snapshots", "enabled": "true" }. |
| targetPom | 1 | Name of the module for which the repository should be added. For example site if the repository should be added to the site/pom.xml file of your Hippo project. |
| @type | 1 | The value must be "repository". This field is required to make the mapping between the JSON string and the corresponding RepositoryRestful Java class work. |
| url | 1 | Maven repository url. |
Vendor
The vendor value is specified as a JSON string with the following fields.
| Field | Multiplicity | Description |
| name | 1 | Descriptive name of the vendor. |
| @type | 1 | The value must be "vendor". This field is required to make the mapping between the JSON string and the corresponding VendorRestful Java class work. |
| url | 1 | URL of webpage with more information about the vendor. |