Bloomreach

Bloomreach Documentation version

This article covers a Bloomreach Experience Manager version 12. There's an updated version available that covers our most recent release.

Essentials Plugin SDK

Before you get started developing your own Essentials plugin, we recommend you take some time to familiarize yourself with Essentials' Plugin SDK. The Plugin SDK exposes a stable API against which you can build your own Essentials plugin.

Getting Started

To get started, create a new Maven project, or if you want to add your plugin to an existing project, create a new Maven module in that project. Then, add a dependency to the Plugin SDK to the module's pom.xml file:

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

What's in the box?

With this dependency in place, in your IDE, you should be able to browse the content of this artifact. Let's quickly examine the conceptual parts:

API Models

Inside the sdk.api.model package, you find a handfull of simple POJO model classes, some of which are exposed over REST (i.e. serialized to JSON) to the Essentials Dashboard (front-end). Most notably, the PluginDescriptor is the Java object representing a super-set of what an Essentials plugin's Plugin Descriptor file can specify.

Services

Inside the sdk.api.service package, you find a collection of service interfaces which your Essentials Plugin can use in custom installation instructions and dynamic REST resources. These services faciilitate how the plugin interacts with the project. At a high level, there are 3 types of interaction:

  1. Interaction with Essentials. This primarily happens through the SettingsService, which provides you with a few global parameters such as the project's primary Namespace, preferred templating language and more. See sdk.api.model.ProjectSettings for more info.
  2. Interaction with the JCR Repository. This primarily happens through the JcrService, which provides you with a JCR session with admin privileges.
  3. Interaction with the Project Sources. This happens through the majority of the other services. Noteworthy are sdk.api.model.Module, which is used by multiple services to indicate which Maven module the service should interact with, as well as the ProjectService, which translates the ProjectSettings into a set of file system Path's through which you can access certain areas of your project.

To use any of these services, define a class-level member of the corresponding type and annotate it with @javax.inject.Inject. The Essentials web application, when instantiating the custom installation Instruction or dynamic REST resource, will make sure the appropriate implementation of the requested service will be injected into the new instance. Please note that custom instructions currently only support zero-argument constructors, so the @Inject annotation must be placed with the member rather than the constructor.

For more info about the API services, we refer to their Javadoc.

Installation

Frequently-used installation actions such as copying a file into your project or importing nodes and properties into the repository is enabled through a set of pre-defined installation instructions. To use these built-in instructions, your Essentials plugin must include an XML packageFile. The schema to use for this file is defined in the instructions.xsd resource packaged in the Plugin SDK. More information about the packageFile can be found on the page describing the Essentials Plugin Installation process.

On top of the built-in instructions, you can create a custom installation instruction by implementing the sdk.api.install.Instruction service provider interface (SPI) and referring to it from the built-in <execute> instruction. Your custom instruction will typically use one or more of the API services described above.

Front-End Integration

If your Essentials plugin includes a front-end fragment for parameterised installation and/or configuration purposes, it will have to integrate into the Essentials Dashboard AngularJS application. For this, the Plugin SDK includes a set of AngularJS services and directives the plugin can use. These are packaged as web fragments in the API JAR, i.e. under META-INF/resources/dashboard/api, and described in more detail on the front-end page.

Compatibility / Stability

As of version 4.2.0, the Essentials Plugin SDK API applies the Semantic Versioning principles, meaning that backwards incompatible changes can only be made by releasing a new major version of the API.

Please do not make your Essentials plugin depend on the Plugin SDK Implementation module, as that module does not expose a stable interface, and may change unexpectedly. If your Essentials plugin requires certain functionality present in the implementation module, let us know and we'll investigate if we can expose that functionality through a stable API in a new version.

 

 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?