Wiki source code of Plugin-Bundle-Properties

Show last authors
1 {{content/}}
2
3 The bundle properties offer the plug-in developer the possibility to configure plug-ins externally and thus control the runtime behaviour of the developed plug-ins.
4
5 The bundle properties can be used, for example, to make addresses and access information of web service endpoints configurable.
6
7 They are suitable for externally influencing certain plugin types, such as the //IPluginFormPreRender plugin //or the //IPluginServletAction plugin//, which themselves do not have their own configuration interface in {{formcycle case="dat"/}}.
8
9 == Definition of bundle properties by the plugin developer ==
10
11 {{figure image="plugin_props_config_en.png" title="FORMCYCLE Bundle-Properties: Display in interface" width="500"}}
12 By including the //IBundleProperties// interface, configurable options can be displayed in the {{formcycle case="dat"/}} interface.
13 {{/figure}}
14
15 The interface of {{formcycle case="dat"/}} offers the possibility to store new properties with name and value at the respective plug-in bundle.
16 In most cases, however, it is useful if the name (access key, must be unique within the bundle properties) and, if necessary, a default value for a property are stored.
17 and, if applicable, a default value for a property, are already defined by the plug-in developer.
18 \\On the one hand, this eliminates typing errors when the access key is created by the plug-in user, and on the other hand
19 on the other hand, the plug-in user receives a view of all configuration values supported by the plug-in developer.
20
21
22 == Interface IBundleProperties ==
23
24 The interface provides the following method signatures:
25
26 {{panel title="{{code language='java'~}~}Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale){{/code~}~}" triggerable="true" fullwidth="true"}}
27 (((
28 The //getConfigProperties// method is used to configure property values that should be available to all Java classes within the plugin bundle.
29 )))
30 **Transfer values:**
31 (((
32 * **IPluginResourceHelper**
33 ** Objects to access the file resources contained in the plugin bundle.
34 * **Locale**
35 ** The //Locale// object defined for the currently logged-in user (contains information on the language and region).
36 This can be used to determine language-dependent texts.
37 )))
38 **Return values:**
39 (((
40 The method must return an object of type //java.util.Map// with Value objects of type //IBundleConfigParam//.
41 There are two possible implementations of //IBundleConfigParam//:
42 )))
43
44 * **BundleConfigGroupItem**
45 **This item can be used to structure the list display in the {{formcycle case="dat"/}} interface.
46 * **BundleConfigParam**
47 ** Used to define a bundle property. An object defines the following properties:
48 **: //name//
49 **:: The name or access key of a property.
50 **: //description//
51 **:: Description of a property. Displayed by //mouseover// over the //Property// name in the interface. Can be used to show the user of the plug-in more detailed information on the use or possible value ranges of the parameter.
52 **: //mandatory//
53 **:: Determines whether the parameter is displayed as a mandatory parameter in the interface and whether a validation for the presence of a value is carried out when saving.
54 **: //crypticValue//
55 **:: Determines whether the value of the property is to be masked as with a password field. Default value is {{code language="none"}}false{{/code}}.
56 **: //defaultValue//
57 **:: Allows the developer to set a default value. Default value is {{code language="none"}}null{{/code}}.
58
59 {{/panel}}
60
61 == Implementation example ==
62
63 The following code example shows a possible implementation:
64
65 {{code language="java" title=""}}
66 @SuppressWarnings("serial")
67 public class MyBundleProperties implements IBundleProperties {
68
69 /**
70 * Returns a map with definitions of bundle configuration parameters. Key is the parameter name, value is a bundle
71 * parameter definition of type {@link IBundleConfigParam}.
72 * @param resHelper ResourceHelper to determine i18n values from the plugin bundle, if they exists.
73 * @param currentLocale the current locale
74 * @return {@link Map} with objects of type {@link IBundleConfigParam} or <code>null</code>.
75 */
76 @Override
77 public Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale) {
78 Map<String, IBundleConfigParam> config = new LinkedHashMap<>();
79 config.put("Group", new BundleConfigGroupItem("Supported parameters:"));
80 config.put("Parameter1", new BundleConfigParam("Parameter1", "Mandatory parameter in scope of plugin with default value", true, "Default value"));
81 config.put("Parameter2", new BundleConfigParam("Parameter2", "Mandatory parameter in the scope of the plug-in", true));
82 config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter in scope of plug-in with default value", false, "Initial value"));
83 config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter in scope of plugin", false));
84 return config;
85 }
86
87 }
88
89 {{/code}}
90
91 == Access to bundle properties within the plugin logic ==
92
93 Access to bundle properties within individual plugin implementations is provided via the //IFCPlugin// interface and its provided plugin lifecycle methods.
94 All [[Plugin Types>>doc:Formcycle.PluginDevelopment.Types.WebHome]] inherit from this interface, allowing access to bundle properties in all plugin implementations.
95
96 == Examples for reading bundle properties ==
97
98 The following example shows how to access the bundle properties within a //IPluginFormPreRender// implementation.
99
100 By default, a PreRender plugin is executed on all form calls in the scope of the client in which it was registered.
101 For example, if you want the //PreRenderer// to be executed only when certain forms are called, you can make this configurable using //Bundle-Properties//.
102 The following example reads in the {{code language="none"}}execute{{/code}} method reads the value of the //Bundle-Property// {{code language="none"}}activate.form.alias{{/code}}, which contains the names of forms (separated by commas).
103 Then these names are compared with the name of the current form in whose scope the //PreRenderer// is currently running. 
104 If the name of the current form does not match a name from the configured list, further processing of the PreRenderer is aborted.
105
106 {{code language="java" title=""}}
107 public class MyPreRenderer implements IPluginFormPreRender {
108
109 private Properties bundleProperties = null;
110
111 /**
112 * Name which makes plugin uniquely identifiable.
113 */
114 @Override
115 public String getName() {
116 return "My PreRenderer";
117 }
118
119 /**
120 * Plugin lifecycle method, which is called when the object instance is created.
121 */
122 @Override
123 public void initialize(IPluginInitializeData initializeData) throws FCPluginException {
124 bundleProperties = initializeData.getProperties();
125 }
126
127 /**
128 * Method for executing plugin logic.
129 */
130 @Override
131 public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams params) throws FCPluginException {
132 // Read bundle property 'activate.form.alias'.
133 Set<String> alias = getConfiguredFormAlias("activate.form.alias");
134
135 // Is PreRender plugin enabled for current form instance?
136 IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)params.getFormRequestContext();
137 if (!alias.contains(ctx.getProject().getName())) {
138 // no form activation found -> cancel processing
139 return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
140 }
141
142 // further PreRender implementation
143 // ....
144
145 return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
146 }
147
148 /**
149 * Function to determine a bundle property value.
150 * The determined value is separated by a comma
151 * and returned as a HashSet.
152 * @param propertyName
153 * @return a {@link HashSet}
154 */
155 protected Set<String> getConfiguredFormAlias(String propertyName) {
156 String formAlias = bundleProperties.getProperty(propertyName, null);
157 if (XStringUtils.isBlank(formAlias)) { return Collections.emptySet(); }
158 String[] arr = XStringUtils.split(formAlias, ",");
159 return new HashSet<String>(Arrays.asList(arr));
160 }
161 }
162 {{/code}}