Seam include un numero di controlli JSF che sono utili per lavorare con Seam. Sono intesi comecomplemento ai controlli predefiniti JSF, e ai controlli di librerie di terze parti. Si raccomanda l'uso in Seam dei tag presenti nelle librerie di JBoss RichFaces, ICEsoft ICEfaces e Apache MyFaces Trinidad. Non si raccomanda l'uso dei tag della libreria Tomahawk.
Per usare questi tag si definisce il namespace "s" nella propria pagina come segue (solo facelets):
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:s="http://jboss.com/products/seam/taglib"
>
L'esempio ui mostra l'uso di diversi tag.
Descrizione
Un pulsante che supporta l'invocazione di un'azione con controllo sulla propagazione della conversazione. Non effettua il submit della form.
Attributi
value— l'etichetta.action— un metodo di binding che specifica l'action listener.view— l'id della vista JSF a cui fare riferimento.fragment— l'identificatore del frammento a cui fare riferimento.disabled— il link è disabilitato?propagation— determina lo stile della propagazione della conversazione:begin,join,nest,noneoend.pageflow— una definizione di pageflow da avviare. (E' utile solamente quando vengono usatipropagation="begin"oppurepropagation="join").
Utilizzo
<s:button id="cancel"
value="Cancel"
action="#{hotelBooking.cancel}"/>
Si possono specificare sia view sia action in <s:link />. In questo caso, l'azione verrà chiamata non appena avviene il redirect alla vista specificata.
L'uso degli action listener (incluso l'action listener di default JSF) non è supportato da <s:button />.
Descrizione
Aggiunge l'id di conversazione al link o bottone JSF (es. <h:commandLink /> , <s:button />).
Attributi
Nessuno
Descrizione
Aggiunge l'id del task all'output link (o controllo JSF simile), quando il task è disponibile via #{task}.
Attributi
Nessuno.
Descrizione
Un link che supporta l'invocazione di un'azione con controllo sulla propagazione della conversazione. Non esegue il submit della form.
L'uso degli action listener (incluso l'action listener di default JSF) non è supportato da <s:link />.
Attributi
value— l'etichetta.action— un metodo di binding che specifica l'action listener.view— l'id della vista JSF a cui fare riferimento.fragment— l'identificatore del frammento a cui fare riferimento.disabled— il link è disabilitato?propagation— determina lo stile della propagazione della conversazione:begin,join,nest,noneoend.pageflow— una definizione di pageflow da avviare. (E' utile solamente quando vengono usatipropagation="begin"oppurepropagation="join").
Utilizzo
<s:link id="register" view="/register.xhtml"
value="Register New User"/>
Si possono specificare sia view sia action in <s:link />. In questo caso, l'azione verrà chiamata non appena avviene il redirect alla vista specificata.
Descrizione
Personalizza la propagazione della conversazione per un command link/button (o controllo JSF simile). Solo Facelets.
Attributi
type— determina lo stile della propagazione della conversazione:begin,join,nest,noneoppureend.pageflow— una definizione di pageflow da avviare. (E' utile solamente quando vengono usatipropagation="begin"oppurepropagation="join").
Utilizzo
<h:commandButton value="Apply" action="#{personHome.update}">
<s:conversationPropagation type="join" />
</h:commandButton
>
Descrizione
Specifica l'azione di default daeseguire quando viene fatto il submit della form usando il tasto invio.
Attualmente lo si può innestare solo dentro i pulsanti (es. <h:commandButton />, <a:commandButton /> o <tr:commandButton />).
Occorre specificare un id sulla sorgente d'azione. Si può avere soltanto un'azione di default per form.
Attributi
Nessuno.
Utilizzo
<h:commandButton id="foo" value="Foo" action="#{manager.foo}">
<s:defaultAction />
</h:commandButton
>
Descrizione
Esegue conversioni di data o orario nella timezone di Seam.
Attributi
Nessuno.
Utilizzo
<h:outputText value="#{item.orderDate}">
<s:convertDateTime type="both" dateStyle="full"/>
</h:outputText
>
Descrizione
Assegna un entity converter al componente corrente. Questo è utile per pulsanti radio e controlli dropdown.
Il converter funziona con qualsiasi entity gestita - sia semplice che composta. Il converter deve essere in grado di trovare gli item dichirati nei controlli JSF durante la sottomissione della form, altrimenti si riceverà un errore di validazione.
Attributi
Nessuno.
Configurazione
Si devono usare le transazioni di Seam gestite (vedere Sezione 9.2, «Transazioni gestite da Seam») con <s:convertEntity />.
Se il Managed Persistence Context non viene chiamato entityManager, allora occorre impostarlo in components.xml:
<components xmlns="http://jboss.com/products/seam/components"
xmlns:ui="http://jboss.com/products/seam/ui">
<ui:jpa-entity-loader entity-manager="#{em}" />Se si usa una Managed Hibernate Session allora occorre impostarla in components.xml:
<components xmlns="http://jboss.com/products/seam/components"
xmlns:ui="http://jboss.com/products/seam/ui">
<ui:hibernate-entity-loader />Se il Managed Hibernate Session non viene chiamato session, allora occorre impostarla in components.xml:
<components xmlns="http://jboss.com/products/seam/components"
xmlns:ui="http://jboss.com/products/seam/ui">
<ui:hibernate-entity-loader session="#{hibernateSession}" />Se si vuole usare più di un entity manager con l'entity converter, si può creare una copia dell'entity converter per ciascun entity manager in components.xml - si noti come l'entity converter deleghi all'entity loader l'esecuzione delle operazioni di persistenza:
<components xmlns="http://jboss.com/products/seam/components"
xmlns:ui="http://jboss.com/products/seam/ui">
<ui:entity-converter name="standardEntityConverter" entity-loader="#{standardEntityLoader}" />
<ui:jpa-entity-loader name="standardEntityLoader" entity-manager="#{standardEntityManager}" />
<ui:entity-converter name="restrictedEntityConverter" entity-loader="#{restrictedEntityLoader}" />
<ui:jpa-entity-loader name="restrictedEntityLoader" entity-manager="#{restrictedEntityManager}" /><h:selectOneMenu value="#{person.continent}">
<s:selectItems value="#{continents.resultList}" var="continent"
label="#{continent.name}" />
<f:converter converterId="standardEntityConverter" />
</h:selectOneMenu
>Utilizzo
<h:selectOneMenu value="#{person.continent}" required="true">
<s:selectItems value="#{continents.resultList}" var="continent"
label="#{continent.name}"
noSelectionLabel="Please Select..."/>
<s:convertEntity />
</h:selectOneMenu
>
Descrizione
Assegna un enum converter al componente corrente. Questo è utile per i pulsanti radio e i controlli dropdown.
Attributi
Nessuno.
Utilizzo
<h:selectOneMenu value="#{person.honorific}">
<s:selectItems value="#{honorifics}" var="honorific"
label="#{honorific.label}"
noSelectionLabel="Please select" />
<s:convertEnum />
</h:selectOneMenu
>
Descrizione
javax.faces.convert.Converter for java.util.concurrent.atomic.AtomicBoolean.
Attributi
Nessuno.
Utilizzo
<h:outputText value="#{item.valid}">
<s:convertAtomicBoolean />
</h:outputText
>Descrizione
javax.faces.convert.Converter for java.util.concurrent.atomic.AtomicInteger.
Attributi
Nessuno.
Utilizzo
<h:outputText value="#{item.id}">
<s:convertAtomicInteger />
</h:outputText
>Descrizione
javax.faces.convert.Converter for java.util.concurrent.atomic.AtomicLong.
Attributi
Nessuno.
Utilizzo
<h:outputText value="#{item.id}">
<s:convertAtomicLong />
</h:outputText
>Descrizione
Tag da innestare dentro un controllo 'input per validare che il valore del suo padre sia uguale (o non uguale!) al valore del controllo referenziato.
Attributi
for— L'id di un controllo da validare.message— Messaggio da mostrare in presenza di errori.required— False disabiliterà un controllo per cui un valore viene inserito nei campi.messageId— L'id del messaggio da mostrare in presenza di errori.operator— Quale operatore usare quando si comparano i valori. Gli operatori sono:equal— Valida che value.equals(forValue)not_equal— Valida che !value.equals(forValue)greater— Valida che sia ((Comparable)value).compareTo(forValue) > 0greater_or_equal— Valida che sia ((Comparable)value).compareTo(forValue) >= 0less— Valida che sia ((Comparable)value).compareTo(forValue) <0less_or_equal— Valida che sia ((Comparable)value).compareTo(forValue) <= 0
Utilizzo
<h:inputText id="name" value="#{bean.name}"/>
<h:inputText id="nameVerification" >
<s:validateEquality for="name" />
</h:inputText
>Descrizione
Un controllo non visuale, valida un campo d'input JSF con la proprietà collegata usando Hibernate Validator.
Attributi
Nessuno.
Utilizzo
<h:inputText id="userName" required="true"
value="#{customer.userName}">
<s:validate />
</h:inputText>
<h:message for="userName" styleClass="error" />
Descrizione
Un controllo non visuale, valida tutti i campi d'input JSF con le proprietà collegate usando Hibernate Validator.
Attributi
Nessuno.
Utilizzo
<s:validateAll>
<div class="entry">
<h:outputLabel for="username"
>Username:</h:outputLabel>
<h:inputText id="username" value="#{user.username}"
required="true"/>
<h:message for="username" styleClass="error" />
</div>
<div class="entry">
<h:outputLabel for="password"
>Password:</h:outputLabel>
<h:inputSecret id="password" value="#{user.password}"
required="true"/>
<h:message for="password" styleClass="error" />
</div>
<div class="entry">
<h:outputLabel for="verify"
>Verify Password:</h:outputLabel>
<h:inputSecret id="verify" value="#{register.verify}"
required="true"/>
<h:message for="verify" styleClass="error" />
</div>
</s:validateAll
>
Descrizione
"Decora" un campo d'input JSF quando la validazione fallisce o quando è impostato required="true".
Attributi
template— il template facelets da usare per decorare il componenteenclose— se true, il template usato per decorare il campo d'input è racchiuso dall'elemento specificato con l'attributo "element". Di default questo è un elemento div.element— l'elemento con cui racchiudere il template usato per decorare il campo d'input. Di default, il template è racchiuso con un elemento div.
#{invalid} e #{required} sono disponibili dentro s:decorate; #{required} valuta true se si è impostato il componente input da decorare come richiesto, e #{invalid} valuta true se avviene un errore di validazione.
Utilizzo
<s:decorate template="edit.xhtml">
<ui:define name="label"
>Country:</ui:define>
<h:inputText value="#{location.country}" required="true"/>
</s:decorate
>
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:s="http://jboss.com/products/seam/taglib">
<div
>
<s:label styleClass="#{invalid?'error':''}">
<ui:insert name="label"/>
<s:span styleClass="required" rendered="#{required}"
>*</s:span>
</s:label>
<span class="#{invalid?'error':''}">
<s:validateAll>
<ui:insert/>
</s:validateAll>
</span>
<s:message styleClass="error"/>
</div
>
</ui:composition
>
Descrizione
Generare un <div> HTML.
Attributi
Nessuno.
Utilizzo
<s:div rendered="#{selectedMember == null}">
Sorry, but this member does not exist.
</s:div
>
Descrizione
Generare un <span> HTML.
Attributi
title— Fornisce un titolo per uno span.
Utilizzo
<s:span styleClass="required" rendered="#{required}" title="Small tooltip"
>*</s:span
>
Descrizione
Un componente non -rendering utile per abilitare/disabilitare il rendering dei suoi figli.
Attributi
Nessuno.
Utilizzo
<s:fragment rendered="#{auction.highBidder ne null}">
Current bid:
</s:fragment
>
Descrizione
"Decora" un campo d'input JSF con l'etichetta. L'etichetta è messa dentro il tag HTML <label>, ed è associato al componente d'input JSF più vicino. E' spesso usato con <s:decorate>.
Attributi
style— Lo stile del controllostyleClass— La classe di stile del controllo
Utilizzo
<s:label styleClass="label">
Country:
</s:label>
<h:inputText value="#{location.country}" required="true"/>
Descrizione
Controlla che il valore inviato sia un Testo Seam valido.
Attributi
Nessuno.
Descrizione
Mostra come output Seam Text, un markup di testo utile per blog, wiki ed altre applicazioni che possono usare rich text. Vedere il capitolo di Seam Text per ulteriori informazioni.
Attributi
value— un'espressione EL che specifica il markup del testo rich da renderizzare.
Utilizzo
<s:formattedText value="#{blog.text}"/>
Esempio
Descrizione
Produce un token casuale che viene inserito in un campo di form nascosta per aiutare rendere sicuro i post della form JSF contro attacchi cross-site request forgery (XSRF). Si noti che il browser deve avere abilitati i cookie per poter eseguire il submit delle form che includono questo componente.
Attributi
requireSession— indica se l'id di sessione debba essere incluso nella signature della form, da qui il binding del token alla sessione. Questo valore può essere impostato a false se viene attivata la modalità "build before restore" dei Facelets (di default in JSF 2.0). (Default: false)enableCookieNotice— indica che deve essere inserito nella pagina un check JavaScript per verificare che i cookie siano abilitati nel browser. Se i cookie non sono abilitati, viene presentata all'utente una nota riportante che l'invio della form non è avvenuto. (Default: false)allowMultiplePosts— indica se consentire che la stessa form venga inviata più volte con la stessa signature (finché non cambia la vista). Questa è una necessità comune se la form esegue chiamate Ajax ma non rigenera se stessa o, almeno, il componente UIToken. L'approccio migliore è avere il componente UIToken rigenerato su ogni chiamata Ajax in cui il componente UIToken viene processato. (Default: false)
Utilizzo
<h:form>
<s:token enableCookieNotice="true" requireSession="false"/>
...
</h:form
>
Descrizione
Crea un SelectItem da un valore enum.
Attributi
enumValue— la rappresentazione stringa di un valore enum.label— l'etichetta da usare per renderizzare ilSelectItem.
Utilizzo
<h:selectOneRadio id="radioList"
layout="lineDirection"
value="#{newPayment.paymentFrequency}">
<s:convertEnum />
<s:enumItem enumValue="ONCE" label="Only Once" />
<s:enumItem enumValue="EVERY_MINUTE" label="Every Minute" />
<s:enumItem enumValue="HOURLY" label="Every Hour" />
<s:enumItem enumValue="DAILY" label="Every Day" />
<s:enumItem enumValue="WEEKLY" label="Every Week" />
</h:selectOneRadio
>
Descrizione
Crea una List<SelectItem> daList, Set, DataModel o Array.
Attributi
value— un'espressione EL che specifica i dati retrostanti aList<SelectItem>var— definisce il nome della variabile locale che mantiene l'oggetto corrente durante l'iterazionelabel— l'etichetta da usare per generareSelectItem. Può fare riferimento alla variabilevar.itemValue— Il valore da restituire al server se quest'opzione è selezionata. E' opzionale, di default viene usato l'oggettovar. Può fare riferimento alla variabilevar.disabled— se true ilSelectItemverrà generato disabilitato. Può fare riferimento alla variabilevar.noSelectionLabel— specifica l'etichetta (opzionale) da mettere in cima alla lista (se è specificato ancherequired="true"allora selezionando questo valore può causare una validazione d'errore).hideNoSelectionLabel— se true,noSelectionLabelverrà nascosto quando viene selezionato il valore.
Utilizzo
<h:selectOneMenu value="#{person.age}"
converter="ageConverter">
<s:selectItems value="#{ages}" var="age" label="#{age}" />
</h:selectOneMenu
>
Descrizione
Renderizza un controllo per l'upload del file. Questo controllo deve essere usato dentro la form con tipo di codifica multipart/form-data, cioè:
<h:form enctype="multipart/form-data"
>
Per richieste multiple, in web.xml deve essere configurato il filtro servlet Seam Multipart :
<filter>
<filter-name
>Seam Filter</filter-name>
<filter-class
>org.jboss.seam.servlet.SeamFilter</filter-class>
</filter>
<filter-mapping>
<filter-name
>Seam Filter</filter-name>
<url-pattern
>/*</url-pattern>
</filter-mapping
>
Configurazione
Le seguenti opzioni di configurazioni per richieste multipart possono essere configurate in components.xml:
createTempFiles— se quest'opzione è impostata a true, i file caricati vengono accodati in un file temporaneo invece che in memoria.maxRequestSize— dimensione massima della richiesta di upload file, in byte.
Ecco un esempio:
<component class="org.jboss.seam.web.MultipartFilter">
<property name="createTempFiles"
>true</property>
<property name="maxRequestSize"
>1000000</property>
</component
>
Attributi
data— questo value binding riceve i dati binari. Il campo ricevente deve essere dichiarato comebyte[]oInputStream(richiesto).contentType— questo value binding riceve il contenuto del file (opzionale).fileName— questo value binding riceve il nome del file (opzionale).fileSize— questo valore di binding riceve la dimensione del file (opzionale).accept— una lista separata da virgola con i tipi di contenuto da accettare, può non essere supportata dal browser. Esempio:"images/png,images/jpg","images/*".style— Lo stile del controllostyleClass— La classe di stile del controllo
Utilizzo
<s:fileUpload id="picture" data="#{register.picture}"
accept="image/png"
contentType="#{register.pictureContentType}" />
Descrizione
Mette nella cache il frammento di pagina renderizzato usando JBoss Cache. Si noti che <s:cache> in verità usa l'istanza di JBoss Cache gestita dal componente predefinito pojoCache.
Attributi
key— la chiave per memorizzare (cache) il contenuto renderizzato, spesso un'espressione di valore. Per esempio, se si mette nella cache un frammento di pagina che mostra un documento, si può usarekey—enabled— un'espressione di valore che determina se la cache debba essere usata.region— un node JBoss Cache da usare (nodi differenti possono avere differenti policy di scadenza).
Utilizzo
<s:cache key="entry-#{blogEntry.id}" region="pageFragments">
<div class="blogEntry">
<h3
>#{blogEntry.title}</h3>
<div>
<s:formattedText value="#{blogEntry.body}"/>
</div>
<p>
[Posted on 
<h:outputText value="#{blogEntry.date}">
<f:convertDateTime timezone="#{blog.timeZone}" locale="#{blog.locale}"
type="both"/>
</h:outputText
>]
</p>
</div>
</s:cache
>
Descrizione
Un tag che agisce come fornitore di download dei file. Deve essere il solo nella pagina JSF. Per essere in grado di usare questo controllo, web.xml deve essere impostato come segue.
Configurazione
<servlet>
<servlet-name
>Document Store Servlet</servlet-name>
<servlet-class
>org.jboss.seam.document.DocumentStoreServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name
>Document Store Servlet</servlet-name>
<url-pattern
>/seam/docstore/*</url-pattern>
</servlet-mapping>
Attributi
data— I dati da downloadare. Può essere java.util.File, InputStream o un byte array.fileName— Nome del file da servirecontentType— tipo di contenuto del file da scaricaredisposition— disposizione da usare. Di default è inline
Utilizzo
Ecco un esempio su come usare il tag:
<s:resource xmlns="http://www.w3.org/1999/xhtml"
xmlns:s="http://jboss.com/products/seam/taglib"
data="#{resources.data}"
contentType="#{resources.contentType}"
fileName="#{resources.fileName}" />
Il bean chiamato resources fornisce al file i parametri di richiesta del server, si veda s:download.
Descrizione
Costruisce un link RESTful a <s:resource>. f:param innestati costruiscono l'url.
src— I file che servono al file di risorsa.
Attributi
<s:download src="/resources.xhtml">
<f:param name="fileId" value="#{someBean.downloadableFileId}"/>
</s:download
>
Genererà qualcosa di simile a: http://localhost/resources.seam?fileId=1
Descrizione
Un <h:graphicImage> esteso che consente all'immagine di essere creata in un componente Seam; possono essere applicate all'immagine altre trasformazioni.
Tutti gli attributi per <h:graphicImage> sono supportati, così come:
Attributi
value— immagine da visualizzare. Può essere un pathString(caricato dal classpath), unbyte[], unjava.io.File, unjava.io.InputStreamo unjava.net.URL. I formati d'immagine supportati sonoimage/png,image/jpegeimage/gif.fileName— se non specificato l'immagine servita avrà un nome di file generato. Se si vuole nominare il file, occorre specificarlo in questo attributo. Il nome deve essere univoco.
Trasformazioni
Per applicare una trasformazione all'immagine, occorre innestare un tag specificando la trasformazione da applicare. Seam attualmente supporta queste trasformazioni:
-
<s:transformImageSize> width— nuova larghezza dell'immagineheight— nuova altezza dell'immaginemaintainRatio— se vengono specificatitrue, ed uno frawidth/height, l'immagine sarà ridimensionata con la dimensione non specificata che viene calcolata per mantenere l'aspect ratio.factor— scala l'immagine col dato fattore
-
<s:transformImageBlur> radius— esegue una convolution blur con il raggio dato
-
<s:transformImageType> contentType— modifica il tipo d'immagine inimage/jpegoimage/png
E' facile creare una trasformazione - si crei un UIComponent che implementi org.jboss.seam.ui.graphicImage.ImageTransform. Dentro il metodo applyTransform() si usi image.getBufferedImage() per recuperare l'immagine originale e image.setBufferedImage() per impostare l'immagine trasformata. Le trasformazioni sono applicare nell'ordine specificato nella vista.
Utilizzo
<s:graphicImage rendered="#{auction.image ne null}"
value="#{auction.image.data}">
<s:transformImageSize width="200" maintainRatio="true"/>
</s:graphicImage
>
Descrizione
Genera gli stub Javascript richiesti per usare Seam Remoting.
Attributi
include— una lista separata da virgola di nomi di componenti (o nome pienamente qualificati) per i quali generare stub Seam Remoting Javascript. Si veda Capitolo 25, Remoting per maggiori dettagli.
Utilizzo
<s:remote include="customerAction,accountAction,com.acme.MyBean"/>
Seam fornisce anche annotazioni che permettono di impiegare i componenti Seam come convertitori JSF e validatori:
-
@Converter @Name("itemConverter")
@BypassInterceptors
@Converter
public class ItemConverter implements Converter {
@Transactional
public Object getAsObject(FacesContext context, UIComponent cmp, String value) {
EntityManager entityManager = (EntityManager) Component.getInstance("entityManager");
entityManager.joinTransaction();
// Do the conversion
}
public String getAsString(FacesContext context, UIComponent cmp, Object value) {
// Do the conversion
}
}<h:inputText value="#{shop.item}" converter="itemConverter" />
Registra il componente Seam come converter JSF. Qua è mostrato un converter capace di accedere all'EntityManager JPA dentro ad una transazione JTA, quando converte il valore legato alla rappresentazione del suo oggetto.
-
@Validator @Name("itemValidator")
@BypassInterceptors
@org.jboss.seam.annotations.faces.Validator
public class ItemValidator implements javax.faces.validator.Validator {
public void validate(FacesContext context, UIComponent cmp, Object value)
throws ValidatorException {
ItemController ItemController = (ItemController) Component.getInstance("itemController");
boolean valid = itemController.validate(value);
if (!valid) {
throw ValidatorException("Invalid value " + value);
}
}
}<h:inputText value="#{shop.item}" validator="itemValidator" />
Registra il componente Seam come validatore JSF. Qua è mostrato un validatore che inietta un altro componente Seam; il componente iniettato è usato per validare il valore.