Plugin-Bundle-Properties
Die Bundle-Properties bieten dem Plugin-Entwickler die Möglichkeit Plugins von außen zu konfigurieren und damit das Laufzeitverhalten der entwickelten Plugins zu steuern.
Die Bundle-Properties können beispielsweise verwendet werden, um Adressen und Zugangsinformationen von Webservice-Endpoints konfigurierbar zu gestalten.
Sie eignen sich dafür, bestimmte Plugin-Typen, wie das IPluginFormPreRender-Plugin oder das IPluginServletAction-Plugin, die selbst über keine eigene Konfigurationsoberfläche in Xima® Formcycle verfügen, von außen zu beeinflussen.
Definition von Bundle-Properties durch den Plugin-Entwickler
Die Oberfläche von Xima® Formcycle bietet die Möglichkeit neue Properties mit Namen und Wert am jeweiligen Plugin-Bundle zu pflegen.
In den meisten Fällen ist es jedoch sinnvoll, wenn der Name (Zugriffsschlüssel, muss eindeutig innerhalb der Bundle-Properties sein)
und gegebenenfalls ein Default-Wert für ein Property, bereits durch den Plugin-Entwickler festgelegt werden.
Damit werden zum einen Schreibfehler beim Anlegen der Zugriffsschlüssels durch den Plugin-Benutzer ausgeschlossen und
zum Anderen erhält der Plugin-Benutzer eine Sicht auf alle durch den Plugin-Entwickler unterstützten Konfigurationswerte ohne Dokumentationen lesen zu müssen.
Interface IBundleProperties
Das Interface IBundleProperties bietet mit der Schnittstellen-Methode getConfigProperties() die Möglichkeit Bundle-Properties
vorzukonfigurieren.
Die Methode muss eine Map mit Objekten vom Typ IBundleConfigParam zurückliefern.
Es existieren zwei mögliche Implementierung von IBundleConfigParam:
BundleConfigGroupItem
Dieses Element kann zur Strukturierung der Listendarstellung in der Oberfläche von Xima® Formcycle verwendet werden.BundleConfigParam
Dient zur Definition eines Bundle-Properties. Es können die folgenden Eigenschaften definiert werden.name
Der Name oder Zugriffsschlüssel einer Property.description
Beschreibung zu einer Property. Wird per Mouseover über den Property-Namen in der Oberfläche eingeblendet. Kann verwendet werden, um dem Nutzer des Plugins nähere Information zur Verwendung oder möglicher Wertebereiche des Parameters anzuzeigen.mandatory
Legt fest, ob der Parameter in der Oberfläche als Pflichtparameter dargestellt wird und ein Validierung auf Vorhandensein eines Wertes beim Abspeichern durchgeführt wird.crypticValue
Legt fest, ob der Wert der Property wie bei einem Passwordfeld maskiert werden soll. Standardwert ist false.defaultValue
Ermöglicht die Festlegung eines Defaultwertes durch den Entwickler. Standardwert ist null.
Das nachfolgende Codebeispiel zeigt eine mögliche Implementierung:
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", "Pflichtparameter im Scope des Plugins mit Defaultwert", true, "Defaultwert"));
config.put("Parameter2", new BundleConfigParam("Parameter2", "Pflichtparameter im Scope des Plugins", true));
config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter im Scope des Plugins mit Defaultwert", false, "Initialwert"));
config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter im Scope des Plugins", false));
return config;
}
}
Zugriff auf Bundle-Properties innerhalb der Plugin-Logik
Der Zugriff auf Bundle-Properties innerhalb von Plugins kann über die Einbindung der abstrakten Klasse AFCPlugin erfolgen.
Diese Klasse liefert mit der Methode getProperties() ein java.util.Properties-Objekt zurück, was den Zugriff auf die Properties ermöglicht.
Beispiele zur Nutzung von Bundle-Properties
Ausschnitt aus der execute-Methode einer IPluginFormPreRender-Implementierung. Ein PreRender-Plugin wird standardmäßig bei allen Formularaufrufen im Scope des Mandanten, in dem er registriert wurde, ausgeführt.
Wenn man zum Beispiel möchte, dass der PreRenderer nur beim Aufruf bestimmter Formulare ausgeführt wird, so kann man dies mittels Bundle-Properties konfigurierbar gestalten. Das nachfolgende Codebeispiel liest den Wert der Bundle-Property activate.form.alias aus, welcher die Namen von Formularen mit Komma getrennt enthält, und
vergleicht diese mit den Namen des aktuellen Formulars, in dessen Anwendungsbereich der PreRenderer gerade ausgeführt wird.
Wenn der Name des aktuellen Formulars nicht mit einen Namen aus der konfigurierten Liste übereinstimmt, wird die weitere Verarbeitung des PreRenderers abgebrochen.
@Override
public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams preRenderParams) throws FCPluginException {
// Bundle-Property 'activate.form.alias' auslesen
Set<String> alias = getConfiguredFormAlias("activate.form.alias");
// Ist PreRender-Plugin für aktuelle Formularinstanz freigeschalten?
IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)preRenderParams.getFormRequestContext();
if(!alias.contains(ctx.getProjekt().getName())) return null;
// weitere PreRender-Implementierung
// ....
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));
}
}