Child pages
  • Creating Client Plugins

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

This page is loosely based on a great manual written by Patrick Talbot (as found on the Servoy forum), and is done so with the author's approval.

Table of Contents
styleupper-roman

Stoc

Client plugins are java classes contained in jar files stored under "/ServoyInstallDir/application_server/plugins/" folder, and by which you can add new features to Servoy Developer.

Plugins can be developed in any Java development environment, like Eclipse for example.

Preliminary settings

  • Create a new Java Project.
  • Add a set of needed Servoy libraries.

    The minimal set of libraries may be found in "/ServoyInstallDir/application_server/lib/" folder, and is the following:
    - j2db.jar
    - j2dbdev.jar
    - js.jar
    - wicket.jar

    Info

    You can define a "User Library" in Window > Preferences which will be available for all future relevant projects. You can name it Servoy, for example.

Example This is an example of a Java project called WhoisPlugin, and the Servoy libraries added to it.

Implementing the plugin

Create a new package under the Java project

A package is a neat way in Java to organize libraries coming from arbitrary sources and make them work together without problems of "Name collision".

...

This is an example of naming a package: com.servoy.plugins.whois  - where 'com.servoy' is a prefix which follows the rule listed above, and 'whois' is the plugin name.

Implement the plugin interface

In order to implement a client plugin, you need to create a class that implements one or more of the three interfaces: IServerPlugin, ISmartClientPlugin, and IClientPlugin.

...

Code Block
public class WhoisPlugin implements IClientPlugin {

    public static final String PLUGIN_NAME = "whois";
    private WhoisPluginProvider provider;
    
    @Override
    public Properties getProperties() {
        Properties props = new Properties();
        props.put(DISPLAY_NAME, getName());
        return props;
    }

    @Override
    public void load() throws PluginException {
        // ignore
    }

    @Override
    public void unload() throws PluginException {
        provider = null;
    }

    @Override
    public void propertyChange(PropertyChangeEvent arg0) {
        // ignore
    }

    @Override
    public IScriptable getScriptObject() {
        if (provider == null) {
            provider = new WhoisPluginProvider();
        } 
        return provider;
    }

    @Override
    public Icon getImage() {
        URL iconUrl = getClass().getResource("images/whois.png"); //the image is added under a package 'com.servoy.plugins.whois.images' added to the WhoisPlugin project.
        if (iconUrl != null) {
            return new ImageIcon(iconUrl);
        } else {
            return null;
        }
    }

    @Override
    public String getName() {
        return PLUGIN_NAME;
    }

    @Override
    public void initialize(IClientPluginAccess arg0) throws PluginException {
        // ignore
    }
}

Implement the script object

The method getStriptObject inherited by IClientPlugin from IScriptableProvider interface, returns the object that will provide the plugin with scripting properties and methods. So, by convention, it is called a Provider.

...

Create a class which implements the two interfaces. This class will provide methods representing the plugin behavior.

Code the plugin main behavior

In order to specify which methods are what, you need to use the JavaDoc annotations system which identifies getter/setter methods for plugin properties, as well as function methods for the plugin functions. The JavaDoc annotation system is also used for documenting the plugin.

...

Note

Make sure you have selected the correct target against which your project is compiled. It needs to be consistent with the Java version your Servoy install is built against. For this, do check Project > Properties > Java Compiler Node > JDK Compliance Panel.

Entry Points

Since the class which implements the IServerPlugin, ISmartClientPlugin or IClientPlugin is one file among many inside your jar, you should indicate which file is the plugin entry point.

...

Code Block
titleMETA-INF/services/com.servoy.j2db.plugins.IPlugin
com.servoy.plugins.whois.WhoisPlugin

Package the plugin

  • Right click on the project and choose Export > Java > JAR file.

  • Click Next

    Note

    You can deselect the .classpath and .project files to avoid polluting your jar with unwanted files only used by Eclipse.

    Select the export destination. You may choose to export the jar directly into your /ServoyInstallDir/application_server/plugins directory.

  • Click Next

    Leave the 2 "Export class files…" checked, and check the "Save the description of this JAR in the workspace". Use the browse button to navigate to your project, and give a name to your definition. Eclipse automatically adds the "jardesc" extension.

    Info

    What is nice about this option is that the next time you will want to deploy your jar (with modified sources for example), all you will have to do is right-click on the file "xxx.jardesc" in the Package explorer and choose "Create JAR" in the menu, with no need to go through all the Export dialogs each time you change something in your plugin.

  • Click Next once more. You may leave it as is, or choose other options.

  • Finish.

Testing the plugin

When opening the Servoy Developer, you should see the plugin under Plugins node in Solution Explorer.

...