Plugins Applications

In the User Interface and Programming chapters we have discussed how to create user interface projects to customize the Web-based GUI and how to develop custom logic using EVENTS, JavaScript and Java. This is the correct approach to the development of one-off customized solutions.

But in some cases you may want to develop general-purpose applications with the intent of reusing them on multiple installations. In this case you would need to bundle both the user interface design and the application code in one package that is easier to distribute and install.

This is exactly what the HSYCO’s plugins framework has been designed for.

There is not much new to learn on order to create a plugin.

Plugins are in fact based on normal index.hsm projects and the standard EVENTS and Java APIs. Only difference is they are bundled in a directory structure that simplifies isolation and deployment of the plugin package. You must also adhere to a specific naming convention for files and sub-directories within your plugin package.

The Directory Structure and Naming Convention

Each plugin has a dedicated sub-directory under the “plugins” directory in HSYCO’s root directory.

The name of that directory is the plugin name.

You should define names carefully, so to avoid naming conflicts with other plugins you may wish to install on the same HSYCO server. 

Besides being the directory name, the plugin name is not relevant for the end user, so even using a complex, long name will not negatively impact the user experience.

A plugin is usually a combination of program logic and user interface, but you can also have plugins that have just a user interface and no server-side logic, or plugins with no user interface, just Java code reacting to system or field events.

EVENTS

You can write plugin-specific EVENTS files in the events subdirectory in your plugin directory.

These events files are just like ordinary events files in the main HSYCO directory, and can contain both events and JavaScript. If you define JavaScript callbacks, the execution order with other EVENTS files declaring the same callback is not guaranteed. If the functions return a value, only the first not null value returned is used as the event return value.

Java

You will write your Java code directly in your plugin directory.

This means that your Java code will have to be in a package named plugins.<directory name>.

The class where you declare your callback code, just like code in user.java, must be public and extend the userBase class.

For example, let’s create a Java class for a plugin named newUser. The callback class file must be declared to be part of the plugins.newUser package, like this:

package plugins.newUser;

import com.hsyco.*;

public class newUser extends userBase {

	public static void StartupEvent() throws Exception {
	}
	
	public static void TimeEvent(long time) throws Exception {
	}	
}

The public class name in this example has been named newUser, just like the plugin’s directory name.

Using the same name is considered a good practice, but is not strictly enforced.

The HSYCO engine looks at all .class files inside each plugin directory, searching one public class with the correct package name and extending userBase.

It will then look in that class only for callback methods.

You can freely add other class files in your plugin directory, as long as they don’t extend userBase.

Besides the package and naming conventions, you can use the same callback and command methods used in user.java.

To check that your plugin’s callbacks are properly defined and discovered by HSYCO, enable the verboseLog option in the system’s general settings, then check the log file. You should see a line for each callback that was correctly registered. Using the example above, the log will be:

2014.02.18 13:19:05.074 - Plugin method StartupEvent() in class plugins.newUser.newUser registered
2014.02.18 13:19:05.077 - Plugin method TimeEvent() in class plugins.newUser.newUser registered

User Interface

The plugin’s user interface consists or one or more regular projects, just like the projects under the main www directory.

In fact, for your convenience, you should use the project editor to create your user interface, then simply move the project directory under the main www to a www directory inside your plugin’s directory.

The project directory will have the index.hsm file and optionally other required files and directories.

The project’s name or names will be used in the URL request to access the user interface, exactly like regular projects.

Precedence

Plugins will coexist with other plugins and with regular projects and application logic in EVENTS, JavaScript and Java.

If a project name exists in the main www directory with the same name of a plugin’s project, it will have priority over the plugin’s project.

The user will see the main project in www, and not the plugin’s user interface.

On the other hand, HSYCO will always execute all defined Java callbacks, in all plugins and in user.java.

The execution order is not guaranteed and your application should be designed to execute properly independently of the execution order.

Anyways, there are a few callback methods that return values, like userCommand(), userSubmit() and a few others.

In these cases HSYCO will always execute the user.java call first, then all plugins’ callbacks, but will use their return value only if the user.java method returns a null or an empty string.

The general rule for plugin callbacks that return values is that they should always return null if they don’t need to intercept the specific event that triggered the call.

This way multiple plugins will be able to coexist without blocking calls to others.

Scope

Because plugins are often designed as self-contained applications, it could be a good design practice to use application scope sessions for the user interface interaction. Read the User Interface section of the Java Command and Utility Methods API chapter for additional information on scope sessions.

When applicable, this will result in more efficient communication between the browser client and the HSYCO server.

Also, user interface objects identifiers should follow a naming convention using a prefix that uniquely identifies the plugin, to avoid potential unwanted conflicts with identifiers used by other applications.

Creating a Plugin Bundle

The most efficient way to create a single file bundle for a plugin is to simply zip the plugin’s directory.

You will distribute the zip file, and simply install it using the file manager to upload it to the main plugins directory.

The file manager will automatically expand the file in place.

 Please note that HSYCO will have to be manually restarted when you upload a new plugin or update an existing one, unless the AutoKillFiles configuration parameter is set to explicitly list all relevant files of the plugin.