Do It The jAPS Way
Copyright © 2009 AgileTec 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-02-14
| Revision History | ||
|---|---|---|
| Revision 0.8 | 2011-02-14 | MEM |
|
Revisione per jAPS 2.0 entando versione 2.2.0 | ||
| Revision 0.7 | 2010-03-10 | GC |
|
Aggiornamento per versione 2.0.10 | ||
| Revision 0.6 | 2009-10-15 | GC |
|
Aggiornamento per versione 2.0.8 | ||
| Revision 0.5 | 2009-06-15 | GC |
|
Revisione di rilascio | ||
| Revision 0.4 | 2009-05-27 | GC |
|
Revisione in previsione del rilascio | ||
| Revision 0.3 | 2009-05-04 | EM |
|
Seconda Versione con modifica nome plugin e percorsi | ||
| Revision 0.2 | 2009-03-26 | RB |
|
Prima Versione docbook | ||
| Revision 0.1 | 2009-02-24 | EM |
|
Versione odt | ||
Abstract
Lo scopo di questo documento è quello di fornire una descrizione completa della struttura del Plugin User Registration.
Table of Contents
List of Tables
List of Examples
Table of Contents
Lo scopo di questo documento è quello di fornire una descrizione completa della struttura del Plugin User Registration.
Questo documento è destinato a chi intende conoscere le funzionalità del jAPS Plugin User Registration,
e sta prendendo in considerazione la eventuale integrazione in un Ambiente di Produzione già funzionante
o nel proprio Ambiente di Sviluppo (Progetto in IDE Eclipse).
Il documento è indirizzato sia a Sistemisti (responsabili di installazioni di Applicazioni su base jAPS 2.0 entando) che ai Java Developers (con una conoscenza base del Framework jAPS 2.0 entando).
Per poter utilizzare efficacemente le informazioni contenute in questo documento, occorre un po' di esperienza su alcune tecnologie del web base: la piattaforma Java, gli strumenti di sviluppo Eclipse, il servlet engine Apache Tomcat, il database PostgreSQL, e del Framework jAPS 2.0 entando. E' inoltre necessario aver letto il documento jAPS 2.0 - Plugin Pattern.
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
Il Plugin
User Registration
consente ad un visitatore del portale le operazioni di:
registrazione dei dati necessari ad effettuare l'accesso ad aree riservate del portale
recupero delle informazioni per l'accesso al sistema (username e/o password)
riattivazione dell'utenza per accedere alle aree riservate del portale, in seguito ad una disattivazione
disattivazione dell'utenza per impedire all'utente di accedere alle aree riservate del portale, in seguito è possibile eseguire la riattivazione
Table 2.1. Riassunto delle caratteristiche
| Codice | Nome | Tipo | Versione del Plugin | Versione di jAPS 2.0 entando |
|---|---|---|---|---|
| jpuserreg | User Registration | PurePlugin | 1.2 | 2.2.0 - |
| jpuserreg | User Registration | PurePlugin | 1.1 | 2.0.8 - 2.0.10 |
| jpuserreg | User Registration | PurePlugin | 1.0 | 2.0.2 |
Il modulo presenta una serie di interfacce per il Front-End, erogabili attraverso la Showlet Internal Servlet , tramite le quali un utente può registrarsi al portale, disattivare la propria utenza, riattivarla. Tali interfacce non contengono nessun elemento di presentazione per consentirne la vestizione in una qualunque istanza specifica di jAPS 2.0 entando. Le operazioni di registrazione e riattivazione di un'utenza prevedono l'invio di una mail contenente un link necessario al completamento dell'operazione.
La procedura di registrazione richiede l'inserimento dei campi nome, cognome, lingua e email. Inseriti questi dati l'utente riceve all'indirizzo email fornito all'atto della registrazione un email contenente un link con un ticket valido per l'attivazione dell'account. Cliccando sul link l'utente accede alla pagina di completamenteo della procedura di registrazione dove gli viene richiesto di definire la sua password. Definita con successo la password l'utente ha a disposizione un account per accedere al portale.
La procedura di riattivazione consente all'utente di recuperare la sua password in caso di smarrimento oppure di riattivare il suo account, precedentemente disattivato, ridefinendo appunto la password. Per effettuare la richiesta di recupero password l'utente deve fornire la username o l'indirizzo email del suo profilo sul portale. Se i dati forniti sono corretti l'utente riceve al suo indirizzo di posta un email contente un link con un ticket valido per ridefinire la password del suo account.
La procedura di disattivazione consente all'utente di sospendere il suo account. Una volta sospeso l'account l'utente non può più utilizzarlo per loggarsi sul portale sino a quando non effettua la procedura di riattivazione. Per sospendere il suo account l'utente deve essere loggato e deve fornire la sua password.
Table of Contents
Il plugin ha la caratteristica di Pure-Plugin, la sua installazione non modifica nessuna funzionalità presente nel sistema. Il plugin ha una serie di interfaccie per il Front-end. Queste interfaccie non contengono nessun elemento grafico. In questo modo è possibile personalizzare l'interfaccia in qualsiasi istanza di di jAPS 2.0 entando
Il pacchetto del Plugin contiene l'insieme delle cartelle (doc ed src
più il file README) come definito nel documento di descrizione generale del jAPSPlugin Pattern.
In particolare, la cartella src è strutturata come di seguito descritto:
Cartella
javacontiene le sorgenti java complete ed i test jUnit del Plugin.Cartella
sqlcontiene gli script da eseguire nei dbPorteServdi produzione e di test.Cartella
webapp. La cartella contiene tutti i file necessari alla webapp. In particolare, la cartella contiene i file (jsp) relativi alla interfacce utente ed i file di configurazione delle stesse, i file di definizione dei bean a servizio sia del layer di Business del Modello di jAPS 2.0 entando, che nelle action di Struts 2 relative al Layer di Presentation, le librerie (compreso il jar ricavato dai sorgenti del plugin), le risorse statiche necessarie (css, immagini, e js).
Per integrare o installare con successo il plugin di registrazione utente è necessario soddisfare la dipendenza dai plugin jpmail e jpuserprofile. Per quanto riguarda l'installazione/integrazione di questi plugin fare riferimento alla relativa documentazione.
I passi da eseguire per eseguire l'installazione in un'applicazione Web in produzione basata sulla versione di jAPS 2.0 entando dichiarata compatibile con il plugin, sono di seguito illustrati.
Tutte le attività sono da eseguire nell'applicazione a freddo ovvero successivamente all'arresto del application server.
Installare i plugin jpmail e jpuserprofile nell'ambiente di produzione (fare riferimento alle rispettive documentazioni), personalizzando opportunamente la configurazione dei plugin come descritto nei paragrafi successivi.
Copiare il contenuto della cartella
src/webapp/WEB-INF/libdel pacchetto dato in dotazione, all'interno della cartella<WEB_APP_NAME>/WEB-INF/lib/in produzione.Copiare il contenuto della cartella
src/webapp/WEB-INF/pluginsdel pacchetto dato in dotazione, all'interno della cartella<WEB_APP_NAME>/WEB-INF/plugins/in produzione. Creare la cartella plugins se non è presente.Copiare il contenuto della cartella
src/webapp/resources/pluginsdel pacchetto dato in dotazione, all'interno della cartella<WEB_APP_NAME>/resources/plugins/in produzione.Eseguire i task contenuti nel file
portScript.sql(contenuto nella cartellasrc/sqldel pacchetto dato in dotazione) nel dbportin produzione (in una configurazione standard il database ha nome<WEB_APP_NAME>Port). Lo script è strutturato ipotizzando il versionproduction(variare se il version dell'ambiente di produzione è diverso). Modificare la struttura del modello del profilo secondo le necessità.Eseguire i task contenuti nel file
servScript.sql(contenuto nella cartellasrc/sqldel pacchetto dato in dotazione) nel dbservin produzione (in una configurazione standard il database ha nome<WEB_APP_NAME>Serv).
Per eseguire l'installazione in un progetto Eclipse basato sulla versione di jAPS 2.0 entando dichiarata compatibile con il plugin, i passi da eseguire sono i seguenti:
Installare i plugin jpmail e jpuserprofile nell'ambiente di sviluppo. Fare riferimento alla documentazione relativa a ciascuno dei plugin.
Copiare il contenuto della cartella
src/webapp/WEB-INF/libdel pacchetto dato in dotazione, all'interno della cartella<PROJECT_NAME>/WebContent/WEB-INF/lib/, con l'esclusione del filejAPSPlugin-jpuserreg-1.1.jar.Copiare il contenuto della cartella
src/webapp/WEB-INF/pluginsdel pacchetto dato in dotazione, all'interno della cartella<PROJECT_NAME>/WebContent/WEB-INF/plugins/. Creare la cartella plugins se non è presente.Copiare il contenuto della cartella
src/webapp/resources/pluginsdel pacchetto dato in dotazione, all'interno della cartella<PROJECT_NAME>/WebContent/resources/plugins/.Eseguire i task contenuti nel file
portScript.sql(contenuto nella cartellasrc/sqldel pacchetto dato in dotazione) nel proprio dbport(in una configurazione standard il database ha nome<PROJECT_NAME>Port). Lo script è strutturato ipotizzando il versionproduction(variare se il version dell'ambiente di produzione è diverso). Modificare la struttura del modello del profilo secondo le necessità.Eseguire i task contenuti nel file
servScript.sql(contenuto nella cartellasrc/sqldel pacchetto dato in dotazione) nel proprio dbserv(in una configurazione standard il database ha nome<PROJECT_NAME>Serv).Eseguire i task contenuti nel file
portTestScript.sql(contenuto nella cartellasrc/sqldel pacchetto dato in dotazione) nel proprio dbportdi test (in una configurazione standard il database ha nome<PROJECT_NAME>testPort).Eseguire i task contenuti nel file
servTestScript.sql(contenuto nella cartellasrc/sqldel pacchetto dato in dotazione) nel proprio dbservdi test (in una configurazione standard il database ha nome<PROJECT_NAME>testServ).Copiare il contenuto della cartella
src/java/main/comnella cartella<PROJECT_NAME>/src/comdel proprio progetto.Copiare il contenuto della cartella
src/java/test/testnella cartella<PROJECT_NAME>/src/testdel proprio progetto.Copiare nella cartella
<PROJECT_NAME>/src/del proprio progetto il file contenuto della cartellasrc/java/maindi nomejpuserreg_japs-struts-plugin.xml. Nel caso che nella cartellasrcdel progetto Eclipse sia già presente un file di nomejaps-struts-plugin.xml, copiare il contenuto del tag <struts> del filejpuserreg_japs-struts-plugin.xmlall'interno del filejaps-struts-plugin.xmlesistente e cancellare il filejpuserreg_japs-struts-plugin.xml. Nel caso che nella cartellasrcdel progetto Eclipse non sia presente un file di nomejaps-struts-plugin.xml, rinominare il filejpuserreg_japs-struts-plugin.xmlinjaps-struts-plugin.xml.Per verificare il corretto invio delle mail nei test di jUnit, modificare la costante
EMAILdella classeJpUserRegTestHelper.javanel packagetest.com.agiletec.plugins.jpuserreg.
Una volta eseguiti i passi sopra descritti, far partire il progetto da Eclipse e configurare, da interfaccia di amministrazione, le pagine necessarie al funzionamento del plugin, come descritto nei paragrafi successivi. Occorrerà anche personalizzare le relative jsp secondo lo stile del portale sviluppato.
E' necessario che nella configurazione del plugin
User Profile
siano presenti i 4 attributi
Nome, Cognome, eMail e Lingua configurati secondo l'esempio:
Example 3.1.
Esempio di configurazione plugin
User Profile
<profiles> <profile typecode="PFL" typedescr="Profilo utente/cittadino tipo" > <attributes> <attribute name="Nome" attributetype="Monotext" required="true"/> <attribute name="Cognome" attributetype="Monotext" required="true"/> <attribute name="email" attributetype="Monotext" required="true" searcheable="true" /> <attribute name="language" attributetype="Monotext" /> </attributes> </profile> </profiles>
importante l'attributo email deve essere dichiarato searchable
L'attributo email deve essere, obbligatoriamente , searcheable per consentire, qual'ora fosse richiesto, la ricerca delle informazioni dell'utente tramite indirizzo email. Come ad esempio avviene nella funzionalità di recupero password passando attraverso la richiesta email. Per eseguire con successo i test Junit verificare la configurazione dell'attributo email anche nella configurazione del profilo nel database di test.
Prendere nota dei
name
assegnati a questi attributi, poichè saranno necessari
nella configurazione del plugin
User Registration
.
Il plugin
Mail
deve contenere almeno un elemento sender contenente l'indirizzo
email valido
con il quale verranno inviate le mail di comunicazione all'utente in
fase di registrazione o recupero informazioni.
Example 3.2.
Esempio di configurazione plugin
Mail
<mailConfig> <senders> <sender code="CODE1">EMAIL1@EMAIL.COM</sender> <sender code="CODE2">EMAIL2@EMAIL.COM</sender> </senders> <smtp debug="true" > <host>out.virgilio.it</host> <user></user> <password></password> </smtp> </mailConfig>
Prendere nota dell'attributo
code
con il quale verranno inviate le email.
Controllare, ed eventualmente modificare, il parametro
applicationBaseURL
presente all'interno del file
/WebContent/META-INF/context.xml
, il parametro deve contenere l'URL completa del portale.
Esempio:
<Environment name="applicationBaseURL" value="http://localhost:8080/PortalExample/" type="java.lang.String" override="false" />
La configurazione del plugin viene definita attraverso la
configurazione di un xml
(inserito nel db
Port
dell'istanza di jAPS 2.0 entando) nel quale sono definiti gli elementi
necessari
alla generazione del nuovo utente e del profilo associato, nonchè le
configurazioni delle eMail inviate all'utente
nelle procedure di registrazione e riattivazione.
Di seguito un esempio della configurazione necessaria:
<userRegConfig>
<!-- Matching between plugin jpuserreg attributes and attributes
Nome, Cognome, language and email mapped
on user profile config -->
<profileEntity nameAttr="Nome" surnameAttr="Cognome"
eMailAttr="email" langAttr="language" />
<!-- Token validity in minutes -->
<tokenValidity minutes="60"/>
<!-- Sender code, as in mailConfig -->
<sender code="CODE1" />
<!-- Authorities to load on user request profile [OPTIONAL] -->
<userAuthDefaults>
<role name="userrole" />
<group name="usergroup" />
</userAuthDefaults>
<!-- Activation page name -->
<activation pageCode="activation">
<template lang="it">
<subject>[jAPS] : Attivazione utente</subject>
<body>
Gentile {name} {surname},
grazie per esserti registrato.
Per attivare il tuo account è necessario seguire il seguente link:
{link}
Cordiali Saluti.
</body>
</template>
</activation>
<!-- Re-Activation page name -->
<reactivation pageCode="recover">
<template lang="it">
<subject>[jAPS] : Riattivazione utente</subject>
<body>
Gentile {name} {surname},
il tuo userName è {userName}.
Per riattivare il tuo account è necessario seguire il seguente link:
{link}
Cordiali Saluti.
</body>
</template>
</reactivation>
</userRegConfig>
Dettaglio e significato dei parametri:
Parametro profileEntity - Questo parametro contiene i nomi degli attributi per effettuare il matching con il plugin
User Profilerelativamente agli attributi Nome, Cognome, linguaggio e emailParametro tokenValidity - Questo parametro contiene la durata del token di attivazione, questo viene inviato all'utente attraverso un email. Trascorso quel tempo il token viene invalidato e non sarà quindi più utilizzabile per l'attivazione
Parametro sender - Questo parametro contiene il nome del sender email per effettuare il matching con il plugin
MailParametro userAuthDefaults - Questo parametro opzionale, da configurare con attenzione, consente di definire i ruoli e i gruppi che verranno assegnati alla nuova utenza creata all'atto dell'iscrizione al portale.
Parametro activation - Questo parametro contiene la configurazione della mail da inviare all'utente per la conferma di richiesta attivazione utenza. Contiene anche il nome della pagina da visualizzare per l'attivazione il valore è contenuto nell'attributo pageCode . All'interno del parametro activation sono presenti almeno un elemento template corrispondente alla lingua di default del portale. Nella situazione ottimale è preferibile creare un template per ogni lingua definita all'interno del portale. Ogni elemento template contiene un elemento subject ed un elemento body . L'elemento body può essere personalizzato inserendo parametri che verranno sostituiti a runtime. Sono previsti i seguenti parametri:
{name}: contenente il nome dell'utente (quello configurato nel profilo nell'attributo contenente il nome).
{surname}: contenente il cognome.
{link}: contenente il link indispensabile per il completamento dell'operazione.
Parametro reactivation - Questo parametro contiene la configurazione della mail da inviare all'utente per la conferma di richiesta di riattivazione utenza. Contiene anche il nome della pagina da visualizzare per la riattivazione il valore è contenuto nell'attributo pageCode . Oltre a quanto specificato al punto precedente per gli elementi subject e body è possibile inserire all'interno del body un elemento cosi definito:
{userName}: contenente lo username dell'utente.
Per il funzionamento del plugin User Registration
è necessario creare delle pagine che verranno di seguito elencate.
Ognuna delle pagina create deve contenere una delle showlet del plugin.
Se si utilizzano i nomi consigliati riportati tra parentesi quadre non sarà necessario modificare i
codici delle pagine nella showlet e nella configurazione del plugin.
Per tenere comodamente sotto controllo l'albero delle pagine si
consiglia di crearle come figlie di una pagina,
chiamata ad esempio Gestione Utenti, non visibile nei menù.
Personalizzare opportunamente la showlet di login fornita con il plugin
jpuserreg_loginUserReg
(/WEB-INF/plugins/jpuserreg/aps/jsp/showlets/jpuserreg_loginUserReg.jsp)
oppure personalizzare la showlet di login base in modo che contenga i link a queste nuove pagine.
Nella showlet jpuserreg_loginUserReg ci sono i link alle pagine:
registr, passwordrecover e disactiv.
Questi codici devono corrispondere rispettivamente ai nomi della pagina di registrazione,
la pagina di recupero password e la pagina di disattivazione account. Queste pagine devono
essere tutte configurate con le relative showlet come illustrato di seguito.
Nella showlet è previsto il link che porta alla pagina di editing del profilo o della
password (di default la pagina editprof_page_code, personalizzare se necessario).
Se non è presente nessuna pagina di editing profilo nel portale rimuovere il link.
Per i dettagli sulla configurazione della pagina di editing profilo/password fare riferimento
alla documentazione del plugin jpuserprofile.
Table 3.1. Configurazione pagine
| Codice Pagina | Nome Showlet |
|---|---|
| registr | User Registration - Registrazione Utente (jpuserreg_Registration) |
| activation | User Activation - Attivazione Utente (jpuserreg_Activation) |
| passwordrecover | Password Recover - Recupero Password (jpuserreg_Recover) |
| recover | User Reactivation - Riattivazione Utente (jpuserreg_Reactivation) |
| disactiv | User Suspension - Sospensione Utente (jpuserreg_Suspension) |
Il codice della pagina activation deve essere uguale a quello inserito
nella configurazione xml del plugin nella tabella sysconfig sul database Port.
Example 3.3.
Esempio di definizione del parametro
pageCode
per attivazione utenza
<activation pageCode="activation"> <template lang="it"> ......... </template> </activation>
Il codice della pagina recover deve essere uguale a quello inserito
nella configurazione del plugin.
Example 3.4.
Esempio di definizione del parametro
pageCode
per recupero/riattivazione utenza
<reactivation pageCode="recover"> <template lang="it"> ......... </template> </reactivation>
Per quanto riguarda lo strato di presentazione, occorre
personalizzare, secondo lo stile del portale, le jsp contenute
all'interno della cartella
/WEB-INF/plugins/jpuserreg/aps/jsp/externalFramework/userreg/
e la showlet che si trova in
/WEB-INF/plugins/jpuserreg/aps/jsp/showlets/
Di seguito la descrizione di ogni jsp:
activation/activateUser.jspcontenente il form di registrazione di un utenza del portale.activation/activateUserError.jspcontenente il messaggio di errore in caso di tentativo di attivazione con token scaduto o non valido.activation/confirmedUserActivation.jspcontenente il messaggio di conferma di ricezione della richiesta di registrazione e di invio di una mail per il completamento della procedura.activation/reactivateUser.jspcontenente il form per il completamento della registrazione, con l'inserimento della password.activation/reactivateUserError.jspcontenente il messaggio di errore in caso di tentativo di riattivazione con token scaduto o non valido.activation/confirmedUserReactivation.jspcontenente il messaggio di conferma avvenuta riattivazione dell'utenza.recover/recoverUser.jspcontenente il form per il recupero di un'utenza a partire dalla username o dall'indirizzo eMail.recover/confirmedRecoverRequest.jspcontenente il messaggio di conferma di ricezione della richiesta di recupero dati.registration/registerUser.jspcontenente il form di richiesta nuova registrazione utente.registration/confirmedUserRegistration.jspcontenente il messaggio di conferma di ricezione della richiesta di registrazione utente.suspension/confirmSuspend.jspcontenente il form di richiesta sospensione account.error.jspcontenente il messaggio di errore in caso di tentativo sospensione account per utente amministrazione o utente non della base utenti locale.
Potrebbe essere necessario personalizzare le etichette presenti nelle
JSPs, utilizzate col tag
wp:i18n
.
