Plugin System

The Gentics Mesh plugin system allows you to write and deploy custom plugins which can enrich the existing REST API.

Typical example plugins are:

  • Comment plugin - A plugin to provide a commenting feature.

  • Like plugin - A plugin to store likes to specific nodes.

  • Sitemap plugin - A plugin which generates a sitemap XML file.

A plugin can access the filesystem or use the Gentics Mesh REST Client to interact with the Mesh server.

Plugins

Check the Gentics Mesh Awesome List for plugins.

Plugin System

Configuration

The plugin directory can be configured within the mesh.yml configuration file. Each plugin may place its own configuration file within its own plugin directory.

Plugin Lifecycle

Deploy

Name Description

Loading

Plugin gets loaded and prepared for starting

Starting

Plugin gets started.

Pre-registration

Plugin gets pre-registered. The plugin will stay in this mode util the server is ready to initialize them.

Initialisation

Plugin gets initialized. You can implement the MeshPlugin#initialize() method to initialize your plugin resources.

Registration

Plugin gets finally registered so that it can be used.

Undeploy

Name Description

De-registration

Plugin registration gets removed. At this point the plugin integration with the server gets removed. REST and GraphQL extensions get removed.

Shutdown

Plugin gets shutdown. You can implement the MeshPlugin#shutdown() method to stop and free your plugin resources.

Stopping

Plugin gets stopped.

Unloading

Finally the plugin gets unloaded.

Deployment

Plugin verticles can be deployed in various ways.

Automatically during start-up

Any plugin jar file which was found in the configured plugins folder will automatically be deployed during server startup.

Deployment via REST API

Plugins can be managed via the /api/v2/admin/plugins endpoint. It is possible to deploy, undeploy and read plugin information.

Plugin jar files which have been copied to the configured plugins folder can be deployed via the POST /api/v2/admin/plugins endpoint.

{
  "path" : "my-plugin.jar"
}

Any deployed plugin can be referenced by the id and loaded via the GET /api/v2/admin/plugins/:id.

{
  "id" : "hello-world",
  "name" : "Hello World 1",
  "manifest" : {
    "id" : "hello-world",
    "name" : "Hello World 1",
    "description" : "A dummy plugin",
    "version" : "1.0",
    "author" : "Joe Doe",
    "inception" : "2018-10-12T14:15:06.024Z",
    "license" : "Apache License 2.0"
  }
}
Plugins will not be directly accessible when deployed since the deployment process will first pre-register them.

You can undeploy a plugin via the DELETE /api/v2/admin/plugins/:id endpoint.

Programmatically deployment

You can deploy plugins programmatically in your IDE of choice via the Java API. This is useful for integration testing or when creating custom Gentics Mesh server bundles.

Mesh mesh = Mesh.mesh();
mesh.run(false);

# Embedded in your IDE
mesh.deployPlugin(YourPlugin.class, "your-plugin").blockingAwait();

Events

Gentics Mesh provides various events which can be acted upon. The events can be via the internal API or via the websocket endpoint.

Name Description

mesh.plugin.deploying

Emitted once a plugin is being deployed.

mesh.plugin.pre-registered

Emitted once a plugin has been pre-registered.

mesh.plugin.registered

Emitted once a plugin has been registered.

mesh.plugin.deployed

Emitted once a plugin has been deployed.

mesh.plugin.deploy.failed

Emitted when a plugin deployment fails.

mesh.plugin.undeploying

Emitted once a plugin is being undeployed.

mesh.plugin.undeployed

Emitted once a plugin has been undeployed.

Clustering

Plugins will only be registered once the write quorum has been reached. Until then the deployed plugins will remain in the pre-registered status.

The registration of plugins in clustered mode utilizes a lock to prevent concurrent plugin initialization within the cluster.

Plugins will not be automatically undeployed or unregistered once the write quorum is no longer reached.
Plugins which use event handling should be aware that every plugin instance in the cluster will process the event. If this is not desireable a locking or negotiation mechansim should be used to prevent concurrent event handling.

HTTP/2

Plugins can use HTTP/2 protocol for the connectivity by setting the boolean environment variable MESH_PLUGIN_USE_HTTP2, or Java API MeshOptions.setPluginUseHttp2().

Plugin Development

FAQ

  • Can I access the Gentics Mesh Graph in order to add custom elements to it?

No this is not possible. Using the Graph API could potentially alter the Graph structure and cause data inconsistencies.

  • Using a REST client to interact with the Mesh Server seems inefficient. Is there maybe a direct way to interact with Gentics Mesh?

We are aware of this limitation and are working on a local client which would work without involving the HTTP stack.

Future

  • UI In the future we will also support UI plugins. A plugin will be able to hook into the Gentics Mesh UI in order to add additional custom UI elements.