Changes for page Plugin-Bundle-Properties

From 2.1 to 1.1 From 5.1 to 4.1

From version 4.1

edited by fse
on 20.07.2021, 14:34

Change comment: There is no comment for this version

To version 2.1

edited by fse
on 19.07.2021, 16:11

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,162 +1,89 @@
  {{content/}}
--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.
++Bundle properties are settings a plugin user change change in order to influence or modify the behavior of plugins.
--The bundle properties can be used, for example, to make addresses and access information of web service endpoints configurable.
++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.
--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"/}}.
++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.
--== Definition of bundle properties by the plugin developer ==
++== Setting up bundle properties ==
--{{figure image="plugin_props_config_en.png" title="FORMCYCLE Bundle-Properties: Display in interface" width="500"}}
--By including the //IBundleProperties// interface, configurable options can be displayed in the {{formcycle case="dat"/}} interface.
--{{/figure}}
++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.
--The interface of {{formcycle case="dat"/}} offers the possibility to store new properties with name and value at the respective plug-in bundle.
--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.
--and, if applicable, a default value for a property, are already defined by the plug-in developer.
--\\On the one hand, this eliminates typing errors when the access key is created by the plug-in user, and on the other hand
--on the other hand, the plug-in user receives a view of all configuration values supported by the plug-in developer.
++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.
--
  == Interface IBundleProperties ==
--The interface provides the following method signatures:
++{{figure image="plugin_props_config_en.png"}}
++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/}}.
++{{/figure}}
--{{panel title="{{code language='java'~}~}Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale){{/code~}~}" triggerable="true" fullwidth="true"}}
--(((
--The //getConfigProperties// method is used to configure property values that should be available to all Java classes within the plugin bundle.
--)))
--**Transfer values:**
--(((
--* **IPluginResourceHelper.**
--* **Objects to access the file resources contained in the plugin bundle.**
--* **Locale**
--* **The //Locale// object defined for the currently logged-in user (contains information on the language and region).
--This can be used to determine language-dependent texts.
--)))
++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"/}}.
--**Return values:**
--(((
--The method must return an object of type //java.util.Map// with Value objects of type //IBundleConfigParam//.
--There are two possible implementations of //IBundleConfigParam//:
--)))
++{{formcycle/}} provides two implementing classes of the {{jpath path="de.xima.fc.plugin.config.IBundleConfigParam"/}} interface you can use:
--* **BundleConfigGroupItem**.
--**This item can be used to structure the list display in the {{formcycle case="dat"/}} interface.
--* **BundleConfigParam**.
--** Used to define a bundle property. An object defines the following properties:
--**: //name//
--**:: The name or access key of a property.
--**: //description//
--**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.
--**: //mandatory//
--**:: 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.
--**: //crypticValue//
--**:: Determines whether the value of the property is to be masked as with a password field. Default value is {{code language="none"}}false{/code}}.
--**: //defaultValue//
--**:: Allows the developer to set a default value. Default value is {{code language="none"}}null{/code}}.
++* {{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}}
++* {{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}}
++** {{litem title="name"}}The name used as the key for the property.{{/litem}}
++** {{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}}
++** {{litem title="isMandatory"}}Whether this property is required and a value must be set.{{/litem}}
++** {{litem title="crypticValue"}}Whether the value of the property should be masked, similar to password fields. Defaults to {{code language="none"}}false{{/code}}.{{/litem}}
++** {{litem title="defaultValue"}}A default value for the property when no value has been specified. Defaults to {{code language="none"}}null{{/code}}.{{/litem}}
--{{/panel}}
++{{panel title="Example for an implementation of IBundleProperties" initial="hidden" triggerable="true"}}
--== Implementation example ==
--
--The following code example shows a possible implementation:
--
--{{code language="java" title=""}}
++{{code language="java"}}
  @SuppressWarnings("serial")
