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.

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"
  }
}

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();

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.