Die Intersult Taglib "meta-ui" ist eine Taglib zur Produktion von Taglibs. Die produzierten Tags sind geeignet für die Entwicklung von JEE-Applikationen unter JSF, Seam, Facelets, Tomahawk und Richfaces. Damit produzieren Sie alle denkbaren Tags in hoher Geschwindigkeit, auch mit Javascript, AJAX, Styles oder Images.
Tag "meta"#
Der wichtigste Tag der Gruppe "com.intersult", Artifact "meta-ui" ist der meta-Tag. Was ist ein Meta-Tag? Das ist ein Tag zur Konstruktion einer Component mittels einer XHTML-Datei mit vollwertigem Id- und Rendering-Verhalten. Der Bau eigener Components wird damit zum Kinderspiel, da in der Regel keine komplizierten Tag-, Renderer- und Handler-Klassen mehr geschrieben werden brauchen. Eine Java-Klasse bauen Sie nur noch, wenn Ihre Komponente ein Datenmodell braucht, also mit dem value-Attribut an einen Wert gebunden wird.Dabei sind Features enthalten, wie Component-Id-Generierung, JSF-Client-Id-Access aus Javascript, Javascript- und CSS-Header-Insertions, Resource-Exposition aus dem JAR, Text-Interpolation (Evaluierung von EL-Expressions) in allen Text-Resources etc. Das Gießen eigener Taglibs ist noch nie so einfach gewesen wie heute!
Attribute#
Der meta-Tag unterstützt einige Attribute:- var: Legt den Variablennamen fest, auf dem die Component-Informationen gebunden werden. Der meta-Tag generiert eine Component-Id und stellt diese unter der unter var angegebenen Variable (hier comp) zur Verfügung. Diese Variable hat zwei Properties:
- id: Innerhalb des meta-Tags kann hier eine Id abgerufen werden und als Zuweisung für eine andere Komponente verwendet werden. Diese Id darf natürlich nur einmal verwendet werden, da die im Component-Tree von JSF eindeutig sein muss. Werden mehrere Ids gebraucht, können diese mit #{comp.id}-suffix erzeugt werden.
- clientId: Innerhalb des meta-Tags kann hier die clientId, als die im HTML-Code tatsächlich heraus generierte Id abgefragt werden. Dies wird vom JavaScript-Code gebraucht.
- parentId: Die JSF-Id des übergeordneten Tags.
- parentClientId: Die ClientId des übergeordneten Tags. Damit ist es möglich, z.B. Javascript-Tags zu bauen, die Aktionen für einen Event durchführen.
- javascriptId: Eine aus der ClientId abgeleitete Id, die für Javascript Variablen und Funktionen benutzt werden kann. Die ClientId kann nicht verwendet werden, da diese Id das Trennzeichen ':' enthält.
- index: Liefert die Position des eigenen Tags im Parent Tag. Damit lassen sich Tabellen einfach mit gestreiftem Muster versehen, erste und letzte Zeile mit besonderem Style versehen etc.
- count: Liefert die Gesamtzahl der Tags im Parent Tag.
- first: Liefert einen boolean-Wert ob der Tag der erste Tag im Parent Tag ist. Damit lassen sich z.B. Header einfärben oder mit anderen Images versehen.
- last: Wie first, nur dass hier auf den letzten Tag geprüft wird.
- get/set: Mit dem generischen getter-/setter-Paar "Object get(String property)" und "void set(String property, Object value)" erhalten man Zugriff auf die UI-Parameter, die an die Komponente übergeben wurden.
- useId: Der meta-Tag generiert eine Id mit dem JSF-Verfahren, falls diese nicht mit useId überschrieben wird. Im Gegensatz zum Zuweisen normaler Ids darf useId="#{id}" benutzt werden, auch wenn die Variable 'id' nicht zugewiesen oder einen Leerstring enthält. Die so gebaute Component arbeitet dann dennoch korrekt mit einer generierten Id.
- rendered: Gibt an ob die Component gerendered wird oder nicht.
- stylesheet: Ein hier angegebener Pfad wird in den Header der HTML-Seite als Link zu einem Stylesheet integriert. Der Link wird dabei nur einmal integriert, auch wenn die Komponente mehrfach auf einer Page verwendet wird. Dies ist vor allem im Zusammenhang mit einer ClassPathResource nützlich.
- javascript: Analog zum Attribut stylesheet wird hier eine Javascript-Datei per Link in den Header der Page eingebunden. Dieser Link wird ebenfalls nur einmal erzeugt und nützlicher Weise mit einer ClassPathResource verknüpft.
- value: Attribut zum Binden an eine EL-Expression, die dann auf der Komponente als Property zur Verfügung steht.
- type: Angabe eines Typs für die Component, standard ist 'com.intersult.ui.tag.meta.Component'. Es kann eine davon abgeleitete Component angegeben werden. Durch hinzufügen von Properties und Methoden können einer Instanz Daten zugeordnet und Funktionen zur Verfügung gestellt werden.
- attribute: Damit kann ein Attribut der Parent Component überschrieben werden, z.B. um einen Javascript-Event hinzuzufügen. Dazu werden ebenfalls das Attribut get spezifiziert, das den Wert enthält, der gesetzt werden soll. Optional kann das Attribut set spezifiziert werden, um den Setter zu überschreiben. Der so erzeugte Tag muss nach A4J- oder Richfaces-Handler gestellt werden, da diese den Handler einfach überschreiben würden. Der meta-Tag hingegen konkateniert die Handler, sodass beide ausgeführt werden.
- get: Dieses Attribut wird zusammen mit attribute verwendet, um ein Attribut der Parent Component zu überschreiben. Wurde mit attribute ein Attribut spezifiziert, muss mit get ein Wert angegeben werden, der beim Lesen des original Attributs der Parent Component geliefert wird. get kann selbst eine EL-Expression sein, dabei ist ein Zugriff auf den Originalwert durch die Variable value möglich. Das Überschreiben des Setters kann durch das Attribut set erfolgen.
- set: Dieses Attribut wird zusammen mit attribute und get verwendet, ist jedoch optional. Wenn mit attribute ein Attribut der Parent Component spezifiziert wurde, wird nicht der originale Wert gesetzt, sondern der unter set spezifizierte. Wie bei get kann es sich hier um eine EL-Expression handelt, der original zu setzende Wert ist unter der Varialbe value zugreifbar.
Beispiel Infobox#
Als Aufgabenstellung soll ein Facelet gebaut werden, das auf einer XHTML-Seite wie folgt eingebaut werden kann:
<i:info id="info" value="Dies ist die Infobox"/>
Die Implementierung erfolgt als Facelet in der Datei info.xhtml:
<ui:composition>
<i:meta useId="#{id}" var="comp" rendered="#{empty rendered or rendered}">
<s:graphicImage id="#{comp.id}" url="#{empty img ? '/images/information.png' : img}"
onmouseover="$('#{comp.clientId}-text').style.display = '';"
onmouseout="$('#{comp.clientId}-text').style.display = 'none';"/>
<s:span id="#{comp.id}-text" style="display: none; position: fixed; background-color: yellow; padding: 3px;">
<h:outputText value="#{value}"/>
</s:span>
</i:meta>
</ui:composition>
Die *.taglib.xml enthält folgenden Eintrag, um das Facelet zu registrieren:
<tag> <tag-name>info</tag-name> <source>/tag/info.xhtml</source> </tag>
Was kann dieser Tag?
- Id-Parameter: Die Id der Facelet-Component verhält sich identisch zu einem in Java entwickelten Tag. Wird keine Id angegeben, wird über den JSF-Mechanismus eine Id generiert. Optional kann eine Id angegeben werden, diese wird dann auch verwendet.
- clientId: Es steht immer die clientId zur Verfügung, sodass beliebiger Code in JavaScript hinzugefügt werden kann. Dieser Code kann ohne Konflikte an mehreren Stellen auf einer XHTML-Seite included werden kann.
- rendered-Attribut: Das Attribut rendered ist etwas tricky, da die Component sowohl gerendered werden muss, wenn rendered nicht angegeben wurde (Prüfung mit empty) als auch wenn rendered="true" angegeben wurde.
- img-Attribut: Das Attribut img ist ebenfalls optional. Der ?-:-Operator prüft, ob das img angegeben wurde, wenn nicht wird als Default-Wert '/images/information.png' eingesetzt. Andernfalls wird der angegebene Wert verwendet.
Als Luxus kann noch eine TLD im Verzeichnis META-INF abgelegt werden, sodass z.B. der Content Assist von Eclipse eine Code Completion für die eben gebaute Component vornehmen kann:
<tag>
<name>info</name>
<tag-class/>
<body-content>empty</body-content>
<description>Renderes a info icon with popup div.</description>
<attribute>
<name>id</name>
<required>false</required>
<rtexprvalue>false</rtexprvalue>
<type>java.lang.String</type>
</attribute>
<attribute>
<name>value</name>
<required>true</required>
<rtexprvalue>false</rtexprvalue>
<type>java.lang.String</type>
<description>Text for popup.</description>
</attribute>
<attribute>
<name>img</name>
<required>false</required>
<rtexprvalue>false</rtexprvalue>
<type>java.lang.String</type>
<description>Optional: Image for the info icon.</description>
</attribute>
<attribute>
<name>rendered</name>
<description>
Flag indicating whether this component (and its children) should be rendered. Expressions must evaluate
to a boolean.
</description>
</attribute>
</tag>
Einschränkungen: Der meta-Tag ist nur mit State-Saving auf dem Server getest, d.h. ohne Serialisierung. Wenn es Probleme gibt, in der web.xml folgende Parameter setzen:
<context-param> <param-name>javax.faces.STATE_SAVING_METHOD</param-name> <param-value>server</param-value> </context-param>
Beispiel Menü#
Eine eigene Menükomponente wird durch die Tage menu und menuItem gebaut. Zunächst wird eine Resource in der components.xml definiert:<component name="resource" class="com.intersult.ui.util.ClassPathResource" scope="application"> <property name="resourcePath">/test</property> <property name="classPath">/de/test/ui/resource</property> </component>
Dann der Tage "menu":
<ui:composition>
<i:meta var="comp" useId="#{id}" rendered="#{empty rendered or rendered}"
stylesheet="#{resource.get('/test.css')}">
<table id="#{comp.clientId}" cellpadding="0" cellspacing="0">
<i:clear var="id,rendered">
<ui:insert/>
</i:clear>
</table>
</i:meta>
</ui:composition>
Und schließlich der Tag "menuItem":
<ui:composition>
<i:meta var="itemComp" useId="#{id}" rendered="#{empty rendered or rendered}"
stylesheet="#{resource.get('/test.css')}">
<tr>
<td class="#{itemComp.last ? 'test-menuL' : 'test-menuI'}"/>
<td class="test-menuContent">
<i:clear var="id,rendered">
<ui:insert/>
</i:clear>
</td>
</tr>
</i:meta>
</ui:composition>
Schließlich wird das Ganze wieder in die test.taglib.xml eingetragen, und in die test.tld, sodass der Content-Assist in der Entwicklungsumgebung den Tag auch anzeigen kann. Die die vorkommenden Styles in die test.css eingetragen. Mit diesen Tags können dann einfach eigene Menüs inklusive beliebig verschachtelter Untermenüs gebaut werden:
<o:menu>
<o:menuItem>
<s:link value="#{msg['menu1']}" action="menu1" propagation="none"/>
</o:menuItem>
<o:menuItem>
<s:link value="#{msg['menu2']}" action="menu2"/>
<o:menu>
<o:menuItem>
<s:link value="#{msg['menu2.1']}" action="home" propagation="none"/>
</o:menuItem>
</o:menu>
</o:menuItem>
</o:menu>
Beispiel Handler#
Es soll ein Tag gebaut werden, der an einen Event-Handler in Javascript hinzugefügt werden kann.
<i:meta var="comp" useId="#{id}" rendered="#{empty rendered or rendered}" attribute="#{event}" get="#{comp.javascriptId}(this); #{value}">
<script type="text/javascript">
function #{comp.javascriptId}() {
<ui:insert/>
}
</script>
</i:meta>
Der Facelet-Taglib-Eintrag:
<tag> <tag-name>setValue</tag-name> <source>/com/intersult/ui/tag/setValue.xhtml</source> </tag>
Und die TLD-Definition:
<tag> <name>setValue</name> <tag-class/> <body-content>empty</body-content> <description>Set a value and call onchange handler</description> <attribute> <name>id</name> </attribute> <attribute> <name>rendered</name> </attribute> <attribute> <name>event</name> <description>Event to set value for</description> </attribute> <attribute> <name>clientId</name> <description>ClientId of the target input html element to set value for.</description> </attribute> <attribute> <name>value</name> <description>Value to apply to target input html element</description> </attribute> </tag>
Der Tag kann nun eingesetzt werden, um z.B. bei einer rich:suggestionbox weitere Felder mit zu befüllen:
<h:inputText id="patient" autocomplete="off"/>
<h:inputText id="gender"/>
<h:inputText id="room"/>
<h:inputText id="patientId"/>
<rich:suggestionbox id="suggest" for="patient" var="suggestion" width="500" height="200"
suggestionAction="#{patient.suggestLabel}" fetchValue="#{patient.label}"
usingSuggestObjects="true" minChars="3">
<i:setValue event="onselect" clientId="#{comp.namingPrefix}gender"
value="#{suggestion.gender}"/>
<i:setValue event="onselect" clientId="#{comp.namingPrefix}room"
value="#{suggestion.room}"/>
<i:setValue event="onselect" clientId="#{comp.namingPrefix}patientId"
value="#{suggestion.id}"/>
<h:column>
<h:outputText value="#{suggestion.label}" escape="false"/>
</h:column>
</rich:suggestionbox>
Beispiel Invertierte Checkbox#
Hat man z.B. eine Modellklasse Article mit einem Property sold und möchte auf der Oberfläche eine Checkbox available anzeigen, ist dies mit JSF nicht möglich. Der Modellklasse möchte man in der Regel keinen transientes getter-/setter-Paar hinzufügen, da keine Business-Logik eingebracht werden soll.Eine sehr einfache Lösung erfolgt mit dem meta-Tag:
<h:selectBooleanCheckbox id="available" value="#{article.sold}">
<i:meta attribute="value" get="#{!value}" set="#{!value}"/>
</h:selectBooleanCheckbox>
Der meta-Tag im Beispiel arbeitet wie folgt:
- Das Attribut attribute="value" legt fest, dass das Attribut value des äußeren Tags selectBooleanCheckbox überschrieben wird.
- Sobald die Component selectBooleanCheckbox auf value zugreift, liefert der meta-Tag stattdessen den Wert des Attributs get zurück, also #{!value}. Die Variable value innerhalb der EL-Expression referenziert dabei den Originalwert #{article.sold}. Durch Einsetzen des Originalwert erhält man #{!article.sold}.
- Wenn die Component selectBooleanCheckbox einen neuen Wert auf value zurückschreibt, wird stattdessen der Wert des Attributs set vom meta-Tag geschrieben, im Beispiel also #{!value}. Die Variable value innerhalb der EL-Expression referenziert hier den Wert, den die Component setzen möchte.
Tag "clear"#
Bei verschachtelter Anwendung des meta-Tags werden Facelet-Parameter unkontrolliert in innere Facelets weiter gegeben. Insbesondere gefährdet ist ui:insert, da hier Facelets generisch eingefügt werden.Dies findet bei ui:include und ui:param ebenso statt, wie bei der Definition von Tags in der Facelets-Taglib. Um dies zu verhindern, steht der Intersult clear-Tag zur Verfügung:
<i:clear var="id,label">
<ui:insert/>
</i:clear>
Was geschieht hier? Der clear-Tag verhindert die weitere Propagierung der UIParameter (also auch Tag-Attribute) "id" und "label".
Beispiel inputGroup#
Das Beispiel soll den Nutzen des clear-Tags verdeutlichen. Zunächst wird ein Tag eingesetzt, der die Gruppierung von Eingabefeldern vornimmt:
<i:inputGroup label="Gruppe">
<i:inputText id="test" value="#{test}"/>
</i:inputGroup>
Die Implementierung der inputGroup ist wie folgt:
<i:meta var="comp" useId="#{id}" rendered="#{empty rendered or rendered}">
<fieldset id="#{comp.clientId}">
<legend>
<h:outputText value="#{label}"/>
</legend>
<i:clear var="id,label">
<ui:insert/>
</i:clear>
</fieldset>
</i:meta>
Die Implementkerung von inputText:
<i:meta var="comp" useId="#{id}" rendered="#{empty rendered or rendered}">
<h:panelGrid>
<h:inputLabel for="#{comp.id"} value="#{empty label ? 'Default' : label}"/>
<h:inputText id="#{comp.id}" value="#{value}"/>
<i:message id="#{comp.id}-message" for="#{comp.id}"/>
</h:panelGrid>
</i:meta>
Der Tag inputText enthält wieder eine Referenz auf die Variable Label. Ohne Verwendung des clear-Tag wäre diese nun auf den äußeren Wert gesetzt, da der inputGroup-Tag den Wert nach innen hinein propagiert.
Tag "inputHidden"#
Dieser Tag ist eine Erweiterung des inputHidden aus der Tomahawk Bibliothek um das Property "from". Selbst in Seam-Projekten werden Informationen aus der Oberfläche, insbesondere bei Listen, als URL-Parameter übergeben. Dies unterwandert das Konzept der Komponenten, da der URL-Parameter dann auf Page-Ebene behandelt wird. Dafür muss zusätzlicher Code geschrieben werden, vermindert die Wartbarkeit und erhöht die Fehleranfälligkeit durch Inkonsistenzen zwischen URL-Parameter und Code-Verarbeitung. Des Weiteren widerstrebt es dem Konzept von meaningful URL und läd zur Manipulation ein.Beispiel#
Folgendes Beispiel zeigt den Einsatz des inputHidden-Tags für ein Steuerelement eines Paging-Mechanismus einer Liste. Es ist ein Mini-Formular mit einem commandLink und dem inputHidden, das den gewünschten Index direkt auf die Liste schreibt.
<h:form>
<h:commandLink action="redirect">#{index}</h:commandLink>
<i:inputHidden value="#{list.firstResult}" from="#{index}"/>
</h:form>
Statt dem h:commandLink kann natürlich auch ein a4j:commandLink benutzt werden.
Tag cell#
Der cell-Tag erlaubt die Generierung klickbarer Tabellen, wie z.B. eines Kalenders. Die herausragende Eigenschaft von <i:cell> ist der Event "onclick". Cell kann innerhalb von table/tr verwendet werden, um Events zu steuern. Insbesondere AJAX-Calls wie durch a4j:support. Im Folgenden ist die "<<"-Taste eines Kalenders dargestellt, der bei einem Kunden produktiv eingesetzt wird (Code aus datenschutzrechtlichen Gründen leicht modifiziert):
<i:cell styleClass="calendar-cell">
<h:outputText value="<<"/>
<a4j:support event="onclick" action="#{comp.page(-3)}" reRender="#{comp.id}-panel"
limitToList="true" ajaxSingle="true"/>
</i:cell>
Tag validator#
Mit dem validator-Tag können Validators anhand EL-Expressions geschrieben werden. Das Schreiben vieler Validator-Classes wird dadurch erspart. Darüber hinaus ist mit dem validator-Tag eine Parametrisierung der Validierung möglich.Beispiel ist ein Validator für zwei Datumswerte, der den Anfang eines Events vor dessen Ende prüft:
<i:inputCalendar value="#{event.from}/>
<i:inputCalendar value="#{event.to}>
<i:validator expression="#{event.from lt value}" message="From before to!"/>
</i:inputCalendar>
ClassPathResource#
Mit dieser Klasse kann ein Resource-Path direkt aus dem ClassLoader in die Web-Applikation exponiert werden. Eine JAR-Datei die sich in einem WAR befindet, hat zunächst keine Möglichkeit auf einen URL zu mappen. Innerhalb eines Facelets aus einer Taglib können zwar URLs erzeugt werden mit h:graphicImage, h:outputLink etc., jedoch keine Dateien als Linkziel exponiert. Die Klasse ClassPathResource exponiert einen Resource-Path mittels eines Eintrag in die components.xml:
<component name="taglibResource" class="com.intersult.ui.util.ClassPathResource" scope="application">
<property name="resourcePath">/taglib</property>
<property name="classPath">/resource</property>
</component>
Die Resourcen sind dann zugreifbar mit:
<t:stylesheet path="#{taglibResource.get('/style.css')}"/>
Alle Resources mit Mime-Type text/* werden dabei interpoliert. Insbesondere CSS-Stylesheets und Javascript-Dateien die durch den meta-Tag geladen werden, können dabei mit EL-Expressions versehen werden. Dies ist z.B. interessant beim Styles vom Typ "background-image", da hier über "url(...)" auf eine Resource zugegriffen wird.
UrlResource#
Web-Sites bestehen heute nicht mehr aus einem einzigen Server, sondern aus einer Infrastruktur mit internen und externen Services. Diese Services können Binärdaten als Stream liefern, z.B. wenn Icons angezeigt werden müssen. Die URLs sind oft aufgrund der Sicherheit oder aus technischen Gründen nicht direkt durchreichbar, werden also über den Web-Server gestreamt.Die Intersult Taglib stellt eine Bean auf Applicationebene zur Verfügung, mit der URLs gestreamt werden können:
<h:graphicImage value="#{urlResource.get(some.bean.url)}"/>
Was macht urlResource.get(...)? Die Methode generiert aus einem URL, der nur innerhalb der Infrastruktur zugreifbar ist einen virtuellen URL auf dem Web-Server. Über diesen URL kann später auf den ursprünglichen URL zugegriffen, also auch gestreamt werden. Der Zugriff ist dabei sicher, da von außen keine URLs generisch erzeugt werden können. Nur im Component-Tree gerendete URLs sind gültig.
ResourceBundle#
Das ResourceBundle ist eine Erweiterung der Resource-Bundles (länder- und sprachspezifisches Laden von *.properties Resourcen) von JSF und Seam um folgende Features:- JAR-Resources: JAR-Dateien können Resources enthalten, die vom verwendenten WAR überschrieben werden können. Eine Taglib kann damit eigene Resources mitliefern.
- Runtime-Loading: Die Resourcen können im laufenden Deployment geändert werden und können sofort zugegriffen werden.
Dazu wird einfach ein Einträge nach folgendem Schema in die components.xml der Taglib-JARs und der Applikation gemacht:
<component name="transportBundles" class="com.intersult.ui.util.ResourceBundle" scope="application" startup="true"> <property name="bundleNames"> <value>transport-messages</value> </property> </component>
Die Resource-Bundles werden dann sauber zusammengeführt und geladen.
Installation#
Maven2 Integration#
Läuft der Build-Prozess in Ihrem Projekt bereits auf Maven2
? Wenn nicht, sollten Sie es sich gründlich überlegen. Der Aufwand zum Einlernen ist sehr gering und der Benefit beim Dependency, Build, Deployment, Distribution, Source Code, Development Environment und andere Prozesse profitieren wesentlich.
Um die Taglib einzubinden, brauchen Sie nur folgende Einträge in Ihrem pom.xml vorzunehmen:
<project>
...
<dependencies>
...
<dependency>
<groupId>com.intersult</groupId>
<artifactId>meta-ui</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
...
</dependencies>
...
<repositories>
...
<repository>
<id>intersult-repository</id>
<name>Intersult Repository</name>
<url>http://repository.intersult.com/repository</url>
</repository>
...
</repositories>
...
</project>
Bei dem Arbeiten mit Eclipse, ist die Taglib nach einem "mvn eclipse:eclipse" und einem Refresh des Projekts verfügbar. Ihnen ist unklar, wie der Content-Assist unter Eclipse für Tags korrekt konfiguriert wird? Wir beantworten gerne diese und weiter Fragen. Nehmen Sie Kontakt mit uns auf.