Do It The jAPS Way
Copyright © 2011 Tzente s.r.l.
Legal Notice
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the Appendix entitled "GNU Free Documentation License".
2011-03-03
| Revision History | ||
|---|---|---|
| Revision 0.3 | 2011-03-03 | MEM |
|
Revisione per il rilascio di jAPS 2.2.0 | ||
| Revision 0.2 | 2010-03-19 | MEM |
Revisione per il rilascio di jAPS 2.0.10 | ||
| Revision 0.1 | 2009-06-09 | AD |
Rilascio prima bozza | ||
Abstract
Le Showlet sono un elemento fondamentale nella creazione di portali con jAPS 2.0 entando.
In breve le Showlet costituiscono i blocchi dinamici del portale, tutti quegli elementi che ci si aspetta di voler spostare, modificare od adattare durante la gestione delle pagine.
In questo documento verrà spiegato velocemente come progettare ed implementare le Showlet.
Verranno inoltre illustrate le Showlet predefinite, le cosiddette Stock Showlets e la tag library di jAPS 2.0 entando tramite esempi.
Table of Contents
List of Examples
- 4.1. Esempio dei nomi dei file delle jsp
Briciole di PaneeMenu di Navigazione - 7.1. Tag wp:url
- 7.2. Tag wp:nav, lista di tutte le pagine figlie di una pagina
- 7.3. Tag wp:nav, lista di link dei figli di una pagina
- 7.4. Tag wp:i18n, Stampa di un'etichetta
- 7.5. Tag wp:resourceURL, utilizzo
- 7.6. Tag jacms:contentList, una lista di news
Table of Contents
Lo scopo di questo documento è illustrare il funzionamento delle Showlet e spiegarne il processo di sviluppo con degli esempi.
Questo documento è rivolto agli sviluppatori che intendono creare od ampliare un portale fatto con jAPS 2.0 entando.
Gli esempi ed i concetti riportati in questo manuale saranno utili agli sviluppatori come riferimento per la creazione di Showlet
Per poter utilizzare efficacemente le informazioni presenti in questo documento è necessario avere conoscenze di:
- jAPS 2.0 entando e la sua architettura
- i “Modelli di Pagina” di jAPS 2.0 entando
- HTML e CSS
- JSP e JSTL
- JSP, Java Server Pages Technology e JSTL, JavaServer Pages Standard Tag Library
Ulteriori informazioni possono essere richieste attraverso la mailing list ufficiale Google Group "japs-platform".
Per mandare un messaggio ai membri della lista, invia una mail a <japs-platform@googlegroups.com>.
È inoltre possibile consultare la documentazione presente in:
Table of Contents
Le Showlet sono un elemento fondamentale nella creazione di portali con jAPS 2.0 entando.
In breve le Showlet costituiscono i "blocchi" dinamici del portale, tutti quegli elementi che ci si aspetta di voler spostare, modificare od adattare durante la gestione delle pagine.
Nell'architettura di jAPS tutte le informazioni che vengono erogate, quindi presenti nelle pagine, passano attraverso le Showlet. Che si tratti di Contenuti, di Menu o di una lista di Contenuti, lo strumento che eroga queste informazioni è la Showlet.
E' possibile creare Showlet a seconda delle informazioni da erogare. Non esiste un limite al numero di Showlet che si possono aggiungere al portale.
Le Internal Servlet sono delle particolari Showlet che consentono di erogare una Servlet all'interno del portale.
Di fatto le Showlet sono JSP che vengono eleborate e poi incluse nelle varie posizioni, Frame, delle pagine.
jAPS si preoccupa di eseguire la richiesta, ottenere la JSP renderizzata e di posizionare l'output nei Frame.
Dal punto di vista del codice Html, le Showlet devono essere viste come porzioni di una intera pagina Html.
Quindi il risultato della renderizzazione di una Showlet dovrà essere un frammento di codice Html in armonia con i Modelli di Pagina
Warning
E' assolutamente sbagliato includere una intera pagina Html nelle showlet
Una Showlet è formata da:
- Un record sulla tabella
showletcatalognel dbport - Un file jsp situato nella directory
WebContent/WEB-INF/aps/jsp/showletsdel progetto
Per inserire una Showlet in jAPS è necessario eseguire i seguenti passi
Creare un file jsp all'interno del progetto nella directory
WebContent/WEB-INF/aps/jsp/showletsInserire un nuovo record nel db
portnella tabellashowletcatalogindicando i campi- code
-
Il nome del file della jsp creata precedentemente (senza l'estensione
.jsp) - titles
- Properties in formato Xml contenente una descrizione multilingua della Showlet.
- parameters
- Xml che definisce le azioni per la configurazione della Showlet da backend
- plugincode
Indica il codice del
plugina cui è associata la Showlet. A meno che non si stia lavorando con un plugin è da lasciare vuoto.Nel caso in cui si stia lavorando ad un plugin, il file
jspdella Showlet deve essere posizionato all'interno della directory/aps/jsp/showlets/del plugin. Per maggiori dettagli fare riferimento alla documentazione relativa al jAPS Plugin Pattern.- parenttypecode
-
Se presente, significa che questa Showlet è una specializzazione di un'altra Showlet.
Questo parametro indica il codice della Showlet che si desidera estendere.
La configurazione di questa Showlet va specificata nel paramentro
defaultconfig. - defaultconfig
-
Questo campo è utilizzato solo nel caso in cui il valore del campo
parenttypecodesia valorizzato. Contiene in formato Xml i paramentri di configurazione della Showlet corrente. Il risultato sarà quindi una Showlet di tipoparenttypecodeavente come configurazione quella specificata in questo campo.
Ricaricare la configurazione di sistema. Dal menu del CMS:
Varie,Ricarica,Ricarica la configurazione.Procedere con la creazione della Showlet inserendo il codice Html nel file jsp creato, importare le
tag librarynecessarie e creare i file css.Importare inoltre le eventuali immagini all'interno del progetto nella directory
WebContent/resources/static/img/showlets/e i file JavaScript inWebContent/resources/static/img/showlets/.Associare la Showlet ai
Framedelle Pagine.
Table of Contents
I nomi dei file delle jsp, i codici, i nomi dei CSS e delle directory utilizzate per le Showlet seguono la formula: nomeservizio_nomecomponente_variante
Ad esempio la jsp del form della ricerca si chiamerà search_form.jsp e la jsp della Showlet che ne stampa i risultati sarà search_results.jsp.
Example 4.1. Esempio dei nomi dei file delle jsp Briciole di Pane e Menu di Navigazione
Showlet Briciole di Pane: navigation_breadcrumbs.jsp
Showlet Menu di Navigazione: navigation_menu.jsp
Table of Contents
Solitamente è una delle prime domande che gli sviluppatori si fanno, ovvero: dove mettere i CSS e come collegarli con il resto del portale?
stato dedicato un intero capitolo per l'inclusione dei file CSS e dei file JavaScript all'interno delle Showlet per mettere in evidenza la procedura e per dare una rapida risposta ad una delle domande ricorrenti che gli sviluppatori si pongono.
necessario utilizzare il tag headInfo presente nella TLD aps-core.tld.
Sostanzialmente il tag headInfo dice al modello di pagina di stampare una informazione. Tale informazione viene recepita dal tag outputHeadInfo presente nel Modello di Pagina.
Il necessario di cui avete bisogno per poter effettuare correttamente l'inclusione di CSS è:
Un tag |
Un tag |
headInfo è il trasmettitore e outputHeadInfo è il ricevitore. Ovviamente devono essere dello stesso tipo, per questo entrambi hanno un attributo type. Type è una semplice stringa, che potete utilizzare a vostro piacimento tranne che per i CSS. Infatti il type="CSS" è utilizzato in tutto il sistema come riferimento per l'inclusione di file CSS (anche i modelli di contenuto se ne servono).
Il concetto risulta essere lo stesso presente per l'inclusione dei file CSS. Si necessita sempre di un tag outputHeadInfo nel Modello di Pagina e di un tag headInfo nella Showlet.
In questo caso però i due tag saranno allineati su un tipo "type" JS.
Note
Con lo stesso principio utilizzato per includere i file CSS e JS è possibile includere CSS per Internet Explorer semplicemente utilizzando un type apposito (es. CSS_IE7) e circondarlo dai commenti condizionali.
Table of Contents
jAPS viene rilasciato con alcune Showlet predefinite, o Stock Showlet, che consentono il corretto funzionamento delle funzionalità base.
Senza le Stock Showlet sarebbe impossibile usufruire ad esempio delle Internal Servlet o della Showlet di Login.
Le Custom Showlet invece sono create dagli sviluppatori per soddisfare delle esigenze specifiche, le quali possono essere di natura prettamente grafica o più complessa nel caso di funzionalità personalizzate.
Le Plugin Showlet sono le showlet incluse all'interno dei plugin di jAPS con lo scopo di erogare le funzioni specifiche di ogni plugin.
Per esempio il plugin java Agile CMS, attualmente distribuito con jAPS 2.0.8, comprende le showlet necessarie alla pubblicazione e alla ricerca dei Contenuti.
Table of Contents
è il tag preposto alla renderizzazione degli URL all'interno del portale quindi lo si deve usare per scrivere i link all'interno portale.
Ha due attributi: page e lang.
L'attributo page, non è obbligatorio, quando specificato restituisce l'URL di una pagina. Quando non è specificato il tag restituirà l'URL della pagina corrente.
L'attributo lang, come è possibile intuire, restituisce la pagina desiderata nella lingua specificata. Quando lang non è presente la lingua della pagina è la lingua corrente.
Example 7.1. Tag wp:url
Se volessi scrivere un link alla pagina con codice "homepage" in lingua inglese scriverei
<a href="<wp:url page="homepage" lang="en" />"> Homepage in English </a>
Il risultato sarebbe:
<a href="http://applicationBaseUrl/en/homepage.wp"> Homepage in English </a>
Il tag wp:nav si utilizza per la creazione di liste di link. in grado di iterare sull'albero delle pagine secondo la regola di navigazione fornita.
L'attributo spec deve contenere una espressione che indica un sottoinsieme di pagine (vedere la documentazione di INavigatorParser.java). Se spec non viene specificato verrà ricercato nella request.
Per ogni pagina ricavata dall'espressione presente in spec verrà eseguito il body del tag valorizzando con la pagina corrente la variabile indicata nell'attributo var.
Example 7.2. Tag wp:nav, lista di tutte le pagine figlie di una pagina
Assumiamo come pagina madre una pagina con codice homepage, vogliamo stampare la lista di tutte le sue figlie.
Nella showlet scriveremo:
<%@ taglib prefix="wp" uri="aps-core.tld" %>
<%@ taglib prefix="c" uri="c.tld" %>
<wp:nav
spec="code(homepage).subtree(1000)"
var="currentPage">
<c:out value="${currentPage.title}" /> -
</wp:nav>
Il risultato sarà simile a:
Homepage - Pagina 1 - Pagina 1 1 - Pagina 1 2 - (....)
Example 7.3. Tag wp:nav, lista di link dei figli di una pagina
Per creare una lista Html con i link a tutti i figli della pagina con codice homepage scriverò
<%@ taglib prefix="wp" uri="aps-core.tld" %>
<%@ taglib prefix="c" uri="c.tld" %>
<ul>
<wp:nav
spec="code(homepage).subtree(1000)"
var="currentPage">
<li>
<a href="<wp:url page="${currentPage.code}" />">
<c:out value="${currentPage.title}" />
</a>
</li>
</wp:nav>
Il risultato sarà simile a:
<ul> <li> <a href="http://applicationBaseUrl/currentLang/homepage.wp> Pagina Iniziale </a> </li> <li> <a href="http://applicationBaseUrl/currentLang/pagina1.wp> Pagina 1 </a> </li> <li> <a href="http://applicationBaseUrl/currentLang/pagina11.wp> Pagina 1 1 </a> </li> <li> <a href="http://applicationBaseUrl/currentLang/pagina12.wp> Pagina 1 2 </a> </li> (...) </ul>
In jAPS la renderizzazione delle etichette multilingua è affidata al tag wp:i18n, che dato un codice di un'etichetta ne recupera il valore.
Ha tre attributi: key, lang e var.
L'attributo key è obbligatorio e deve indicare un codice di un'etichetta esistente.
L'attributo lang se specificato restituisce il valore dell'etichetta nella lingua specificata. Quando non viene indicato l'etichetta renderizzata è nella lingua corrente dell'utente.
Infine è possibile salvare il valore restituito del tag in una variabile specificata nell'attributo var, altrimenti se non specificato, il tag stamperà direttamente l'etichetta.
Example 7.4. Tag wp:i18n, Stampa di un'etichetta
Assumendo di aver creato dal CMS l'etichetta con codice WELCOME e che nel portale esistano due lingue disponibili, italino ed inglese.
Il valore dell'etichetta WELCOME in italiano è Benvenuto in jAPS e in inglese Welcome to jAPS.
Nella Showlet voglio stamparne il valore nella lingua visualizzata dall'utente.
Scriverò:
<%@ taglib prefix="wp" uri="aps-core.tld" %> <%@ taglib prefix="c" uri="c.tld" %> <wp:i18n key="WELCOME" />
Note
I codici (key) delle etichette vengono scritti tutti maiuscoli. Se sono necessari degli spazi si utilizzano gli underscore(_)
Questi tre tag vengono utilizzati quando è necessario riferirsi a risorse statiche, utilizzato principalmente per l'inclusione di immagini e css.
Il tag wp:resourceURL restituisce di default il path completo sino alla directory resources/static/.
Gli altri due tag, wp:cssURL e wp:imgURL sono un'estensione di wp:resourceURL. Restituiscono rispettivamente il path della directory resources/static/css e resources/static/img.
Example 7.5. Tag wp:resourceURL, utilizzo
Nella directory del progetto WebContent/resources/static/js posiziono un file chiamato test.js. Per includerlo nel mio modello scrivo:
<%@ taglib prefix="wp" uri="aps-core.tld" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="it"> <head> <script type="text/javascript" src="<wp:resourceURL/>js/test.js"> </script> </head> [...]
Mi assicuro di aver incluso la TLD aps-core.tld e dopodichè utilizzo il tag wp:resourceURL nell'attributo src dello script. In output troveremo l'elemento script così modificato
[...] <script type="text/javascript" src="http://applicationbaseurl/resources/static/js/test.js"> </script> [...]
Questi tags fanno parte del plugin jacms che è in bundle con jAPS 2.0.8
Si utilizza quando si vuole stampare una lista di contenuti che possono essere visualizzati nel portale.
Il suo funzionamento prevede che restituisca una lista di identificativi che dovranno poi essere renderizzati
tramite il tag jacms:content.
è composto dagli attributi:
- listName
- è obbligatorio, è il nome della variabile, nel contesto di pagina, che verrà valorizzata con la lista degli identificativi dei contenuti.
- contentType
- Se specificato la lista conterrà solo identificati di contenuti di quel tipo. Deve essere uno dei codici dei
Tipi di Contenutoconfigurati nel sistema. - category
- è il codice di una categoria. Se specificato, verranno inseriti nella lista solo gli identificativi dei contenuti che appartengono alla categoria indicata.
- cacheable
-
Può assumere i valori
trueoppurefalse, di default ha valoretrue. Determina se la lista debba essere generata utilizzando lacachedi sistema. Quando è impostato afalsenon verrà utilizzata la cache di sistema per generare la lista.
Insieme al tag contentList è fornito il sottotag contentListFilter. ContentListFilter, lo dice il nome stesso, imposta un filtro sulla lista dei contenuti. All'interno del tag contentList è possibile inserire più di un filtro tramite contentListFilter, ciascun filtro verrà processato nell'ordine di posizione.
Ecco gli attributi di contentListFilter
- key
il codice di un
metadatooppure il nome un attributo (compatibile con il tipo specificato incontentTypedel tagcontentList).Il filtro sarà applicato sulla base del metadato o dell'attributo indicato.
I metadati disponibili sono: la data di creazione del contenuto (codice
created) e la data dell'ultima modifica (codicemodified).Quando il valore di
keysi riferisce al nome di un attributo delTipo di Contenutoè necessario impostareattributeFilteratrue- attributeFilter
-
Può assumere i valori
trueofalseed indica se il filtro debba essere applicato sugli attributi del contenuto oppure sui metadati. - value
il valore atteso. Si utilizza quando si vuole raggiungere un gruppo di contenuti con proprietà di pari valore. Ad esempio tutti i contenuti con data 22/01/2001.
Non è obbligatorio. Viene considerato alternativo a
starteend- start
è il valore di partenza del metadato o dell'attributo specificato per cui applicare il filtro. Si utilizza per creare filtri su un dato intervallo. Ad esempio tutti i contenuti creati dal 22/01/2001
Non è obbligatorio. considerato alternativo a
valueed utilizzato in coppia conendper la definizione di intervalli.- end
è il valore finale del metadato o dell'attributo specificato per il quale applicare il filtro. Si utilizza per creare filtri con range di valori. Ad esempio tutti i contenuti creati prima del 19/06/2005
Non è obbligatorio. considerato alternativo a
valuee generalmente utilizzato in coppiastartper la definizione di intervalli.- order
Non è obbligatorio e può assumere i valori
ASCeDESC, non ha un valore predefinito.Specifica come debbano essere ordinati i risultati del filtro, quando assume il valore
ASCi risultati saranno ordinati in modo crescente, quando specificatoDESCin modo decrescente.- likeOption
Può assumere i valori
trueofalseed è applicabile ai soli metadati e attributi del contenuto di tipo testo. Di default il suo valore èfalse.Quando impostato a
trueil comportamento del filtro verrà modificato in modo tale da includere nella lista quei contenuti (gli identificativi) che esprimono somiglianza per il metadato o attributo fornito.
Example 7.6. Tag jacms:contentList, una lista di news
Con il codice seguente si vogliono stampare gli ultimi cinque contenuti di tipo News che fanno parte della categoria con codice sport.
<%@ taglib prefix="jacms" uri="/WEB-INF/plugins/jacms/aps/tld/jacms-aps-core.tld" %>
<%@ taglib prefix="wp" uri="aps-core.tld" %>
<%@ taglib prefix="c" uri="c.tld" %>
<wp:i18n key="LATEST_SPORT" />
<hr />
<jacms:contentList listName="listaNews" contentType="NEW" category="sport">
<jacms:contentListFilter key="Data" attributeFilter="true" order="DESC"/>
<jacms:contentListFilter key="Titolo" attributeFilter="true" order="ASC"/>
</jacms:contentList>
<c:forEach var="contentId" items="${listaNews}" begin="0" end="4">
<jacms:content contentId="${contentId}" modelId="default" />
<hr />
</c:forEach>
Table of Contents
Form della Ricerca che punta ad una pagina dei risultati search_results
<%@ taglib prefix="wp" uri="aps-core.tld" %> <form id="searchForm" method="get" action="<wp:url page="search_results" />"> <input type="text" name="search" /> <input type="submit" value="Cerca" /> </form>
Ultime 4 notizie con categoria homepage
<%@ taglib prefix="jacms" uri="/WEB-INF/plugins/jacms/aps/tld/jacms-aps-core.tld" %>
<%@ taglib prefix="wp" uri="aps-core.tld" %>
<%@ taglib prefix="c" uri="c.tld" %>
<jacms:contentList listName="contentList" contentType="NEW" category="homepage">
<jacms:contentListFilter key="Data" attributeFilter="true" order="DESC" />
</jacms:contentList>
<ul>
<c:forEach var="content" items="${contentList}" begin="0" end="3">
<li><jacms:content contentId="${content}" modelId="list" /></li>
</c:forEach>
</ul>
Sfrutta il solo tag jacms:content il resto lo fa la configurazione
<%@ taglib prefix="jacms" uri="aps-core.tld" %> <jacms:content />
Eroga una lista di contenuti configurata dal CMS
<%@ taglib prefix="jacms" uri="/WEB-INF/plugins/jacms/aps/tld/jacms-aps-core.tld" %>
<%@ taglib prefix="wp" uri="aps-core.tld" %>
<%@ taglib prefix="c" uri="c.tld" %>
<%
/*
Author: William Ghelfi <william.ghelfi@elicriso.biz> - 2005/05/23
Author: Eugenio Santoboni <eugeniosant@tiscali.it>
Erogatore automatico di contenuti.
*/
%>
<jacms:contentList listName="contentList" />
<c:if test="${contentList != null}">
<wp:pager listName="contentList" objectName="groupContent" pagerIdFromFrame="true" >
<ul>
<c:forEach var="contentId" items="${contentList}" begin="${groupContent.begin}" end="${groupContent.end}">
<li><jacms:content contentId="${contentId}" /></li>
</c:forEach>
</ul>
<c:if test="${groupContent.size > groupContent.max}">
<p class="paginazione">
<c:choose>
<c:when test="${'1' == groupContent.currItem}"><< <wp:i18n key="PREV" /></c:when>
<c:otherwise><a href="<wp:url paramRepeat="true" ><wp:urlPar name="${groupContent.paramItemName}" ><c:out value="${groupContent.prevItem}"/></wp:urlPar></wp:url>"><< <wp:i18n key="PREV" /></a></c:otherwise>
</c:choose>
<c:forEach var="item" items="${groupContent.items}">
<c:choose>
<c:when test="${item == groupContent.currItem}"> [<c:out value="${item}"/>] </c:when>
<c:otherwise> <a href="<wp:url paramRepeat="true" ><wp:urlPar name="${groupContent.paramItemName}" ><c:out value="${item}"/></wp:urlPar></wp:url>"><c:out value="${item}"/></a> </c:otherwise>
</c:choose>
</c:forEach>
<c:choose>
<c:when test="${groupContent.maxItem == groupContent.currItem}"><wp:i18n key="NEXT" /> >></c:when>
<c:otherwise><a href="<wp:url paramRepeat="true" ><wp:urlPar name="${groupContent.paramItemName}" ><c:out value="${groupContent.nextItem}"/></wp:urlPar></wp:url>"><wp:i18n key="NEXT" /> >></a></c:otherwise>
</c:choose>
</p>
</c:if>
</wp:pager>
</c:if>