--public class MyBundleProperties implements IBundleProperties {
--
--  /**
--   * Returns a map with definitions of bundle configuration parameters. Key is the parameter name, value is a bundle
--   * parameter definition of type {@link IBundleConfigParam}.
--   * @param resHelper ResourceHelper to determine i18n values from the plugin bundle, if they exists.
--   * @param currentLocale the current locale
--   * @return {@link Map} with objects of type {@link IBundleConfigParam} or <code>null</code>.
--   */
--  @Override
--  public Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale) {
++public class MyBundleProperties implements IBundleProperties, Serializable {
++  @Override
++  public Map<String, IBundleConfigParam> getConfigProperties() {
      Map<String, IBundleConfigParam> config = new LinkedHashMap<>();
--    config.put("Group", new BundleConfigGroupItem("Supported parameters:"));
--    config.put("Parameter1", new BundleConfigParam("Parameter1", "Mandatory parameter in scope of plugin with default value", true, "Default value"));
--    config.put("Parameter2", new BundleConfigParam("Parameter2", "Mandatory parameter in the scope of the plug-in", true));
--    config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter in scope of plug-in with default value", false, "Initial value"));
--    config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter in scope of plugin", false));
++    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;
    }
--
  }
--
  {{/code}}
++{{/panel}}
--== Access to bundle properties within the plugin logic ==
++== Retrieving bundle properties ==
--Access to bundle properties within individual plugin implementations is provided via the //IFCPlugin// interface and its provided plugin lifecycle methods.
--All [[Plugin Types>>doc:Formcycle.PluginDevelopment.Types.WebHome]] inherit from this interface, allowing access to bundle properties in all plugin implementations.
++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.
--== Examples for reading bundle properties ==
++== Example for using bundle properties ==
--The following example shows how to access the bundle properties within a //IPluginFormPreRender// implementation.
++An example taken from the //execute// method of a plugin of type [[IPluginFormPreRender>>doc:Formcycle.PluginDevelopment.Types.IPluginFormPreRender]].
--By default, a PreRender plugin is executed on all form calls in the scope of the client in which it was registered.
--For example, if you want the //PreRenderer// to be executed only when certain forms are called, you can make this configurable using //Bundle-Properties//.
--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).
--Then these names are compared with the name of the current form in whose scope the //PreRenderer// is currently running.
--If the name of the current form does not match a name from the configured list, further processing of the PreRenderer is aborted.
++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.
--{{code language="java" title=""}}
--public class MyPreRenderer implements IPluginFormPreRender {
++The plugin will exit when called for a form not part of that list.
--  private Properties bundleProperties = null;
--
--  /**
--   * Name which makes plugin uniquely identifiable.
--   */
++{{code language="java" title=""}}
++public class MyPreRenderer extends AFCPlugin implements IPluginFormPreRender {
    @Override
--  public String getName() {
--    return "My PreRenderer";
--  }
--
--  /**
--   * Plugin lifecycle method, which is called when the object instance is created.
--   */
--  @Override
--  public void initialize(IPluginInitializeData initializeData) throws FCPluginException {
--    bundleProperties = initializeData.getProperties();
--  }
--
--  /**
--   * Method for executing plugin logic.
--   */
--  @Override
--  public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams params) throws FCPluginException {
--    // Read bundle property 'activate.form.alias'.
++  public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams preRenderParams) throws FCPluginException {
++    // Read the bundle property 'activate.form.alias'
      Set<String> alias = getConfiguredFormAlias("activate.form.alias");
--    // Is PreRender plugin enabled for current form instance?
--    IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)params.getFormRequestContext();
--    if (!alias.contains(ctx.getProject().getName())) {
--      // no form activation found -> cancel processing
--      return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
--    }
--
--    // further PreRender implementation
++    // 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 new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
++    return null;
    }
--  /**
--   * Function to determine a bundle property value.
--   * The determined value is separated by a comma
--   * and returned as a HashSet.
--   * @param propertyName
--   * @return a {@link HashSet}
--   */
    protected Set<String> getConfiguredFormAlias(String propertyName) {
--    String formAlias = bundleProperties.getProperty(propertyName, null);
--    if (XStringUtils.isBlank(formAlias)) { return Collections.emptySet(); }
--    String[] arr = XStringUtils.split(formAlias, ",");
++    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));
    }
  }