Plugin Installation

Overview

Essentials plugins of type feature require installation. When you install a feature plugin, Essentials applies changes to your project sources. These changes may include copying or modifying Java classes, configuration files, or other resources. Additionally, Essentials can import nodes and properties into a running repository. The auto-export mechanism then exports these changes as YAML files into your project sources.

After most changes to your project sources, you must rebuild your project (to package updated resources into new WAR files) and restart your local deployment. Some plugins do not require a restart. If so, the plugin can indicate this in its Plugin Descriptor. Essentials tracks each plugin's installation state using a plugin file stored in the essentials module's resources. By default, these files are located at essentials/src/main/resources/<pluginId>.xml.

Inter-Plugin Dependencies

Essentials plugins can declare dependencies on other plugins. A plugin may require other plugins because its installation depends on certain project sources, repository nodes, or node types being present. The plugin installation mechanism ensures that all required plugins are installed first.

Declare dependencies in the Plugin Descriptor by specifying the plugin ID of each dependency. For example:

{
  "id": "pluginA",
  // ...
  "pluginDependencies": [
    {
      "pluginId": "pluginB"
    }
  ]
}
copy

In this example, "pluginA" can only be installed after "pluginB" is installed. If "pluginB" requires a rebuild and restart after its installation, "pluginA" can be installed before you rebuild and restart.

If "pluginA" requires a rebuild and restart after "pluginB" is installed (for example, if "pluginB" adds a dependency that creates a new JCR namespace needed by "pluginA"), use the minInstallStateForInstalling property:

{
  "id": "pluginA",
  // ...
  "pluginDependencies": [
    {
      "pluginId": "pluginB",
      "minInstallStateForInstalling": "installed"
    }
  ]
}
copy

Setting minInstallStateForInstalling to installed ensures that "pluginA" is only installed after "pluginB" has reached the installed state, which occurs after the required rebuild and restart. The default value is installing, which is the state before the rebuild and restart.

Installation Instructions

During plugin installation, the Essentials web application executes sets of installation instructions. The plugin specifies which instructions to run using a packageFile, referenced in the Plugin Descriptor. The package file follows the XML schema defined in the Plugin SDK API and organizes instructions into instruction sets.

Each instruction set can include a comma-separated list of group names using the group attribute. This attribute determines whether the instructions in that set are executed during installation.

Installation Parameters

Installation parameters determine which instruction sets are executed during plugin installation. The Essentials web application provides two built-in installation parameters. Advanced plugins can define additional custom parameters. The built-in parameters are stored in essentials/src/main/resources/project-settings.xml:

1. extraTemplates: Installs extra HST component template variants.
2. sampleData: Installs sample data into the project.

You can reference these flags in the group attribute of instruction set tags in your package file. If you specify multiple flags (comma-separated), the instruction set runs if at least one flag is true during installation. If you omit the group attribute, the instruction set always runs.

Note: By default, Essentials uses the global flags during installation. To override these settings for a specific plugin, you can adjust the installation parameters in the Advanced Settings section of the Dashboard's Settings screen before installing each plugin. This allows for more granular control but requires additional steps.

Built-in Instructions

Essentials provides several built-in instruction types. The table below summarizes each instruction element:

Element Name	Description
file	Copy a file from a source location (classloader resource path) to a target location (project sources), append data from a source to a target, or delete a file at a target location. Placeholder substitution is applied to text-based (non-binary) files.
freemarker	Same as <file>.
directory	Create a directory at a target location or copy an entire directory from a source location to a target location.
xml	Import nodes and properties from a source location (node:sv XML classloader resource path) to a target JCR path, or delete a node at a target location.
cnd	Register a JCR content type, given an existing namespace and optionally a list of existing supertypes.
translation	Import a set of translations (JSON-formatted localized labels) from a source location into the JCR repository.
mavenDependency	Register a Maven dependency with the specified Maven module.
hstBeanClasses	Register a scanning pattern for the site module to detect HST beans.
execute	Execute a custom instruction, typically defined within the plugin.

Essentials supports a range of placeholders for use in imported resources (such as text-based files or node:sv XML files) and target locations. The complete set of supported placeholders is defined in the Plugin SDK API's PlaceholderService interface. To use a placeholder, embed it with double curly braces in your instructions.xml file or resource files. See the example package file below for usage.

Custom Instructions

If your plugin requires installation actions not covered by the built-in instructions, you can implement custom instructions. Create a Java class that implements the sdk.api.install.Instruction SPI. Implement your custom logic in the #execute method, using services from the Plugin SDK API. Also implement the #populateChangeMessages method to provide a preview of your instruction's effects in the Dashboard.

To execute your custom instruction during plugin installation, add an <execute> instruction to the relevant instruction set in your package file and reference your custom instruction class.

Example Package File

The following example shows a package file with several instruction types and usage of placeholders:

<?xml version="1.0" encoding="UTF-8"?>
<instructions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://www.onehippo.org/essentials/instructions /instructions.xsd"
              xmlns="http://www.onehippo.org/essentials/instructions">
  <instructionSet>
    <hstBeanClasses pattern="classpath*:org/onehippo/forge/**/*.class" />
    <mavenDependency targetPom="cms" groupId="org.example" artifactId="some-dependency"/> 
    <execute class="org.example.essentials.plugin.CustomInstruction" />
    <file action="copy" source="java/HstBean.txt" target="{{beansFolder}}/HstBean.java"/>
  </instructionSet>

  <instructionSet group="sampleData">
    <xml action="copy" source="instructions/xml/sample-data.xml" target="/content/documents"/>
  </instructionSet>
</instructions>
copy