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_de.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 {{panel title="{{code language='java'~}~}Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale){{/code~}~}" triggerable="true" fullwidth="true"}}
26 (((
27 Die Methode //getConfigProperties// dient zur Konfiguration von Eigenschaftswerten, die allen Java-Klassen innerhalb des Plugin-Bundles zur Verfügung stehen sollen.
28 )))
29 **Übergabewerte:**
30 (((
31 * **IPluginResourceHelper**
32 ** Objekte zum Zugriff auf die im Plugin-Bundle enthaltenen Datei-Ressourcen.
33 * **Locale**
34 ** Das für den aktuell angemeldeten Nutzer festgelegte //Locale//-Objekt (enthält Informationen zur Sprache und Region).
35 Dieses kann zum Ermitteln von sprachabhängigen Texten verwendet werden.
36 )))
37
38 **Rückgabewerte:**
39 (((
40 Die Methode muss ein Objekt vom Typ //java.util.Map// mit Value-Objekten vom Typ //IBundleConfigParam// zurückliefern.
41 Es existieren zwei mögliche Implementierung von //IBundleConfigParam//:
42 )))
43
44 * **BundleConfigGroupItem**
45 ** Dieses Element kann zur Strukturierung der Listendarstellung in der Oberfläche von {{formcycle case="dat"/}} verwendet werden.
46 * **BundleConfigParam**
47 ** Dient zur Definition eines Bundle-Properties. Ein Objekt definiert die folgenden Eigenschaften:
48 **: //name//
49 **:: Der Name oder Zugriffsschlüssel einer Property.
50 **: //description//
51 **:: 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.
52 **: //mandatory//
53 **:: 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.
54 **: //crypticValue//
55 **:: Legt fest, ob der Wert der Property wie bei einem Passwordfeld maskiert werden soll. Standardwert ist {{code language="none"}}false{{/code}}.
56 **: //defaultValue//
57 **:: Ermöglicht die Festlegung eines Defaultwertes durch den Entwickler. Standardwert ist {{code language="none"}}null{{/code}}.
58
59 {{/panel}}
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 ermöglicht.
94 Alle [[Plugin-Typen>>doc:Formcycle.PluginDevelopment.Types.WebHome]] erben von dieser Schnittstelle, sodass damit in allen Plugin-Implementierungen ein Zugriff auf die Bundle-Properties möglich ist.
95
96 == Beispiele zum Auslesen von Bundle-Properties ==
97
98 Das nachfolgende Beispiel zeigt den Zugriff auf die Bundle-Properties innerhalb einer //IPluginFormPreRender//-Implementierung.
99
100 Ein PreRender-Plugin wird standardmäßig bei allen Formularaufrufen im Scope des Mandanten, in dem er registriert wurde, ausgeführt.
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.
102 Das nachfolgende Beispiel liest in der {{code language="none"}}execute{{/code}} Methode den Wert der //Bundle-Property// {{code language="none"}}activate.form.alias{{/code}} aus, welche die Namen von Formularen (mit Komma getrennt) enthält.
103 Anschließend werden diese Namen mit dem Namen des aktuellen Formulars, in dessen Anwendungsbereich der //PreRenderer// gerade ausgeführt wird, verglichen. 
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 implements IPluginFormPreRender {
108
109 private Properties bundleProperties = null;
110
111 /**
112 * Name, welcher Plugin eindeutig identifizerbar macht.
113 */
114 @Override
115 public String getName() {
116 return "Mein PreRenderer";
117 }
118
119 /**
120 * Plugin-Lebenszyklus-Methode, welche beim Erzeugen der Objekt-Instanz aufgerufen wird.
121 */
122 @Override
123 public void initialize(IPluginInitializeData initializeData) throws FCPluginException {
124 bundleProperties = initializeData.getProperties();
125 }
126
127 /**
128 * Methode zum Ausführen von Plugin-Logik.
129 */
130 @Override
131 public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams params) throws FCPluginException {
132 // Bundle-Property 'activate.form.alias' auslesen
133 Set<String> alias = getConfiguredFormAlias("activate.form.alias");
134
135 // Ist PreRender-Plugin für aktuelle Formularinstanz freigeschalten?
136 IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)params.getFormRequestContext();
137 if (!alias.contains(ctx.getProjekt().getName())) {
138 // keine Formularfreischaltung gefunden -> Verarbeitung abbrechen
139 return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
140 }
141
142 // weitere PreRender-Implementierung
143 // ....
144
145 return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
146 }
147
148 /**
149 * Funktion zum Ermitteln eines Bundle-Property-Wertes.
150 * Der ermittelte Wert wird mittels Komma getrennt
151 * und als HashSet zurückgeliefert.
152 * @param propertyName
153 * @return ein {@link HashSet}
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}}