Create your first plentyBase plugin (Tutorial)

October 5, 2018

Info: Plugins are supported since plentyBase version 1.5 and higher

The easiest way to get a quick and easy start into plentyBase plugin development is to begin with the provided HelloWorld sample plugin. This plugin provides simple and basic functionality and can be used as a starting point for any project.

Get the HelloWorld plugin

In order to get a simple, runnable example plugin project, just check out our HelloWorld plugin on GitHub.

Create an installable plugin

To get an installable plugin, you have to create a runnable jar file from your project with all classes and dependencies. How to do this is described below.

When you want to create a runnable plugin jar there are two possibilities. (The second one is recommended)

First possibility: Build plugin jar via IntelliJ

Steps:

  1. File →  Project Structure
  2. Project Settings → Artifacts → + → jar → From modules with dependencies…
  3. Press ‘OK’
  4. Output Layout Tab → + → File → choose your plugin.json file → press ‘Open’
  5. Change ‘Output directory’ to the location where the plugin jar should be saved
  6. Press ‘OK’ in order to close the window
  7. Build → Build Artifacts… → hover over your created artifact → Build

The plugin jar should be created at your specified output directory.

Second possibility (recommended): Build plugin jar via gradle task

To build a jar with all dependencies included, you need to build a fatJar. The following task will include all dependencies which are added with the ‘compile’ tag (see dependencies section in gradle script). All dependencies that are added with the ‘compileOnly’ tag will only be used for compiling the sources.

In order to add this gradle task to your project add this code snippet to your build.gradle file at the lowest level.

build.gradle
task fatJar(type: Jar) {
    manifest {
        attributes 'Implementation-Title': 'Gradle Jar File Example',
                'Implementation-Version': version,
                'Main-Class': 'PluginStart'
    }
    // Include resources (plugin.json) in jar
    into 'resources', {
        from 'resources'
    }
    // Include compile dependencies in jar
    from {
        configurations.compile.collect { it.isDirectory() ? it : zipTree(it) }
    } {
        exclude "META-INF/*.SF"
        exclude "META-INF/*.DSA"
        exclude "META-INF/*.RSA"
    }
    with jar
}

Execute this gradle task in order to create the jar file of the plugin.

(In Intellij there is a play icon besides the first line of the gradle task declaration. By clicking it you can run the specific gradle task)

After executing the gradle task your plugin jar should be found under “build/libs/”.

Install your plugin

Manual installation

The f irst possibility to debug your plugin is to manually install your plugin like a normal plugin via the plugin user interface in terra (start/plenty-base under the menu point “Plugins”) .

Installation via gradle task

You can install your built plugin from within a gradle task. First, you have to add a gradle plugin called ‘http-builder-ng’. To do so, you have to add the following line to the plugins {} section of your gradle plugin:

id "io.github.http-builder-ng.http-plugin" version "0.1.1"

Hint: If there is no plugins {} section create it in the first line of your gradle file.

After gradle loaded the plugin, you have to add some imports. Add these lines at the first position (line 1) of the gradle script:

build.gradle
        import io.github.httpbuilderng.http.*
        import groovyx.net.http.*
        import static groovyx.net.http.MultipartContent.multipart
    

Now, you can add the following gradle task at the end of your gradle script:

build.gradle
    task installPlugin(type: HttpTask) {
    config {
    request.uri = ' https://local.plentybase.de:7331 '
    }

    post {
    request.uri.path = '/plugin/install'
    request.contentType = 'multipart/form-data'
    request.headers['Authorization'] = 'INSERT YOUR ACCESS TOKEN HERE'
    request.body = multipart {
    field 'activated', 'true'
    part 'plugin', jar.archivePath.name, 'application/java-archive', jar.archivePath
    }

    request.encoder 'multipart/form-data', OkHttpEncoders.&multipart
    request.encoder('application/java-archive') {ChainedHttpConfig config, ToServer req- >
    req.toServer(new ByteArrayInputStream(jar.archivePath.bytes))}
    response.success {
    println "Successful"
    }
    }
    }

Now you can insert your plentyBase access token into the ‘Authorization’ header and run the gradle task.

Debug your plugin

Start plentyBase in debug mode

Follow these steps in order to run plentyBase in debug mode:

Open the root folder of plentyBase:
Windows:        C:\Program Files (x86)\plentyBase
macOS:        /Applications/plentyBase.app/Contents

This folder contains a file named vmoptions.txt. In this file, remove the hashtag (#) from the last line. After you have done this, plentyBase should start in debug mode when you start it.

The ‘suspend’ parameter can be adjusted:
n = Programm starts normally, a remote-debug-connection can be
established  at any time.
y = Programm is waiting after start up until a remote-debug-connection has been established.

Ready:  Now you can debug your plugin in the IntelliJ project of your plugin.

Development Rules

The “PluginStart” class must be in the root package This class also has to extend the “BasePlugin” class from the plenty-base-plugin-dependencies lib.

Use the plenty-base-plugin-dependencies lib by adding this to your gradle file:

build.gradle
        repositories {
                ..
                maven { url "https://jitpack.io" }
        }
        dependencies {
                ..
                compile 'com.github.plentymarkets:plentyBase-plugin-dependencies:lib'
        }
    

Plugin Startup Actions

You can define all startup actions in the “startupPlugin” method of “PluginStart” class.

Events

You can register event listeners by returning them in the “getEventListeners” method of the “PluginStart” class. This should return a map with a string key and a BaseEventListener object as value.

The key  is the name of the event the listener should be registered to.

The value  is the event listener which should be registered for the event.

The returned event listeners will be registered for the specific event name. Events can be triggered by calling the plentyBase event route. (Later, it should be possible to listen to general events like “after print”, “after save”, etc.)

rest route (POST): /events/{key}/    

Servlets

You can register servlets by returning them in the “getServlets” method of the “PluginStart” class. This should return a map with a string key and a common HttpServlet object as value.

The key  is the name of the route the servlet should be registered to.

The value  is the servlet that should be registered for the specific route.

The returned servlets will be registered for the specific routes.

Attention:

Registered servlets are not reachable under the exactly declared route.

Registered servlets are reachable under the following URL: PLENTY_BASE_URL/plugins/PLUGIN_ID/api/DECLARED_ROUTE

PLENTY_BASE_URL is the URL where  plentyBase is reachable. (By default: https://local.plentybase.de )

PLUGIN_ID is the ID of the plugin that wants to register the specific route. (It is declared in the plugin.json file of the plugin.)

DECLARED_ROUTE is the route that you declare as key in the servlet map.