Wiki source code of Plugin-Bundle-Properties

Hide last authors

version	line-number	content
1.1	1	{{content/}}
	2
8.1	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.
1.1	4
8.1	5	The bundle properties can be used, for example, to make addresses and access information of web service endpoints configurable.
1.1	6
8.1	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"/}}.
1.1	8
8.1	9	== Definition of bundle properties by the plugin developer ==
1.1	10
8.1	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.
1.1	13	{{/figure}}
	14
8.1	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.
1.1	20
	21
8.1	22	== Interface IBundleProperties ==
1.1	23
8.1	24	The interface provides the following method signatures:
	25
1.1	26	{{panel title="{{code language='java'~}~}Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale){{/code~}~}" triggerable="true" fullwidth="true"}}
	27	(((
8.1	28	The //getConfigProperties// method is used to configure property values that should be available to all Java classes within the plugin bundle.
1.1	29	)))
8.1	30	Transfer values:
1.1	31	(((
	32	* IPluginResourceHelper
8.1	33	** Objects to access the file resources contained in the plugin bundle.
1.1	34	* Locale
8.1	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.
1.1	37	)))
8.1	38	Return values:
1.1	39	(((
8.1	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//:
1.1	42	)))
	43
	44	* BundleConfigGroupItem
8.1	45	**This item can be used to structure the list display in the {{formcycle case="dat"/}} interface.
1.1	46	* BundleConfigParam
8.1	47	** Used to define a bundle property. An object defines the following properties:
1.1	48	**: //name//
8.1	49	**:: The name or access key of a property.
1.1	50	**: //description//
8.1	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.
1.1	52	**: //mandatory//
8.1	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.
1.1	54	**: //crypticValue//
8.1	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}}.
1.1	56	**: //defaultValue//
8.1	57	**:: Allows the developer to set a default value. Default value is {{code language="none"}}null{{/code}}.
1.1	58
	59	{{/panel}}
	60
8.1	61	== Implementation example ==
1.1	62
8.1	63	The following code example shows a possible implementation:
1.1	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}.
8.1	72	* @param resHelper ResourceHelper to determine i18n values from the plugin bundle, if they exists.
1.1	73	* @param currentLocale the current locale
8.1	74	* @return {@link Map} with objects of type {@link IBundleConfigParam} or <code>null</code>.
1.1	75	*/
	76	@Override
	77	public Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale) {
	78	Map<String, IBundleConfigParam> config = new LinkedHashMap<>();
8.1	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));
1.1	84	return config;
	85	}
	86
	87	}
	88
	89	{{/code}}
	90
8.1	91	== Access to bundle properties within the plugin logic ==
1.1	92
8.1	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.
1.1	95
8.1	96	== Examples for reading bundle properties ==
1.1	97
8.1	98	The following example shows how to access the bundle properties within a //IPluginFormPreRender// implementation.
1.1	99
8.1	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.
1.1	105
	106	{{code language="java" title=""}}
	107	public class MyPreRenderer implements IPluginFormPreRender {
	108
	109	private Properties bundleProperties = null;
	110
	111	/**
8.1	112	* Name which makes plugin uniquely identifiable.
1.1	113	*/
	114	@Override
	115	public String getName() {
8.1	116	return "My PreRenderer";
1.1	117	}
	118
	119	/**
8.1	120	* Plugin lifecycle method, which is called when the object instance is created.
1.1	121	*/
	122	@Override
	123	public void initialize(IPluginInitializeData initializeData) throws FCPluginException {
	124	bundleProperties = initializeData.getProperties();
	125	}
	126
	127	/**
8.1	128	* Method for executing plugin logic.
1.1	129	*/
	130	@Override
	131	public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams params) throws FCPluginException {
8.1	132	// Read bundle property 'activate.form.alias'.
1.1	133	Set<String> alias = getConfiguredFormAlias("activate.form.alias");
	134
8.1	135	// Is PreRender plugin enabled for current form instance?
1.1	136	IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)params.getFormRequestContext();
8.1	137	if (!alias.contains(ctx.getProject().getName())) {
	138	// no form activation found -> cancel processing
1.1	139	return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
	140	}
	141
8.1	142	// further PreRender implementation
1.1	143	// ....
	144
	145	return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
	146	}
	147
	148	/**
8.1	149	* Function to determine a bundle property value.
	150	* The determined value is separated by a comma
	151	* and returned as a HashSet.
1.1	152	* @param propertyName
8.1	153	* @return a {@link HashSet}
1.1	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}}