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.
In This Chapter
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.
The minimal set of libraries may be found in "/ServoyInstallDir/application_server/lib/" folder, and is the following:
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.
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".
You can name the package whatever you want, but, by convention, the package hierarchy should reflect your domain name (if you have any) in reverse (from domain to sub-domains). This will avoid name collision with any other libraries, and will spare you from having to type the "fully qualified name" in your code; Eclipse will automatically do that for you.
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.
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.
Before starting coding, do study these interfaces on api docs.
This example shows the implementation of a component which will query a whois server and retrieve whois information about a domain.
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.
A provider implements interfaces IScriptable and IReturnedTypesProvider. Do study them on api docs.
Create a class which implements the two interfaces. This class will provide methods representing the plugin 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.
For a proper understanding of how to use JavaDoc and how to build the documentation of your plugin, see Documenting your plugin Api.
This example shows the implementation of the WhoisPluginProvider - the scriptable object which provides the behavior for the "whois" plugin.
The plugin will expose an overloaded guery method, as well as three other properties: port, server, and timeout.
The main query method contains JavaDoc which provides a description of the function and a sample. The other overloaded methods will display the same description and sample, having them copied via @clonedesc and @sampleas annotations from the main method.
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.
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.
The plugin jar can use Java Service Provider to expose Servoy Plugin classes. There should be a file inside the plugin jar at the path:
META-INF/services/com.servoy.j2db.plugins.IPlugin which contains a line for each class in the jar that implements IPlugin). The plugin should also have a default constructor (with no parameters). If file com.servoy.j2db.plugins.IPlugin is missing or contains invalid entries Servoy will automatically scan the jar for all classes that implement interface IPlugin. An example of file content (for whois plugin) is:
Right click on the project and choose Export > Java > JAR file.
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.
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.
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.
When opening the Servoy Developer, you should see the plugin under Plugins node in Solution Explorer.
Example #1 This example shows how the whois plugin is displayed in the Solution Explorer. Notice the overloaded function query and the three properties.
Example #2 This example shows a small sample solution WhoisTest which tests the whois plugin.
We have a simple test form with two fields based on two form variables domainName and result, and a button Query whois whose action will call the query function.
The Form Editor
The Script Editor
Running Smart Client