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.
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:
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.
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:
- 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.
- Interaction with the JCR Repository. This primarily happens through the JcrService, which provides you with a JCR session with admin privileges.
- 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.
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.
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.