Wiki-Quellcode von Plugin-Bundle-Properties

Verstecke letzte Bearbeiter

version	line-number	content
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
5.2	11	{{figure image="plugin_props_config_de.png" title="FORMCYCLE Bundle-Properties: Darstellung in Oberfläche" width="500"}}
1.1	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 zur 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}}