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 hinterlegen.
In den meisten Fällen ist es jedoch sinnvoll, wenn der Name (Zugriffsschlüssel, muss eindeutig innerhalb der Bundle-Properties sein)
und gegebenenfalls ein Standard-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.
Schnittstelle IBundleProperties
Die Schnittstelle bietet folgende Methodesignaturen:
Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale)
- IPluginResourceHelper
- Objekte zum Zugriff auf die im Plugin-Bundle enthaltenen Datei-Ressourcen.
- Locale
- Das für den aktuell angemeldeten Nutzer festgelegte Locale-Objekt (enthält Informationen zur Sprache und Region). Dieses kann zum Ermitteln von sprachabhängigen Texten verwendet werden.
- BundleConfigGroupItem
- Dieses Element kann zur Strukturierung der Listendarstellung in der Oberfläche von Xima® Formcycle verwendet werden.
- BundleConfigParam
- Dient zur Definition eines Bundle-Properties. Ein Objekt definiert die folgenden Eigenschaften:
- 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.
- name
- Dient zur Definition eines Bundle-Properties. Ein Objekt definiert die folgenden Eigenschaften:
Implementierungsbeispiel
Das nachfolgende Codebeispiel zeigt eine mögliche Implementierung:
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) {
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 die Bundle-Properties innerhalb von einzelnen Plugin-Implementierungen wird über die Schnittstelle IFCPlugin und deren bereitgestellte Plugin-Lebenszyklus-Methoden ermöglicht.
Alle Plugin-Typen erben von dieser Schnittstelle, sodass damit in allen Plugin-Implementierungen ein Zugriff auf die Bundle-Properties möglich ist.
Beispiele zur Auslesen von Bundle-Properties
Das nachfolgende Beispiel zeigt den Zugriff auf die Bundle-Properties innerhalb 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 Beispiel liest in der execute Methode den Wert der Bundle-Property activate.form.alias aus, welche die Namen von Formularen (mit Komma getrennt) enthält.
Anschließend werden diese Namen mit dem Namen des aktuellen Formulars, in dessen Anwendungsbereich der PreRenderer gerade ausgeführt wird, verglichen.
Wenn der Name des aktuellen Formulars nicht mit einen Namen aus der konfigurierten Liste übereinstimmt, wird die weitere Verarbeitung des PreRenderers abgebrochen.
private Properties bundleProperties = null;
/**
* Name, welcher Plugin eindeutig identifizerbar macht.
*/
@Override
public String getName() {
return "Mein PreRenderer";
}
/**
* Plugin-Lebenszyklus-Methode, welche beim Erzeugen der Objekt-Instanz aufgerufen wird.
*/
@Override
public void initialize(IPluginInitializeData initializeData) throws FCPluginException {
bundleProperties = initializeData.getProperties();
}
/**
* Methode zum Ausführen von Plugin-Logik.
*/
@Override
public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams params) 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)params.getFormRequestContext();
if (!alias.contains(ctx.getProjekt().getName())) {
// keine Formularfreischaltung gefunden -> Verarbeitung abbrechen
return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
}
// weitere PreRender-Implementierung
// ....
return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
}
/**
* Funktion zum Ermitteln eines Bundle-Property-Wertes.
* Der ermittelte Wert wird mittels Komma getrennt
* und als HashSet zurückgeliefert.
* @param propertyName
* @return ein {@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, ",");
return new HashSet<String>(Arrays.asList(arr));
}
}