Wiki-Quellcode von Plugin-Bundle-Properties

Verstecke letzte Bearbeiter
XIMA Admin 1.1 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
rth 3.3 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.
XIMA Admin 1.1 16 In den meisten Fällen ist es jedoch sinnvoll, wenn der Name (Zugriffsschlüssel, muss eindeutig innerhalb der Bundle-Properties sein)
rth 3.3 17 und gegebenenfalls ein Standard-Wert für ein Property, bereits durch den Plugin-Entwickler festgelegt werden.
XIMA Admin 1.1 18 \\Damit werden zum einen Schreibfehler beim Anlegen der Zugriffsschlüssels durch den Plugin-Benutzer ausgeschlossen und
rth 3.3 19 zum Anderen erhält der Plugin-Benutzer eine Sicht auf alle durch den Plugin-Entwickler unterstützten Konfigurationswerte.
XIMA Admin 1.1 20
rth 3.3 21 == Schnittstelle IBundleProperties ==
XIMA Admin 1.1 22
rth 3.3 23 Die Schnittstelle bietet folgende Methodesignaturen:
XIMA Admin 1.1 24
rth 4.1 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).
rth 3.3 35 Dieses kann zum Ermitteln von sprachabhängigen Texten verwendet werden.
rth 4.1 36 )))
rth 3.3 37
rth 4.1 38 **Rückgabewerte:**
39 (((
rth 3.3 40 Die Methode muss ein Objekt vom Typ //java.util.Map// mit Value-Objekten vom Typ //IBundleConfigParam// zurückliefern.
XIMA Admin 1.1 41 Es existieren zwei mögliche Implementierung von //IBundleConfigParam//:
rth 4.1 42 )))
XIMA Admin 1.1 43
rth 4.1 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//
gru 4.3 55 **:: Legt fest, ob der Wert der Property wie bei einem Passwordfeld maskiert werden soll. Standardwert ist {{code language="none"}}false{{/code}}.
rth 4.1 56 **: //defaultValue//
gru 4.3 57 **:: Ermöglicht die Festlegung eines Defaultwertes durch den Entwickler. Standardwert ist {{code language="none"}}null{{/code}}.
XIMA Admin 1.1 58
rth 4.1 59 {{/panel}}
60
rth 3.3 61 == Implementierungsbeispiel ==
XIMA Admin 1.1 62
63 Das nachfolgende Codebeispiel zeigt eine mögliche Implementierung:
64
65 {{code language="java" title=""}}
66 @SuppressWarnings("serial")
rth 3.2 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) {
XIMA Admin 1.1 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 }
rth 3.2 86
XIMA Admin 1.1 87 }
rth 3.2 88
XIMA Admin 1.1 89 {{/code}}
90
91 == Zugriff auf Bundle-Properties innerhalb der Plugin-Logik ==
92
rth 3.5 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.
rth 3.6 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.
XIMA Admin 1.1 95
rth 3.5 96 == Beispiele zur Auslesen von Bundle-Properties ==
XIMA Admin 1.1 97
rth 3.6 98 Das nachfolgende Beispiel zeigt den Zugriff auf die Bundle-Properties innerhalb einer //IPluginFormPreRender//-Implementierung.
XIMA Admin 1.1 99
rth 3.6 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.
gru 4.3 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.
rth 3.6 103 Anschließend werden diese Namen mit dem Namen des aktuellen Formulars, in dessen Anwendungsbereich der //PreRenderer// gerade ausgeführt wird, verglichen. 
XIMA Admin 1.1 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=""}}
rth 3.6 107 public class MyPreRenderer implements IPluginFormPreRender {
108
109 private Properties bundleProperties = null;
110
111 /**
112 * Name, welcher Plugin eindeutig identifizerbar macht.
113 */
XIMA Admin 1.1 114 @Override
rth 3.6 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 {
XIMA Admin 1.1 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?
rth 3.6 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
XIMA Admin 1.1 142 // weitere PreRender-Implementierung
143 // ....
144
rth 3.6 145 return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
XIMA Admin 1.1 146 }
147
rth 3.6 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 */
XIMA Admin 1.1 155 protected Set<String> getConfiguredFormAlias(String propertyName) {
rth 3.6 156 String formAlias = bundleProperties.getProperty(propertyName, null);
157 if (XStringUtils.isBlank(formAlias)) { return Collections.emptySet(); }
158 String[] arr = XStringUtils.split(formAlias, ",");
XIMA Admin 1.1 159 return new HashSet<String>(Arrays.asList(arr));
160 }
161 }
162 {{/code}}

Navigation

Copyright 2000-2025