Creating a Plugin

Last updated a month ago

Plugins enable you to add optional features across multiple apps of the CoreMedia Blueprint.

What you'll learn

Creating new plugins

Prerequisites

Blueprint Workspace
Basic knowledge of Java, Spring, Maven

Time matters

Reading time: 5 to 7 minutes

Should I read this?

This guide is for Developers.

Table of Contents

Introduction
Plugin Workspace Structure
Implementing the Plugin
Further Reading

Introduction

Plugins are developed in their own workspaces and have their own release cycle, apart from the Blueprint. They are bundled with the application, when creating Docker images or when deploying the application.

Plugin Workspace Structure

You have to implement a plugin in a specific workspace structure. The following image shows a simplified view on the content-hub-adapter-filesystem plugin workspace.

content-hub-adapter-filesystem
+- studio-client
|  |- [...]
+- studio-server
|  |- src
|  |  \- main
|  |     \- java
|  |        \- com.coremedia.labs.plugins.adapters.filesystem.server
|  |           +- FilesystemConfiguration.java
|  |           +- FilesystemContentHubAdapterFactory.java
|  |           +- [...]
|  \- pom.xml
+- content-hub-adapter-filesystem.json
\- pom.xml

The content-hub-adapter-filesystem plugin gives you access to content in your local filesystem from Studio. To do so, it implements a studio-server and studio-client app plugin. The studio-server app plugin is a Java and Maven based plugin, while the studio-client app plugin is JavaScript and npm based. In this how-to guide, we limit the description to the studio-server app plugin.

In the following section, you will learn which parts of a Java plugin are stored in which location and needs which files and settings. Have a look at the corresponding files in content-hub-adapter-filesystem to learn how to implement the features.

Implementing the Plugin

1. Create app plugins for multiple CoreMedia applications.

Usually, a plugin consists of multiple app plugins because it needs to access different CoreMedia applications. In the example, these are studio-server and studio-client. The composition of the app plugins constitutes the plugin, or the feature from the user’s perspective.

Implementing an extension point.

A Java app plugin usually implements an extension point. In this example case, the class FilesystemContentHubAdapterFactory implements the ContentHubAdapterFactory interface. See Extension Points for a complete list of extension points that plugins can implement.
Create a Spring configuration class

A Java app plugin must have a Spring configuration class to provide beans of the extension points. FilesystemConfiguration.java provides a ContentHubAdapterFactory:
```
  @Bean
  public ContentHubAdapterFactory<?> filesystemContentHubAdapterFactory() {
    return new FilesystemContentHubAdapterFactory();
  }
```
Configure the app plugin in the pom.xml file of the app plugin.
- The app plugin studio-server is basically a Java module. However, it must have the custom packaging type coremedia-plugin in order to work with the coremedia-plugins-maven-plugin.
  
  <packaging>coremedia-plugin</packaging>
  
  The artifact of a coremedia-plugin module is not a JAR file, but a plugin ZIP file, which contains the module code and the dependencies.
- Reference the Spring configuration class (here FilesystemConfiguration) in the <pluginConfigurationClass> configuration of the coremedia-plugins-maven-plugin.
- Configure the coremedia-plugins-maven-plugin with the other properties needed to generate a plugin.properties file, which is an essential feature of a plugin artifact.
  
  <plugin> <groupId>com.coremedia.maven</groupId> <artifactId>coremedia-plugins-maven-plugin</artifactId> <version>0.1.0</version> <extensions>true</extensions> <configuration> <pluginId>${project.artifactId}</pluginId> <pluginVersion>${project.version}</pluginVersion>  <pluginConfigurationClass>f.q.p.FilesystemConfiguration</pluginConfigurationClass> <pluginProvider>CoreMedia</pluginProvider> </configuration> </plugin>
Take great care for dependency scopes in-app plugin modules! Unlike in ordinary Java modules, dependencies on libraries already packaged with CoreMedia applications which you cannot have multiple versions/instances of, must have the scope provided. This concerns especially com.coremedia.cms dependencies and the Spring and logging frameworks.

See the full documentation for details. This is important because you do not notice scope errors during plugin development, but only when you run the application enhanced with the plugin. It may fail with class loading errors or show even more subtle effects if the scopes are not correct.

2. Create the plugin descriptor

Every plugin must have a plugin descriptor. The plugin descriptor maps the app plugins to the apps. In this example, the plugin descriptor is the content-hub-adapter-filesystem.json file. It maps the release location of the studio-server and studio-client app plugins to the corresponding CoreMedia applications.

{
  "$schema": "https://releases.coremedia.com/plugins/plugin-schema-2.0.0.json",
  "plugins": {
    "studio-server": {
      "url": "https://github.com/CoreMedia/content-hub-adapter-filesystem/releases/download/v2.0.0/studio-server.content-hub-adapter-filesystem-2.0.0.zip"
    },
    "studio-client.main": {
      "url": "https://github.com/CoreMedia/content-hub-adapter-filesystem/releases/download/v2.0.0/studio-client.main.content-hub-adapter-filesystem-2.0.0.zip"
    }
  }
}

In the source code of the content-hub-adapter-filesystem this plugin descriptor file is only a template, and the real plugin descriptor is generated by a GitHub action during the release. But it is up to you to use GitHub actions, any other deployment process, or maintain the plugin descriptor manually.

3. Release the Plugin

The mandatory artifacts of a plugin are the following:

The plugin descriptor
The app plugin ZIP files

The artifacts must be released into some repository, so that they can be used in Blueprint projects. The content-hub-adapter-filesystem, for example, lies in GitHub.