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".
2010-04-01
| Revision History | ||
|---|---|---|
| Revision 0.3 | 2010-03-10 | GC |
|
Revision for jAPS version 2.0.10 | ||
| Revision 0.2 | 2009-10-15 | GC |
|
Revision for jAPS version 2.0.8 | ||
| Revision 0.1 | 2009-09-18 | GC |
|
English version | ||
Abstract
The purpose of this document is to provide a complete description of the Plugin "jpuserreg" structure.
Table of Contents
List of Tables
- 2.1. Summary of features
- 3.1. Pages configuration
List of Examples
Table of Contents
The purpose of this document is to provide a complete description of the Plugin "jpuserreg" structure.
This document is intended for those who wish to know the capabilities of the jAPSPlugin "jpuserreg" and is considering the possible integration into a running production environment or in its Development Environment (IDE Eclipse Project).
The document is addressed to both System Administrators and java Developers.
In order to take maximum advantage from the present document, it is necessary to have basic knowledge about: the Java platform, the Eclipse IDE, the Apache Tomcat servlet engine, the PosgreSQL DBMS.
Additional informations may be obtained through the following mailing-lists:
<japs-devs@lists.sourceforge.net>, focused on developers<japs-users@lists.sourceforge.net>, focused on final users
Is it also possible to refer to the documentation found in the:
Table of Contents
The jAPS Plugin
User Reg
allows to a portal visitor the following actions:
registration of data mandatory to access reserved areas on portal
recover credential to portal access (username and/or password)
account reactivation to access reserved areas on portal, after disactivation
the account deactivation to avoid user access to reserved areas on portal, is possible to reactivate the account
Table 2.1. Summary of features
| Code | Name | Type | Plugin Version | jAPS 2.0 Version |
|---|---|---|---|---|
| jpuserreg | User Reg | PurePlugin | 1.1 | 2.0.10, 2.0.8 |
| jpuserreg | User Reg | PurePlugin | 1.0 | 2.0.2 |
The module presents a set of interfaces for the Front-End, payable through Showlet Internal Servlet. These interfaces do not contain any graphical element. In this way it's possible to decorate it in any specific instance of jAPS 2.0. The actions of the registration and the reactivation of an account happens with an email sending, these mail contains a link to complete operation.
The registration procedure require the insertion of fields name, surname, language and email. When user provides required data, he receives an email with a link with a ticket valid for account activation. Clicking on the link the user accessed to a page to complete the registration procedure. During this procedure the user have to define his password. If user successfully defined his password the user has an account to access reserved areas on portal.
The reactivation process allows you to recover your password if lost or to reactivate your account, previously deactivated, redefining the password. The password recovery procedure requires that user provide his username or his email address from his profile on the portal. If the data provided are correct the user receives an email containing a link with a valid ticket to redefine the password for your account.
The procedure allows the user to disable his account. Once suspended the account you can not use it to log into the portal until the reactivation process is not completed. An user for suspend his account must be logged and must provide his password.
Table of Contents
The plugin has the characteristic of PurePlugin, its installation does not change any functionality in the system. The module presents a set of interfaces for the Front-End. These interfaces do not contain any graphical element. In this way it's possible to decorate it in any specific instance of jAPS 2.0.
The package contains the folders doc, src
and the file README as defined on jAPSPlugin Pattern documentation.
The src folder is structured as follows:
The
javafolder contains complete java sources and the jUnit tests for the Plugin.The
sqlfolder contains scripts to execute onPortandServdb, for production and for test.The
webappfolder contains all file needed by the webapp. In details, the folders contains jsp files (user interfaces) and config files, files for bean definition used by business layer of the jAPS 2.0 model and also by Struts 2 actions from the layer of presentation, the libraries (including the jar from sources of the plugin) and statics resources (css, images, js).
For integrate and install successfully the plugin of user registration the installation of plugins jpmail and jpuserprofile is mandatory. For integration/installation of this plugins see relative documentation.
The following steps are for the installation of the plugin on a web application, in production state, based on the jAPS version declared compatible with the plugin.
The following activities are to be carried out after the stop of the Web Application.
Install the plugins jpmail and jpuserprofile in the production environment (see relative documentation), customize properly plugin configuration following the next paragraphs instructions.
Copy the contents of the folder
src/webapp/WEB-INF/libof the package as supplied within the folder<WEB_APP_NAME>/WEB-INF/lib/in production.Copy the contents of the folder
src/webapp/WEB-INF/pluginsof the package as supplied within the folder<WEB_APP_NAME>/WEB-INF/plugins/in production. Create folder plugins if not exists.Copy the contents of the folder
src/webapp/resources/pluginsof the package as supplied within the folder<WEB_APP_NAME>/resources/plugins/in production.Perform tasks detailed in the file
portScript.sql(present in the foldersrc/sql) in the production db port (for a standard configuration the database has name<WEB_APP_NAME>Port). The script is written for a versionproduction(edit if the version of the environment is different). Edit the structure of the profile model if needed.Perform tasks detailed in the file
servScript.sql(present in the foldersrc/sql) in the production db serv (for a standard configuration the database has name<WEB_APP_NAME>Serv).
To install the plugin in an Eclipse project based on jAPS 2.0 and declared compatible with the plugin,
Perform the following steps (From this point on, we will assume that your new project is called <PROJECT_NAME>):
Install the plugins jpmail and jpuserprofile in the development environment (see relative documentation), customize properly plugin configuration following the next paragraphs instructions.
Copy the contents of the folder
src/webapp/WEB-INF/libof the package as supplied within the folder<PROJECT_NAME>/WebContent/WEB-INF/lib/, excluding filejAPSPlugin-jpuserreg-1.1.jar.Copy the contents of the folder
src/webapp/WEB-INF/pluginsof the package as supplied within the folder<PROJECT_NAME>/WebContent/WEB-INF/plugins/. Create folder plugins if not exists.Copy the contents of the folder
src/webapp/resources/pluginsof the package as supplied within the folder<PROJECT_NAME>/WebContent/resources/plugins/.Perform tasks detailed in the file
portScript.sql(present in the foldersrc/sql) in the development db port (for a standard configuration the database has name<PROJECT_NAME>Port). The script is written for a versionproduction(edit if the version of the environment is different). Edit the structure of the profile model if needed.Perform tasks detailed in the file
servScript.sql(present in the foldersrc/sql) in the development db serv (for a standard configuration the database has name<PROJECT_NAME>Serv).Perform tasks detailed in the file
portTestScript.sql(present in the foldersrc/sql) in the test db port (for a standard configuration the database has name<PROJECT_NAME>testPort).Perform tasks detailed in the file
servTestScript.sql(present in the foldersrc/sql) in the test db serv (for a standard configuration the database has name<PROJECT_NAME>testServ).Copy the contents of the folder
src/java/main/comin the folder<PROJECT_NAME>/src/comof your project.Copy the contents of the folder
src/java/test/testin the folder<PROJECT_NAME>/src/testof your project.Copy in the folder
<PROJECT_NAME>/src/of your project the file namedjpuserreg_japs-struts-plugin.xmlcontained in the foldersrc/java/main. If in the foldersrcof the Eclipse project is already present one file with namedjaps-struts-plugin.xml, copy the content of the tag <struts> of the filejpuserreg_japs-struts-plugin.xmlinto the existing filejaps-struts-plugin.xmland delete the filejpuserreg_japs-struts-plugin.xml. If the foldersrcof the Eclipse project there is not a file namedjaps-struts-plugin.xml, rename the filejpuserreg_japs-struts-plugin.xmltojaps-struts-plugin.xml.To verify the correct send of emails in the jUnit tests, change the constant
EMAILof th classJpUserRegTestHelper.javain the packagetest.com.agiletec.plugins.jpuserreg.
After performing the steps above, start the project from Eclipse and configure using the administrative interface, pages needed to run the plugin, as described in the following paragraphs. Yuo need also to customize the jsp.
In your configuration for the plugin User Profile
need to be presents 4 attributes Name, Surname, email and Language,
configured as in the example:
Example 3.1.
Example of configuration for 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>
important: attribute email must be declared searchable
The email attribute must be, , searcheable this to be able to recover user information by email. Such as occurs in the password recovery feature via email request. To successfully run JUnit tests verify the configuration of email attribute in the profile configuration in the test database.
Note the name assigned to these attributes, as will be necessary
to the configuration of the plugin Reg User.
The jpmail plugin need to be configured at least of one sender whit a
valid email address. This will be used for comunication with the user
during the registration procedure and the reactivation procedure.
Example 3.2.
Example of configuration for jpmail plugin
<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>
Note the code attribute
used for email send.
Check, and if need edit, the parameter
applicationBaseURL into file
/WebContent/META-INF/context.xml,
it must be set to the full URL of the portal.
Example:
<Environment name="applicationBaseURL" value="http://localhost:8080/PortalExample/" type="java.lang.String" override="false" />
The plugin configuration is defined on a xml file (loaded
into Port database of jAPS 2.0 ). In that file
are defined elements of configuration needed for user generation and
user profile generation and also configuration for emails
for registratione and reactivation procedures.
An example of required configurations:
<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>
Details and meanings for the configuration params
Parameter profileEntity - this param contains attribute's names to make the matching with
User Profileplugin for attributes name, surname, language and emailParameter tokenValidity - this is the expiration time for the token of activation, sent to the user with an email. Spent this time the token will be invalidated and will not be more usable for activation.
Parameter sender - This param contains the email sender for matching with the plugin
Mail.Parameter userAuthDefaults - this optional param allow to define roles and groups that will be assigned to the new account created during registration to portal.
Parameter activation - this param contains the configuration for the email of confirm message for account activation. It contains also the code of the page for activation, the value is setted into the attribute pageCode. Within the parameter activation is present at the least one element template corresponding to the default language of the portal. In the optimal situation is preferable to create a template for each language defined within the portal. Each element template contains one element subject and one element body . The body element can be customized with params that will be replaced at runtime. There are the following params:
{name}: the user name (that one configured on the attribute for the name into the profile )
{surname}: the surname il cognome.
{link}: the link for activation, it's mandatory for operation.
Parameter reactivation - this param contains the configuration for email of confirmation of account reactivation. It contains also the page code for the page of reactivation into the attribute pageCode . In addition to that specified in the preceding paragraph for the elements subject and body You can insert an element inside the body so defined:
{userName}: the username of the user.
The User Reg plugin needs some pages to work correctly.
These pages need to be created.
Each created pages contains one of the showlets of the plugin.
If you use the recommended names given in the next table will not need to change
codes of the pages in the showlet.
For simplify page management is recommended to create all of them like childs
of one page, at example called "User Management", not visible on menu.
Appropriately customize the showlet of login from the plugin
jpuserreg_loginUserReg
(/WEB-INF/plugins/jpuserreg/aps/jsp/showlets/jpuserreg_loginUserReg.jsp)
or customize login showlet of the portal with new links for registration and account management.
In the showlet
Nella showlet jpuserreg_loginUserReg there are links for pages:
registr, passwordrecover and disactiv.
This codes must match the codes of: the page for registration, the page for the password recover and
the page for account disactivation.
hese pages must be configured with showlets like in the following table.
In the showlet there is a link for page for editing profile/password
(the default page code is editprof_page_code, customize if necessary).
If there isn't on portal page for editng profile/password remove the link.
For details on configuration of page for editing profile/password refer
to documentation of plugin jpuserprofile.
Table 3.1. Pages configuration
| Page code | Showlet name |
|---|---|
| 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) |
The code of the page activation must be equal to that one into the xml configuration
of the plugin in table sysconfig into the Port database.
Example 3.3.
Example of definition for parameter
pageCode
for account activation
<activation pageCode="activation"> <template lang="it"> ......... </template> </activation>
The page code recover must be equal to that one
inserted into the plugin configuration.
Example 3.4.
Example of configuration for parameter
pageCode
for account activation or recover
<reactivation pageCode="recover"> <template lang="it"> ......... </template> </reactivation>
The presentation layer need to be customized to portal style.
The resources are:
those in the folder:
/WEB-INF/plugins/jpuserreg/aps/jsp/externalFramework/userreg/
and the showlet in
/WEB-INF/plugins/jpuserreg/aps/jsp/showlets/
next description for the jsp files:
activation/activateUser.jspcontains the form for users registration.activation/activateUserError.jspcontains the error message for activation of account with invalid or expired ticket.activation/confirmedUserActivation.jspcontains the confirm that the request for registration was received and the sending of an email for end the procedure.activation/reactivateUser.jspcontains form for end registration with password definition.activation/reactivateUserError.jspcontains the error message for riactivation of account with invalid or expired ticket.activation/confirmedUserReactivation.jspcontains message for successfully happened reactivation of accountrecover/recoverUser.jspthis is the form for recovering the account from email or from username.recover/confirmedRecoverRequest.jspmessage of confirmation for receipt of request for account recover.registration/registerUser.jspthe form new account registration.registration/confirmedUserRegistration.jspmessage of confirmation for receipt of request for account registration.suspension/confirmSuspend.jspform for account suspension request.error.jspcontains the error message for failed attempt of account suspension (administration user or user that is not from the local user database).
Probably you need also to customize labels for the JSPs, used with tag
wp:i18n
.
