Plugin Installation
Introduction
Essentials plugins are typically represented by two artifacts:
- A Plugin Descriptor
- A Plugin JAR
Some plugin descriptors and JARs are built into the Essentials setup application (i.e. packaged inside the essentials WAR), others (including plugins contributed by 3rd parties) can be retrieved from external servers.
Essentials implements a state machine for installing Essentials plugins into the setup application and into the Hippo project's CMS and site applications.
In order to be able to develop an Essentials plugin which installs successfully and takes advantage of the setup application's standardized installation process as much as possible, a good understanding of the installation state machine is required.
Installation State Machine
Initially, the setup application loads all plugin descriptors and shows them in the Library tab of the dashboard. There, users of the setup application can click on the Install Feature button, which starts the installation process.
The installation process consists of two major phases, both of which may require rebuilding your project.
Phase 1 (Boarding)
The first phase takes care of installing the plugin JAR as a dependency into your setup application. If the plugin was pre-packaged with the setup application, the plugin JAR is already part of the setup application, and step one only involves installation state-tracking. Otherwise, the dependency on the plugin JAR is added to your setup application, and you need to rebuild it in order to make that JAR available to the running setup application. The dashboard monitors this and indicates when a rebuild is necessary.
In order to speed up and simplify the installation process, this first step also involves installing any additional dependencies into your project's CMS and site applications. That is why the plugin descriptor supports the dependencies section. If additional dependencies are necessary, the corresponding web applications also need to be rebuilt / restarted. For simplicity, we recommend to always rebuild and restart your entire project.
After the first phase, the installation state machine considers the plugin on board.
Phase 2 (Setup)
The state machine uses the term setup for this second phase. During the setup phase, instructions are executed to install the plugin into your project. Typically, this involves copying files into your project and importing configuration into your repository.
The plugin descriptor's packageFile and packageClass properties are used to indicate that the installation of a plugin should go through the setup phase. If no setup phase is required, the state machine has reached its terminal state installed.
If there is a setup phase, the behavior of the state machine depends on the project setting to "override / confirm the settings on a per-plugin basis". If the default (no need to confirm) is used, the setup application will trigger the execution of the setup phase at the earliest possible moment, i.e. as soon as the plugin is on board. Otherwise, or if the plugin JAR indicates the need for an explicit setup phase by means of the parameterServiceClass, the dashboard shows a "Needs to be configured" button in the Installed Features tab, bringing the user to a plugin-specific view where setup parameters can be entered/confirmed before the setup phase takes place.
If the setup phase adds resources to your Hippo project, a rebuild / restart cycle is necessary to make them available to your running project. Again, the dashboard will indicate this need. After the rebuild, the installation state machine considers the plugin to be fully installed.
Here's a schematic view on the installation state machine:
