Essentials Plugin SDK

The Essentials Plugin SDK provides a stable API for developing custom Essentials plugins for Bloomreach Content. Use this SDK to ensure compatibility and maintainability when building your own plugins.

Getting Started

To develop an Essentials plugin, create a new Maven project or add a Maven module to an existing project. Add the Plugin SDK dependency to your module's pom.xml:

<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-essentials-plugin-sdk-api</artifactId>
  <version>4.2.0</version>
</dependency>
copy

SDK Components

The Plugin SDK dependency provides several key components for plugin development.

API Models

The sdk.api.model package contains simple POJO model classes. Some of these classes are exposed over REST and serialized to JSON for the Essentials Dashboard front end. The PluginDescriptor class represents the complete set of properties that can be defined in a plugin's descriptor file.

Services

The sdk.api.service package provides service interfaces for use in custom installation instructions and dynamic REST resources. These services enable your plugin to interact with the project in three primary ways:

1. Essentials Settings: Use the SettingsService to access global project parameters, such as the primary namespace and preferred templating language. Refer to sdk.api.model.ProjectSettings for details.
2. JCR Repository Access: Use the JcrService to obtain a JCR session with administrative privileges.
3. Project Source Management: Use other services to interact with project source files. The sdk.api.model.Module class identifies Maven modules, and the ProjectService translates ProjectSettings into file system Path objects for accessing specific areas of the project.

To use a service, declare a class-level member of the corresponding type and annotate it with @javax.inject.Inject. The Essentials web application injects the appropriate service implementation when it instantiates a custom installation Instruction or dynamic REST resource. Custom instructions must use zero-argument constructors; apply the @Inject annotation to the member field, not the constructor.

Info: For detailed information about the API services, refer to the Javadoc.

Installation

Common installation actions, such as copying files into the project or importing nodes and properties into the repository, are handled by predefined installation instructions. To use these instructions, include an XML packageFile in your plugin. The schema for this file is defined in the instructions.xsd resource included with the Plugin SDK. For more information about the packageFile, see the Essentials Plugin Installation documentation.

You can also implement custom installation instructions by creating a class that implements the sdk.api.install.Instruction service provider interface (SPI). Reference your custom instruction from the built-in <execute> instruction. Custom instructions typically use one or more of the API services described above.

Front-End Integration

If your plugin includes a front-end fragment for parameterized installation or configuration, it must integrate with the Essentials Dashboard AngularJS application. The Plugin SDK provides AngularJS services and directives for this purpose. These resources are packaged as web fragments in the API JAR under META-INF/resources/dashboard/api. For implementation details, see the front-end integration documentation.

Compatibility and Stability

Starting with version 4.2.0, the Essentials Plugin SDK API follows Semantic Versioning. Backward-incompatible changes are only introduced in new major versions.

Do not depend on the Plugin SDK Implementation module. The implementation module does not provide a stable interface and may change without notice. If your plugin requires functionality from the implementation module, contact Bloomreach Support to request that the functionality be exposed through the stable API in a future release.