Wiki-Quellcode von Widgets

Zeige letzte Bearbeiter
1 {{info}}
2 Nach der Installation von Widgets aus Plugin-Bundles stehen diese im {{designer case="acc"/}} unter der Elementauswahl mit zur Verfügung
3 {{/info}}
4
5 == Schnittstelle IXItemWidget ==
6
7 {{info}}
8 Die Schnittstelle //IXItemWidget// dient zur Definition einer einzelnen Widget-Komponente. Um die Widgets aus einem Plugin-Bundle heraus
9 verfügbar zu machen, ist die Schnittstelle //IPluginFormElementWidget// notwendig, auf die im weiteren Verlauf eingegangen wird.
10 {{/info}}
11
12 === Verwendungsmöglichkeiten ===
13
14 * Erstellung eigener Formular-HTML-Komponenten zur Vereinfachung wiederkehrender Aufgaben (Captcha, Erzeugung von Anzeige-Kacheln mit mehreren Informationen etc.)
15 * Möglichkeit zum Überschreiben der Standard Formular-Elemente mit einer eigenen Implementierung, mit eigener Logik und eigener Validierung
16 * Die Darstellung der durch das Widget bereitgestellten Elemente, kann im Designer und im Formular in Ausführung, unterschieden werden
17
18 === Methodensignaturen ===
19
20 {{panel title="{{code language='java'~}~}void renderItem(Div container, XItemRenderData renderData, XItemRenderCtx renderCtx, IXFormRenderContext formRenderCtx){{/code~}~}" triggerable="true" fullwidth="true"}}
21 (((
22 Methode zum Rendern der HTML-Komponenten, welche durch das Widget bereitgestellt werden.
23 )))
24
25 **Übergabewerte**
26 * **container:** Ein HTML-DIV-Element, welches als Eltern-Element im Formular-Element-Baum dient, in welchen mittels Methodeaufruf von (//container.appendChild(...)//) die eigens erzeugte HTML-Komponente eingefügt werden muss.
27 * **renderData:** Liefert über die Schnittstelle //XItemRenderData// den Zugriff auf die Render-Daten und damit auf:
28 ** die konfigurierten Eigenschaften am Widget (Methode: //getProperties()//). Bei den zurückgelieferten Eigenschaften kann es sich sowohl um eigene, als auch innerhalb der Widget-Implementierung, selbst definierte, Eigenschaften handeln.
29 ** zentrale Eigenschaften des Formulars (Methode: //getXFormRenderConfig()//).
30 ** die aktuell übermittelten Formularwerte (Methode: //getValuesMap()//).
31 Informationen zum Formular
32 * **renderCtx:** Liefert über die Schnittstelle //XItemRenderCtx// den Zugriff auf Methoden zur Unterstützung beim Render-Prozess:
33 ** **registerParent():** Ermöglicht es, die Widget-Komponente so im System zu registrieren, dass sie weiter Unter-Elemente aufnehmen kann
34 ** **addHtmlAttributes():** Reichert das gerenderte HTML-Element mit den definierten Attributen, aus der Attribut-Auflistung an
35 ** **addValidationAttributes():** Fügt alle für die Validierung des HTML-Elements notwendigen Attribute in das gerenderte Element ein
36 * **formRenderCtx:** Bietet Zugriff auf die Form-Request Session-Attribute
37
38 {{/panel}}
39
40 {{panel title="{{code language='java'~}~}default void renderItemPreview(Div container, XItemRenderData renderData, XItemRenderCtx renderCtx, IXFormRenderContext formRenderCtx){{/code~}~} " triggerable="true" fullwidth="true"}}
41 Durch das Implementieren dieser Methode kann ein eigenes Aussehen und Verhalten der gerenderten HTML-Komponenten im Vorschau-Modus bewirkt werden.
42 Wenn eine eigene Implementierung notwendig ist, kann auf die gleichen, wie bei Methode //renderItem(...)// beschriebenen Übergabeparameter zurückgegriffen werden.
43 {{formcycle/}} stellt für diese Methode eine Standardimplementierung bereit.
44 {{/panel}}
45
46 {{panel title="{{code language='java'~}~}ArrayList<XItemPropertyDesc> getAvailableProperties(Locale locale){{/code~}~}" triggerable="true" fullwidth="true"}}
47 Definiert die Liste aller Konfigurations-Eigenschaften, sowohl durch {{formcycle/}} bereitgestellte, als auch selbst definierte, weche das Widget in der Nutzeroberfläche zur Verfügung stellen soll.
48
49 Eine Auflistung aller durch {{formcycle/}} bereitgestellten Eigenschaften bietet die Enumeration //XPropertyEnum//.
50 (((
51 **Übergabewerte:**
52 )))
53 * **locale:** Liefert Informationen zur aktuellen Sprache und Region
54
55 {{/panel}}
56
57 {{panel title="Beispiel-Implementierung für die Methode //getAvailableProperties(...)// mit den gebräuchlichsten Eigenschaften" initial="hidden" triggerable="true" fullwidth="true"}}
58 {{code language="java"}}
59 @Override
60 public ArrayList<XItemPropertyDesc> getAvailableProperties(Locale locale) {
61 ArrayList<XItemPropertyDesc> PROPERTIES = new ArrayList<XItemPropertyDesc>() {
62 {
63 // Basis-Attribute
64 add(new XItemPropertyDesc(XPropertyEnum.name));
65 add(new XItemPropertyDesc(XPropertyEnum.aliasname));
66 add(new XItemPropertyDesc(XPropertyEnum.id));
67 add(new XItemPropertyDesc(XPropertyEnum.parentid));
68 add(new XItemPropertyDesc(XPropertyEnum.rowid));
69 add(new XItemPropertyDesc(XPropertyEnum.flex));
70 add(new XItemPropertyDesc(XPropertyEnum.computedwidth));
71
72 add(new XItemPropertyDesc(XPropertyEnum.textalign));
73 add(new XItemPropertyDesc(XPropertyEnum.cssclasses));
74 add(new XItemPropertyDesc(XPropertyEnum.helptext));
75 add(new XItemPropertyDesc(XPropertyEnum.i18n));
76 add(new XItemPropertyDesc(XPropertyEnum.statusdependent));
77 add(new XItemPropertyDesc(XPropertyEnum.viewstatus));
78 add(new XItemPropertyDesc(XPropertyEnum.usergrouppendent));
79 add(new XItemPropertyDesc(XPropertyEnum.viewusergroup));
80
81 add(new XItemPropertyDesc(XPropertyEnum.readonly_statusdependent));
82 add(new XItemPropertyDesc(XPropertyEnum.readonly_viewstatus));
83 add(new XItemPropertyDesc(XPropertyEnum.readonly_usergrouppendant));
84 add(new XItemPropertyDesc(XPropertyEnum.readonly_viewusergroup));
85
86 // Bedingungen
87 add(new XItemPropertyDesc(XPropertyEnum.isdisabled));
88 add(new XItemPropertyDesc(XPropertyEnum.attributes));
89
90 add(new XItemPropertyDesc(XPropertyEnum.requiredif));
91 add(new XItemPropertyDesc(XPropertyEnum.requiredifcomp));
92 add(new XItemPropertyDesc(XPropertyEnum.requiredifvalue));
93
94 add(new XItemPropertyDesc(XPropertyEnum.readonlyif));
95 add(new XItemPropertyDesc(XPropertyEnum.readonlyifmode));
96 add(new XItemPropertyDesc(XPropertyEnum.readonlyifcomp));
97 add(new XItemPropertyDesc(XPropertyEnum.readonlyifvalue));
98
99 add(new XItemPropertyDesc(XPropertyEnum.hiddenif));
100 add(new XItemPropertyDesc(XPropertyEnum.hiddenifcomp));
101 add(new XItemPropertyDesc(XPropertyEnum.hiddenifvalue));
102
103 add(new XItemPropertyDesc(XPropertyEnum.ishidden));
104 add(new XItemPropertyDesc(XPropertyEnum.isreadonly));
105
106 add(new XItemPropertyDesc(XPropertyEnum.comment));
107 }
108 };
109 return PROPERTIES;
110 }
111 {{/code}}
112 {{/panel}}
113
114 {{panel title="{{code language='java'~}~}boolean isSubmitsValues(){{/code~}~}" triggerable="true" fullwidth="true"}}
115 Mit dieser Methode wird durch einen Rückgabewert //true// festgelegt, dass das Widget zur Laufzeit Formular-Eingaben bereitstellt, welche bei Absenden an den {{formcycle/}}-Server übermittelt werden sollen.
116 {{/panel}}
117
118 {{panel title="{{code language='java'~}~}String getPrefix(){{/code~}~}" triggerable="true" fullwidth="true"}}
119 Definiert ein Präfix, welches dem Element-Namen bei Benutzung im Designer angefügt wird.
120 {{/panel}}
121
122 {{panel title="{{code language='java'~}~}String getLabel(){{/code~}~}" triggerable="true" fullwidth="true"}}
123 Definiert den Namen des Widgets in der Element-Auflistung innerhalb des Designers.
124 {{/panel}}
125
126 {{panel title="{{code language='java'~}~}default XValidationResult validate(List<String[]> values, Locale locale, Map<Serializable, Serializable> frqSessionAttributes){{/code~}~} " triggerable="true" fullwidth="true"}}
127 Mit dieser Methode kann eine Validierung der eingegebene Widget-Element-Werte vorgenommen werden. Bei Fehleingaben kann damit eine Rückmeldung an den Benutzer erfolgen, sowie ein Absenden bei Falsch-Eingabe verhindert werden.
128
129 **Übergabewerte:**
130 * **values:** eine Liste mit den Nutzer-Eingaben aus dem Formular
131 * **locale:** liefert Informationen zur aktuellen Sprache und Region
132 * **frqSessionAttributes:** eine Map mit Werten aus der Formular-Request-Session
133
134 (((
135 **Rückgabewerte:**
136 )))
137 Als Rückgabewert wird ein //XValidationResult//-Objekt erwartet. Diesem Objekt kann beim Instanziieren ein boolscher Wert als Ergebnis des vorhergehenden Validierungsprozesses übergeben werden.
138
139 {{/panel}}
140
141 === Einbindung von JavaScript und CSS-Resourcen im Widget ===
142
143 Widgets können ihre eigenen JavaScript- und CSS-Ressourcen definieren, welche bei der Nutzung des Widgets im Designer und als auch im fertig gerenderten Formular automatisch eingebunden werden. Um dies zu bewerkstelligen müssen die im Widget-Plugin bereitgestellten Ressourcen in einer vordefinierten Ziel-Struktur abgelegt werden.
144
145
146 Für Ressourcen welche beim Benutzen der Widget-Komponente im Designer zur Verfügung stehen sollen, sind folgende Ablagepfade innerhalb des Plugin-JARs vorgeschrieben:
147
148 * für CSS-Resourcen ist der Pfad: **includes/designer/designer-min.js**
149 * für JavaScript-Ressourcen ist der Pfad: **Includes/designer/designer-min.css**
150
151 Bei Ressourcen, welche der Widget-Komponente innerhalb des gerenderten Formulars zur Verfügung stehen sollen, wird eine Einbindung über Widget-Klassennamensgleichheit erreicht.
152
153 * für CSS-Ressourcen ist der Pfad: **includes/css/<//Java-Klassenname der zugrundeliegenden Widget-Implementierung//>.css**
154 Für eine beispielhafte Widget-Implementierung unter dem Klassennamen XMyWidget ergbit sich damit der vollständige Zielpfad: //includes/css/XMyWidget.css//.
155 * für JavaScript-Ressourcen ist der Pfad: **includes/js/<//Java-Klassenname der zugrundeliegenden Widget-Implementierung//>.js**
156 Für eine beispielhafte Widget-Implementierung unter dem Klassennamen XMyWidget ergbit sich damit der vollständige Zielpfad: //includes/js/XMyWidget.js//.
157
158 Um die eingangs beschriebene Zielpfad-Struktur zu erreichen empfiehlt sich der Einsatz von Maven-Plugins, welche innerhalb des Maven Build-Prozesses die gewünschte Dateistruktur anlegen
159 und zusätzlich eine Minifizierung des eingebundenen JavaScripts und CSS bewirken.
160
161 Das nachfolgende Beispiel geht von folgender gegebener Dateistruktur aus:
162
163 [[image:plugin-structure.png||alt="Beispielhafte Projektstruktur"]]
164
165 Ein eingebundenes Maven-Plugin zum Minifizieren der Ressourcen und Herstellung der Zielstruktur kann folgendermaßen aussehen:
166
167 {{panel title="Beispielhafter Ausschnitt aus der POM mit Maven-Plugin-Konfiguration" initial="hidden" triggerable="true" fullwidth="true"}}
168 {{code language="xml"}}
169 ...
170 <build>
171 <plugins>
172 <plugin>
173 <groupId>com.samaxes.maven</groupId>
174 <artifactId>minify-maven-plugin</artifactId>
175 <version>1.7.6</version>
176 <configuration>
177 <charset>UTF-8</charset>
178 <closureWarningLevels>
179 <misplacedTypeAnnotation>OFF</misplacedTypeAnnotation>
180 <es5Strict>OFF</es5Strict>
181 <unknownDefines>OFF</unknownDefines>
182 <nonStandardJsDocs>OFF</nonStandardJsDocs>
183 <uselessCode>OFF</uselessCode>
184 </closureWarningLevels>
185 <jsEngine>CLOSURE</jsEngine>
186 <closureCreateSourceMap>false</closureCreateSourceMap>
187 <closureDefine>
188 <DEFINE_TEST>false</DEFINE_TEST>
189 </closureDefine>
190 <closureLanguageIn>ECMASCRIPT5</closureLanguageIn>
191 <closureLanguageOut>ECMASCRIPT5</closureLanguageOut>
192 <nosuffix>true</nosuffix>
193 <webappSourceDir>/</webappSourceDir>
194 <webappTargetDir>/</webappTargetDir>
195 </configuration>
196 <executions>
197 <!-- Bereitstellung der Ressourcen für die Verwendung im gerenderten Formular -->
198 <execution>
199 <id>default-minify</id>
200 <configuration>
201 <skipMinify>false</skipMinify>
202 <skipMerge>true</skipMerge>
203 <jsSourceDir>${basedir}/src/main/resources/widget/</jsSourceDir>
204 <cssSourceDir>${basedir}/src/main/resources/widget/</cssSourceDir>
205 <jsTargetDir>${project.build.directory}/classes/includes/</jsTargetDir>
206 <cssTargetDir>${project.build.directory}/classes/includes/</cssTargetDir>
207 <jsSourceIncludes>
208 <jsSourceInclude>js/**/*.js</jsSourceInclude>
209 </jsSourceIncludes>
210 <cssSourceIncludes>
211 <cssSourceInclude>css/**/*.css</cssSourceInclude>
212 </cssSourceIncludes>
213 </configuration>
214 <goals>
215 <goal>minify</goal>
216 </goals>
217 </execution>
218
219 <!-- Bereitstellung der CSS-Ressourcen für die Verwendung im Designer -->
220 <execution>
221 <id>default-minify-designer-css</id>
222 <configuration>
223 <skipMinify>false</skipMinify>
224 <skipMerge>false</skipMerge>
225 <jsSourceDir>${basedir}/src/main/resources/widget/</jsSourceDir>
226 <cssSourceDir>${basedir}/src/main/resources/widget/</cssSourceDir>
227 <cssTargetDir>${project.build.directory}/classes/includes/designer/</cssTargetDir>
228 <cssSourceIncludes>
229 <cssSourceInclude>designer/widget.css</cssSourceInclude>
230 </cssSourceIncludes>
231 <cssFinalFile>designer-min.css</cssFinalFile>
232 </configuration>
233 <goals>
234 <goal>minify</goal>
235 </goals>
236 </execution>
237
238 <!-- Bereitstellung der JavaScript-Ressourcen für die Verwendung im Designer -->
239 <execution>
240 <id>default-minify-desiger.js</id>
241 <configuration>
242 <skipMinify>true</skipMinify>
243 <skipMerge>false</skipMerge>
244 <jsSourceDir>${basedir}/src/main/resources/widget/</jsSourceDir>
245 <cssSourceDir>${basedir}/src/main/resources/widget/</cssSourceDir>
246 <jsTargetDir>${project.build.directory}/classes/includes/designer/</jsTargetDir>
247 <jsSourceIncludes>
248 <jsSourceInclude>designer/I18N.js</jsSourceInclude>
249 <jsSourceInclude>designer/Properties.js</jsSourceInclude>
250 <jsSourceInclude>js/XDatalistWidget.js</jsSourceInclude>
251 </jsSourceIncludes>
252 <jsFinalFile>designer-min.js</jsFinalFile>
253 </configuration>
254 <goals>
255 <goal>minify</goal>
256 </goals>
257 </execution>
258 </executions>
259 </plugin>
260 ...
261 </plugins>
262 </build>
263 ...
264 {{/code}}
265 {{/panel}}
266
267 == Schnittstelle IPluginFormElementWidget ==
268
269 Die Schnittstelle //IPluginFormElementWidget// dient zur Bereitstellung von Widget-Komponenten aus einem Plugin-Bundle.
270
271 === Methodensignaturen ===
272
273 Die Plugin-Schnittstelle //IPluginProcessing// referenziert alle durch die [[Basis-Schnittstelle IFCPlugin>>doc:Formcycle.PluginDevelopment.Types.IFCPlugin]] bereitgestellten Methoden
274 und zusätzlich noch folgende Plugin-spezifische Methodensignaturen:
275
276 {{panel title="{{code language='java'~}~}List<Class> getWidgets(Locale locale){{/code~}~}" triggerable="true" fullwidth="true"}}
277
278 **Übergabewerte:**
279 * **loacle:** Liefert Informationen zur aktuellen Sprache und Region
280
281 (((
282 **Rückgabewerte:**
283 )))
284 Als Rückgabewert wird eine Auflistung von //IXItemWidget//-Implementierungsklassen erwartet.
285
286 {{/panel}}