Plugin bundle properties
Bundle properties are settings a plugin user change change in order to influence or modify the behavior of plugins.
As an example, they can be used to allow the user tho change the address to a web services as well as the necessary login data.
There is a separate user interface for some plugins, eg. IPluginProcessing, for which settings can be set when selecting the plugin as an action type. For some plugin types such as IPluginFormPreRender or IPluginServletAction, there is no special user interface available within Xima® Formcycle. Plugin bundle properties can also be used to pass data to these types of plugins.
Setting up bundle properties
When configuring a plugin, Xima® Formcycle allows the user to add new key-value type properties with arbitrary keys. Unless otherwise required, you should define which keys exist yourself to prevent users from entering incorrect keys. This will always provide the user with an overview of which settings can be set without having to read the the docs, and make the plugin easier to use.
To add bundle properties to your plugin, create a new class that implements the interface IBundleProperties. When uploading the plugin bundle, Xima® Formcycle will search for this class.
Interface IBundleProperties
The interface IBundleProperties contains the method getConfigProperties() that can be used to define the available options for the plugins. This method must return a Map with values of type IBundleConfigParam.
Xima® Formcycle provides two implementing classes of the IBundleConfigParam interface you can use:
BundleConfigGroupItem
Can be used to group several items in the list view of the plugin configuration interface.BundleConfigParam
Defines a plugin bundle property. The following parameters can be passed to the constructor:name
The name used as the key for the property.description
Description for the property. It will be shown when hovering the mouse over the name of the property. Can be used to provide further details on the paramters, or inform the user about allowed values.isMandatory
Whether this property is required and a value must be set.crypticValue
Whether the value of the property should be masked, similar to password fields. Defaults to false.defaultValue
A default value for the property when no value has been specified. Defaults to null.
Example for an implementation of IBundleProperties
public class MyBundleProperties implements IBundleProperties, Serializable {
@Override
public Map<String, IBundleConfigParam> getConfigProperties() {
Map<String, IBundleConfigParam> config = new LinkedHashMap<>();
config.put("Group", new BundleConfigGroupItem("Unterstützte Parameter:"));
config.put("Parameter1", new BundleConfigParam("Parameter1", "Required parameter with default value", true, "default value"));
config.put("Parameter2", new BundleConfigParam("Parameter2", "Required parameter without default value", true));
config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter with default value, not required", false, "initial value"));
config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter with default value, not required", false));
return config;
}
}
Retrieving bundle properties
By extending the abstract class AFCPlugin, you can access the values that have been set for the bundle properties. The method getProperties() return an object of type java.util.Properties that allows you to access the properties.
Example for using bundle properties
An example taken from the execute method of a plugin of type IPluginFormPreRender.
Plugins of this type will be executed when opening a form belonging to the same client for which the plugin has been uploaded. To restrict the plugin to certain forms, you can add a bundle property activate.form.alias that contains a list of comma separated names of forms the plugin should be run for.
The plugin will exit when called for a form not part of that list.
@Override
public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams preRenderParams) throws FCPluginException {
// Read the bundle property 'activate.form.alias'
Set<String> alias = getConfiguredFormAlias("activate.form.alias");
// Check whether the current form is on the white list
IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)preRenderParams.getFormRequestContext();
if(!alias.contains(ctx.getProjekt().getName())) return null;
// Actual plugin logic
// ....
return null;
}
protected Set<String> getConfiguredFormAlias(String propertyName) {
String formAlias = getProperties().getProperty(propertyName, null);
if(StringUtils.isBlank(formAlias)) {
return Collections.emptySet();
}
String[] arr = StringUtils.split(formAlias, ",");
return new HashSet<String>(Arrays.asList(arr));
}
}