Writing a first plugin

In this tutorial, we will explain how to create your first plugin and display it in a layout. Be sure to have activated the plugins by following the Requirements first. For the rest of this documentation, we will designate the directory that contains all the plugins as the root folder and the directory that contains a specific plugin as the plugin folder. There can only be one root folder that may have an unlimited number of plugin folders.

Making a plugin folder

A plugin must be in its own directory, in the root folder. The directory's name can be anything as long as the file system supports it.

We will create a "MyFirstPlugin" directory for this tutorial in the root folder.

mkdir /symlnks/var/es/htmlplugin/MyFirstPlugin

Making a descriptive file

Then, we have to create a file named escmp.xml in this plugin folder. This descriptive file contains the necessary information for the system to load the plugin correctly. If this file is missing or has invalid content, your plugin won't be able to load.

vi /symlnks/var/es/htmlplugin/MyFirstPlugin/escmp.xml

Here is an example of such a file:

<es-plugin
    name="MyPlugin"
    layoutUsage="Job"
    smartviewUsage="Job"
    properties="LongComment" />

For more information about this file and its content, please refer to the Declaration file document.

Implementation of the plugin

Next, we will implement the plugin. To do this, we will create a JavaScript file that contains the necessary code for the plugin to be executed.

vi /symlnks/var/es/htmlplugin/MyFirstPlugin/MyPlugin.js

Here is the content of the file:

var MyPlugin = {
    buildComponent: function() {
        var input = document.createElement('input');
        input.type = 'text';
        input.onchange = function() {
            var val = input.getValue();
            this.setModelProperty('LongComment', val);
        }.bind(this);
        this.input = input;
        return input;
    },
    update: function() {
        var longComment = this.getModelProperty('LongComment');
        this.input.value = longComment;
    },
};

Note:

• It is mandatory to have a variable with the same name as the plugin that contains the implementation of the mixin.
• The functions buildComponent and update are required on the mixin object.
• You can access extra-methods such as this.setModelProperty and this.getModelProperty. Those functions are added to the mixin by the system when generating the plugin.
  

For more information about this file and its content, please refer to the JavaScript Mixin documentation.

Adding a plugin to a layout

The plugin can then be added to a layout in the Administration > Job Ticket Layout > {Your Layout} screen. To add the plugin, drag and drop it from the tree on the right to where you want it in the view tab. The plugin should be in the Plugins folder and appear with its name.

If your plugin does not appear, or the Plugins folder is missing, ensure the layout's Metadata template's property matches the layout usage you have declared in the escmp.xml file. In this tutorial, the Project template must be checked.