[JSF Desktop] is a library to support JSF 2 (2.0, 2.1) with some basic features to extend JSF.
!!!Overview
The main features of the [JSF-Ext] (formerly JSF Desktop) are:
* __Events:__ Event sources and registration. Java beans and components can produce events, other beans and components can consume them. This includes rendering and updating components, even using AJAX requests.
* __Messages:__ Clean message handling. Exceptions are converted to faces messages, using normal or AJAX requests. An event is raised, thus you can update your message components.
* __Dynamic Includes:__ Clean component tree and small network traffic. Facelets can dynamically are loaded from XHTML sources when needed through AJAX requests. No more overloaded component trees, no waiting for loading all the megabytes to your browser. You can include as much popups, tabs and other elements in your page without slowing it down. Everything is just loaded when needed. And much better, its also can be unloaded when finished. Both DOM and component tree stays clean.
* __Custom Scopes:__ Use custom scopes within your loaded facelets, they are cleaned up when finished. No more manual clearing of data from popups. Nice memory footprint and save data.
* __Integration:__ [JSF-Ext] works perfectly together with Richfaces, Primefaces and other component libraries.
!!!Configuration
In the pom.xml use:
{{{
<dependency>
<groupId>com.intersult</groupId>
<artifactId>jsf-desktop</artifactId>
<version>1.1-SNAPSHOT</version>
</dependency>
<repository>
<id>intersult-repository</id>
<name>Intersult Repository</name>
<url>http://repository.intersult.com/repository</url>
</repository>
}}}
In the web.xml use:
{{{
<context-param>
<param-name>javax.faces.FACELETS_RESOURCE_RESOLVER</param-name>
<param-value>com.intersult.jsf_desktop.util.ClassPathResourceResolver</param-value>
</context-param>
}}}
Access via http://localhost/faces/resource/<test.xhtml>
!!!Insert-Tag
The Insert-Tag can insert UIComponent objects into the component tree. This is usefull when creating XHTML-Components with namespace http://java.sun.com/jsf/composite/...
!!Example
Imagin a component which evenly distributes Command-Buttons in a form. You'de like to create a component (luckily this is already included in [JSF Desktop]). The component should wrap each contained component in a SPAN-Tag with some padding.
__Solution:__ You iterate through the children and write a span for each child. Into the span you insert the child itself. With normal JSF-Tags this is not possible, you need <i:insert>
{{{
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:cc="http://java.sun.com/jsf/composite"
xmlns:p="http://primefaces.prime.com.tr/ui"
xmlns:i="http://intersult.com/taglib"
xmlns:dt="http://java.sun.com/jsf/composite/desktop"
>
<cc:interface>
<cc:attribute name="align"/>
</cc:interface>
<cc:implementation>
<div style="margin-top: 10px; text-align: #{empty cc.attrs.align ? 'center' : cc.attrs.align};">
<ui:repeat value="#{cc.children}" var="child">
<span style="margin-right: 5px;">
<i:insert component="#{child}"/>
</span>
</ui:repeat>
</div>
</cc:implementation>
</html>}}}
!!!Events
Events sind eine Erweiterung des Action- und Update-Systems von JSF. Events können von der Java- und XHTML-Seite erzeugt und konsumiert werden.
||Name||Java||Parameter||Beschreibung
|com.intersult.post_construct|Event.EVENT_POST_CONSTRUCT|Object managedBean|Der Event wird nach dem Erzeugen einer managed Bean durch das JSF-System erzeugt.
|com.intersult.pre_destroy|Event.EVENT_PRE_DESTROY|Der Event wird vor dem Entfernen einer managed Bean erzeugt.
|com.intersult.event|Event.EVENT_EVENT|String event, Object... arguments|Dieser Meta-Event wird bei jedem Event erzeugt, sodass allgemeine Event-Handler geschrieben werden können. Dies ist mit Vorsicht zu verwenden.
|com.intersult.messages|MessageHandler.EVENT|-|Der Event wird erzeugt, wenn Faces Messages vorliegen.
|login.before|Login.EVENT_LOGIN_BEFORE|-|Bevor ein Benutzer eingeloggt wird.
|login.success|Login.EVENT_LOGIN_SUCCESS|-|Nachdem ein Benutzer erfolgreich eingeloggt wurde. Der Benutzer ist über Login.instance().getUser() abrufbar.
|login.fail|Login.EVENT_LOGIN_FAIL|-|Nachdem ein Login fehlgeschlagen ist.
|login.after|Login.EVENT_LOGIN_AFTER|-|Nach dem Login-Prozess, unabhängig ob er erfolgreich oder fehlgeschlagen ist.
|login.logout|Login.EVENT_LOGOUT|-|Nach dem Logout.
!!Java
Ein Event wird erzeugt, indem die Instanz von Event geholt wird. Dies kann durch @ManagedProperty("#{event}") geschehen oder durch die statische Methode Event.instance(). Dabei ist zu beachten, dass keine Session scoped Bean in einen Application Context injected wird.
Das Session basierte Event-Objekt enthält die Methode raise(String event, Object... arguments), also im einfachsten Fall:
{{{
Event.instance().raise("com.intersult.some-event");
}}}
Die Events werden in der Regel durch eine Annotation konsumiert:
{{{
@Listener("com.intersult.some-event")
public void someEvent() {
}
}}}
Es ist zu beachten, dass Events nur empfangen werden wenn eine Bean tatsächlich instantiiert ist.
!!XHTML
Events können auch in XHTML verarbeitet werden. Zum Beispiel der vorgefertigte Event com.intersult.messages, der bei vorhandenen Faces-Messages ausgelöst wird:
{{{
<h:messages id="messages" globalOnly="true">
<e:update event="com.intersult.messages"/>
</h:message>
}}}
Ergebnis: Die Faces-Messages werden gerendered, ohne dass bei jedem AJAX-Tag ein gesondertes Rendered-Attribut angegeben werden muss.
!!Raise-Component
Events können hervorragend dazu benutzt werden, um AJAX-Submits und Rerendering voneinander zu trennen. Events werden dabei durch Components erzeugt und von anderen Components konsumiert. So braucht die erzeugende Component zur Erstellungszeit nicht wissen, welche Components rerendered werden:
{{{
<h:commandButton value="Submit">
<f:ajax execute="@form"/>
<e:raise name="com.intersult.test"/>
</h:commandButton>
}}}
Hier ist zu beachten, dass ein AJAX-Tag zusätzlich verwendet wird. Bei vollen GET- oder POST-Requests machen Events keinen Sinn, da hier sowieso die komplette Seite gerendered werden würde.
Das Konsumieren kann wieder auf ähnliche Weise erfolgen:
{{{
<h:outputText id="output" value="#{bean.text}">
<e:update event="com.intersult.test"/>
</h:outputText>
}}}
Es ist zu beachten, dass bei der Update-Component (hier outputText) eine Id angegeben wird, damit der AJAX-Handler das Rerendering zuordnen kann. Dies tritt beim Verwenden des render-Attributs nicht auf, da durch die Angabe einer Id ja eine vergeben wurde.
!!Hinweise
Events sind momentan Session-basiert, das heißt es existieren keine Application übergreifenden Events.
!!!Konfiguration
[JSF Desktop] ist darauf ausgelegt, ohne größere Konfiguration benutzt werden zu können. Viele Features können Out-of-the-Box verwendet werden, sobald sich das jsf-desktop.jar in der Web-Application befindet.
Bei einigen Features und Konstellationen ist es von Vorteil, bestimmte Konfigurationen vorzunehmen.
!!Annotations und InjectionProvider
Wie bereits in [JSF2] erwähnt, werden in einigen Servlet-Containern die Annotations nicht verarbeitet. [JSF Desktop] registriert einen sogenannten InjectionProvider, was im Normalfall transparent funktioniert.
Falls man feststellt, dass die Events im [JSF Desktop] nicht arbeiten, Oberflächenelemente nicht aktualisiert werden und Messages nicht angezeigt werden, dann arbeiten vermutlich auch übliche JSF-Annotations @ManagedBean oder @SessionScoped nicht. Abhilfe schafft dann:
{{{
<context-param>
<param-name>com.sun.faces.injectionProvider</param-name>
<param-value>com.intersult.jsf_ext.event.EventInjectionProvider</param-value>
</context-param>
}}}