Plugin bundle properties - FORMCYCLE Wiki

author	version	line-number	content
1	{{content/}}
2
3	Bundle properties are settings a plugin user change change in order to influence or modify the behavior of plugins.
4
5	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.
6
7	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 {{jpath path="de.xima.fc.interfaces.plugin.retval.form.IPluginFormPreRender"/}} or {{jpath path="de.xima.fc.interfaces.plugin.param.servlet.IPluginServletAction"/}}, there is no special user interface available within {{formcycle/}}. Plugin bundle properties can also be used to pass data to these types of plugins.
8
9	== Setting up bundle properties ==
10
11	When configuring a plugin, {{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.
12
13	To add bundle properties to your plugin, create a new class that implements the interface {{jpath path="de.xima.fc.plugin.config.IBundleProperties"/}}. When uploading the plugin bundle, {{formcycle/}} will search for this class.
14
15	== Interface IBundleProperties ==
16
17	{{figure image="FCSnapshot37.png"}}
18	By implementing the interface {{jpath path="de.xima.fc.plugin.config.IBundleProperties"/}}, all available options for the plugin will be visible when configuring the plugin in {{formcycle/}}.
19	{{/figure}}
20
21	The interface {{jpath path="de.xima.fc.plugin.config.IBundleProperties"/}} contains the method {{code language="none"}}getConfigProperties(){{/code}} that can be used to define the available options for the plugins. This method must return a {{code language="none"}}Map{{/code}} with values of type {{jpath path="de.xima.fc.plugin.config.IBundleConfigParam"/}}.
22
23	{{formcycle/}} provides two implementing classes of the {{jpath path="de.xima.fc.plugin.config.IBundleConfigParam"/}} interface you can use:
24
25	* {{litem title="{{jpath path='de.xima.fc.plugin.models.config.BundleConfigGroupItem'/~}~}"}}Can be used to group several items in the list view of the plugin configuration interface.{{/litem}}
26	* {{litem title="{{jpath path='de.xima.fc.plugin.models.config.BundleConfigParam'/~}~}"}}Defines a plugin bundle property. The following parameters can be passed to the constructor:{{/litem}}
27	** {{litem title="name"}}The name used as the key for the property.{{/litem}}
28	** {{litem title="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.{{/litem}}
29	** {{litem title="isMandatory"}}Whether this property is required and a value must be set.{{/litem}}
30	** {{litem title="crypticValue"}}Whether the value of the property should be masked, similar to password fields. Defaults to {{code language="none"}}false{{/code}}.{{/litem}}
31	** {{litem title="defaultValue"}}A default value for the property when no value has been specified. Defaults to {{code language="none"}}null{{/code}}.{{/litem}}
32
33	{{panel title="Example for an implementation of IBundleProperties" initial="hidden" triggerable="true"}}
34
35	{{code language="java"}}
36	@SuppressWarnings("serial")
37	public class MyBundleProperties implements IBundleProperties, Serializable {
38	@Override
39	public Map<String, IBundleConfigParam> getConfigProperties() {
40	Map<String, IBundleConfigParam> config = new LinkedHashMap<>();
41	config.put("Group", new BundleConfigGroupItem("Unterstützte Parameter:"));
42	config.put("Parameter1", new BundleConfigParam("Parameter1", "Required parameter with default value", true, "default value"));
43	config.put("Parameter2", new BundleConfigParam("Parameter2", "Required parameter without default value", true));
44	config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter with default value, not required", false, "initial value"));
45	config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter with default value, not required", false));
46	return config;
47	}
48	}
49	{{/code}}
50	{{/panel}}
51
52	== Retrieving bundle properties ==
53
54	By extending the abstract class {{jpath path="de.xima.fc.plugin.abstracts.AFCPlugin"/}}, you can access the values that have been set for the bundle properties. The method {{code language="none"}}getProperties(){{/code}} return an object of type //java.util.Properties// that allows you to access the properties.
55
56	== Example for using bundle properties ==
57
58	An example taken from the //execute// method of a plugin of type [[IPluginFormPreRender>>doc:Formcycle.PluginDevelopment.Types.IPluginFormPreRender]].
59
60	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 {{code language="none"}}activate.form.alias{{/code}} that contains a list of comma separated names of forms the plugin should be run for.
61
62	The plugin will exit when called for a form not part of that list.
63
64	{{code language="java" title=""}}
65	public class MyPreRenderer extends AFCPlugin implements IPluginFormPreRender {
66	@Override
67	public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams preRenderParams) throws FCPluginException {
68	// Read the bundle property 'activate.form.alias'
69	Set<String> alias = getConfiguredFormAlias("activate.form.alias");
70
71	// Check whether the current form is on the white list
72	IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)preRenderParams.getFormRequestContext();
73	if(!alias.contains(ctx.getProjekt().getName())) return null;
74
75	// Actual plugin logic
76	// ....
77
78	return null;
79	}
80
81	protected Set<String> getConfiguredFormAlias(String propertyName) {
82	String formAlias = getProperties().getProperty(propertyName, null);
83	if(StringUtils.isBlank(formAlias)) {
84	return Collections.emptySet();
85	}
86	String[] arr = StringUtils.split(formAlias, ",");
87	return new HashSet<String>(Arrays.asList(arr));
88	}
89	}
90	{{/code}}

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.

6

7

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 {{jpath path="de.xima.fc.interfaces.plugin.retval.form.IPluginFormPreRender"/}} or {{jpath path="de.xima.fc.interfaces.plugin.param.servlet.IPluginServletAction"/}}, there is no special user interface available within {{formcycle/}}. Plugin bundle properties can also be used to pass data to these types of plugins.

8

9

== Setting up bundle properties ==

10

11

When configuring a plugin, {{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.

12

13

To add bundle properties to your plugin, create a new class that implements the interface {{jpath path="de.xima.fc.plugin.config.IBundleProperties"/}}. When uploading the plugin bundle, {{formcycle/}} will search for this class.

14

15

== Interface IBundleProperties ==

16

17

18

By implementing the interface {{jpath path="de.xima.fc.plugin.config.IBundleProperties"/}}, all available options for the plugin will be visible when configuring the plugin in {{formcycle/}}.

19

20

21

The interface {{jpath path="de.xima.fc.plugin.config.IBundleProperties"/}} contains the method {{code language="none"}}getConfigProperties(){{/code}} that can be used to define the available options for the plugins. This method must return a {{code language="none"}}Map{{/code}} with values of type {{jpath path="de.xima.fc.plugin.config.IBundleConfigParam"/}}.

22

23

{{formcycle/}} provides two implementing classes of the {{jpath path="de.xima.fc.plugin.config.IBundleConfigParam"/}} interface you can use:

24

25

* {{litem title="{{jpath path='de.xima.fc.plugin.models.config.BundleConfigGroupItem'/~}~}"}}Can be used to group several items in the list view of the plugin configuration interface.{{/litem}}

26

* {{litem title="{{jpath path='de.xima.fc.plugin.models.config.BundleConfigParam'/~}~}"}}Defines a plugin bundle property. The following parameters can be passed to the constructor:{{/litem}}

27

** {{litem title="name"}}The name used as the key for the property.{{/litem}}

28

** {{litem title="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.{{/litem}}

29

** {{litem title="isMandatory"}}Whether this property is required and a value must be set.{{/litem}}

30

** {{litem title="crypticValue"}}Whether the value of the property should be masked, similar to password fields. Defaults to {{code language="none"}}false{{/code}}.{{/litem}}

31

** {{litem title="defaultValue"}}A default value for the property when no value has been specified. Defaults to {{code language="none"}}null{{/code}}.{{/litem}}

32

33

{{panel title="Example for an implementation of IBundleProperties" initial="hidden" triggerable="true"}}

34

35

36

@SuppressWarnings("serial")

37

public class MyBundleProperties implements IBundleProperties, Serializable {

38

@Override

39

public Map<String, IBundleConfigParam> getConfigProperties() {

40

Map<String, IBundleConfigParam> config = new LinkedHashMap<>();

41

config.put("Group", new BundleConfigGroupItem("Unterstützte Parameter:"));

42

config.put("Parameter1", new BundleConfigParam("Parameter1", "Required parameter with default value", true, "default value"));

43

config.put("Parameter2", new BundleConfigParam("Parameter2", "Required parameter without default value", true));

44

config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter with default value, not required", false, "initial value"));

45

config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter with default value, not required", false));

return config;

}

}

== Retrieving bundle properties ==

53

54

By extending the abstract class {{jpath path="de.xima.fc.plugin.abstracts.AFCPlugin"/}}, you can access the values that have been set for the bundle properties. The method {{code language="none"}}getProperties(){{/code}} return an object of type //java.util.Properties// that allows you to access the properties.

55

56

== Example for using bundle properties ==

57

58

An example taken from the //execute// method of a plugin of type [[IPluginFormPreRender>>doc:Formcycle.PluginDevelopment.Types.IPluginFormPreRender]].

59

60

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 {{code language="none"}}activate.form.alias{{/code}} that contains a list of comma separated names of forms the plugin should be run for.

61

62

The plugin will exit when called for a form not part of that list.

63

64

65

public class MyPreRenderer extends AFCPlugin implements IPluginFormPreRender {

66

@Override

67

public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams preRenderParams) throws FCPluginException {

68