Wiki-Quellcode von Plugin-Bundle-Properties

Zeige letzte Bearbeiter
1 {{content/}}
2
3 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.
4
5 Die Bundle-Properties können beispielsweise verwendet werden, um Adressen und Zugangsinformationen von Webservice-Endpoints konfigurierbar zu gestalten.
6
7 Sie eignen sich dafür, bestimmte Plugin-Typen, wie das //IPluginFormPreRender-Plugin //oder das //IPluginServletAction-Plugin//, die selbst über keine eigene Konfigurationsoberfläche in {{formcycle case="dat"/}} verfügen, von außen zu beeinflussen.
8
9 == Definition von Bundle-Properties durch den Plugin-Entwickler ==
10
11 {{figure image="plugin_props_config_ui.png" title="FORMCYCLE Bundle-Properties: Darstellung in Oberfläche" width="500"}}
12 Durch Einbinden des Interfaces //IBundleProperties// können konfigurierbare Optionen in der Oberfläche von {{formcycle case="dat"/}} angezeigt werden.
13 {{/figure}}
14
15 Die Oberfläche von {{formcycle case="dat"/}} bietet die Möglichkeit neue Properties mit Namen und Wert am jeweiligen Plugin-Bundle zu hinterlegen.
16 In den meisten Fällen ist es jedoch sinnvoll, wenn der Name (Zugriffsschlüssel, muss eindeutig innerhalb der Bundle-Properties sein)
17 und gegebenenfalls ein Standard-Wert für ein Property, bereits durch den Plugin-Entwickler festgelegt werden.
18 \\Damit werden zum einen Schreibfehler beim Anlegen der Zugriffsschlüssels durch den Plugin-Benutzer ausgeschlossen und
19 zum Anderen erhält der Plugin-Benutzer eine Sicht auf alle durch den Plugin-Entwickler unterstützten Konfigurationswerte.
20
21 == Schnittstelle IBundleProperties ==
22
23 Die Schnittstelle bietet folgende Methodesignaturen:
24
25 * **//public Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale)//**
26
27 === Methode: //getConfigProperties// ===
28
29 Dient zur Konfiguration von Eigenschaftswerten, die allen Java-Klassen innerhalb des Plugin-Bundles zur Verfügung stehen sollen.
30
31 ==== Übergabewerte: ====
32
33
34 ; IPluginResourceHelper
35 : Objekte zum Zugriff auf die im Plugin-Bundle enthaltenen Datei-Ressourcen.
36 ; Locale
37 : Das für den aktuell angemeldeten Nutzer festgelegte //Locale//-Objekt (enthält Informationen zur Sprache und Region).
38 Dieses kann zum Ermitteln von sprachabhängigen Texten verwendet werden.
39
40 ==== Rückgabewerte: ====
41
42
43 Die Methode muss ein Objekt vom Typ //java.util.Map// mit Value-Objekten vom Typ //IBundleConfigParam// zurückliefern.
44 Es existieren zwei mögliche Implementierung von //IBundleConfigParam//:
45
46 ; BundleConfigGroupItem
47 : Dieses Element kann zur Strukturierung der Listendarstellung in der Oberfläche von {{formcycle case="dat"/}} verwendet werden.
48 ; BundleConfigParam
49 : Dient zur Definition eines Bundle-Properties. Ein Objekt definiert die folgenden Eigenschaften:
50 : //name//
51 :: Der Name oder Zugriffsschlüssel einer Property.
52 : //description//
53 :: 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.
54 : //mandatory//
55 :: 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.
56 : //crypticValue//
57 :: Legt fest, ob der Wert der Property wie bei einem Passwordfeld maskiert werden soll. Standardwert ist {{code}}false{{/code}}.
58 : //defaultValue//
59 :: Ermöglicht die Festlegung eines Defaultwertes durch den Entwickler. Standardwert ist {{code}}null{{/code}}.
60
61 == Implementierungsbeispiel ==
62
63 Das nachfolgende Codebeispiel zeigt eine mögliche Implementierung:
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("Unterstützte Parameter:"));
80 config.put("Parameter1", new BundleConfigParam("Parameter1", "Pflichtparameter im Scope des Plugins mit Defaultwert", true, "Defaultwert"));
81 config.put("Parameter2", new BundleConfigParam("Parameter2", "Pflichtparameter im Scope des Plugins", true));
82 config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter im Scope des Plugins mit Defaultwert", false, "Initialwert"));
83 config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter im Scope des Plugins", false));
84 return config;
85 }
86
87 }
88
89 {{/code}}
90
91 == Zugriff auf Bundle-Properties innerhalb der Plugin-Logik ==
92
93 Der Zugriff auf die Bundle-Properties innerhalb von einzelnen Plugin-Implementierungen wird über die Schnittstelle //IFCPlugin// und deren bereitgestellte Plugin-Lebenszyklus-Methoden gewährleistet.
94 Alle [[Plugin-Typen>>Plugin-Typen||target="_self"]] erben von dieser Schnittstelle, sodass damit in allen Plugin-Implementierungen ein Zugriff auf die Bundle-Properties möglich ist.
95 Diese Klasse liefert mit der Methode //getProperties()// ein //java.util.Properties//-Objekt zurück, was den Zugriff auf die Properties ermöglicht.
96
97 == Beispiele zur Nutzung von Bundle-Properties ==
98
99 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.
100
101 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// {{code}}activate.form.alias{{/code}} aus, welcher die Namen von Formularen mit Komma getrennt enthält, und
102 vergleicht diese mit den Namen des aktuellen Formulars, in dessen Anwendungsbereich der //PreRenderer// gerade ausgeführt wird.
103
104 Wenn der Name des aktuellen Formulars nicht mit einen Namen aus der konfigurierten Liste übereinstimmt, wird die weitere Verarbeitung des PreRenderers abgebrochen.
105
106 {{code language="java" title=""}}
107 public class MyPreRenderer extends AFCPlugin implements IPluginFormPreRender {
108 @Override
109 public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams preRenderParams) throws FCPluginException {
110 // Bundle-Property 'activate.form.alias' auslesen
111 Set<String> alias = getConfiguredFormAlias("activate.form.alias");
112
113 // Ist PreRender-Plugin für aktuelle Formularinstanz freigeschalten?
114 IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)preRenderParams.getFormRequestContext();
115 if(!alias.contains(ctx.getProjekt().getName())) return null;
116
117 // weitere PreRender-Implementierung
118 // ....
119
120 return null;
121 }
122
123 protected Set<String> getConfiguredFormAlias(String propertyName) {
124 String formAlias = getProperties().getProperty(propertyName, null);
125 if(StringUtils.isBlank(formAlias)) {
126 return Collections.emptySet();
127 }
128 String[] arr = StringUtils.split(formAlias, ",");
129 return new HashSet<String>(Arrays.asList(arr));
130 }
131 }
132 {{/code}}

Navigation

Copyright 2000-2025