Ellipse Framework Tutorial - Comment utiliser le composant <web:DatePicker> ?

ATTENTION : Tutorial en cours d'écriture ! N'hésitez pas à nous signaler toute erreur ou suggestion.

Accès rapide :
Utilisation sous forme de composant JWT
Activation du mode d'édition rapide
Gestion de l'internationalisation
Gestion des événements en Javascript
Utilisation sous forme de composant Ellipse
Adaptez le look de votre composant DatePicker

De manière interne au framework Ellipse, le composant DatePicker est fournit sous forme de composant JWT (Javascript Widget Toolkit). Il peut donc être utilisé directement en Javascript. Néanmoins, ce composant Web est aussi encapsulé dans un composant Web Ellipse : le composant <web:DatePicker />. Cette seconde possibilité permet d'utiliser trés simplement le composant Web comme étant un élément de formulaire, avec transport de la date saisie jusqu'au serveur HTTP et au gestionnaire d'événements côté serveur. Commençons, dans un premier temps, à appréhender l'utilisation du composant sous forme de composant JWT.

Utilisation sous forme de composant JWT

Commençons par créer un nouveau projet Ellipse pour y tester nos composants de sélection de date. Pour ce faire, ouvrez Eclipse et placez-vous dans le workspace souhaité. Au niveau de la vue "Package Explorer", cliquez avec le bouton droit de la souris et sélectionnez "New / Other... / Java Web Development / Java Web Project". La boîte de dialogue de construction du projet apparaît : vous devez saisir comme nom de projet "TestDatePickers", configurez votre serveur Web, cliquez sur "Next" puis vérifiez la présence de la facette Ellipse. Enfin, cliquez sur "Finish". En cas de demande de chargement de perspective, acceptez ce changement. Votre projet Web est maintenant créé.

Il vous faut maintenant créer une nouvelle page Web avec le support Ellipse pour le script client (en langage Javascript, bien entendu). Pour ce faire, cliquez avec le bouton droit de la souris sur votre projet (dans la vue "Package Explorer", bien entendu). Sélectionnez "New / Web Page" : une boîte de dialogue apparaît. Renseignez-y le nom "JwtDatePicker.wp" et prenez soin d'activer le support pour le code côté client ("Supports Client Side").

Deux fichiers viennent d'être créés : JwtDatePicker.wp et JwtDatePicker.js. Ne cherchez pas le tag <script> de changement du fichier Javascript dans la page Web : le framework Ellipse garantira un chargement implicite de ce fichier. Rajoutez dans la page web (dans le body) le code HTML suivant.

01 <?xml version="1.0" encoding="ISO-8859-1" ?>
02 <web:Html xmlns:web="corelib.services.web.components"
03           codeBehind="corelib.services.web.webapplications.WebPage">
04     <head>
05         <title>DatePicker Tests</title>
06         <link rel="stylesheet" type="text/css"
07               href="corelib/services/web/javascript/jwt/Jwt.css" />
08     </head>
09     <body>
10         <h1 align="center">DatePicker Tests</h1>
11 
12         <div id="forFrenchJwtDatePicker" style="width: 200px"> </div>
13 
14     </body>
15 </web:Html>

JwtDatePicker.wp : On défini notamment un tag qui servira de conteneur pour le composant DatePicker

Ensuite, vous devrez éditer la partie de code client (code Javascript) afin d'injecter votre composant dans le div. Bien entendu, l'injection ne pourra se faire qu'après que le tag HTML ait été mis en place : d'où l'utilisation du gestionnaire d'événements onload.

01 importPackage( "corelib/services/web/javascript/jwt/DatePicker.js" );
02 
03 addEventHandler( window, "onload", function ( event ) {
04     var frenchJwtDatePicker = new DatePicker( new Date( 2008, 0, 1 ), new Locale( "fr" ) );
05     frenchJwtDatePicker.injectInDocument( document.getElementById( "forFrenchJwtDatePicker" ) );
06 });

JwtDatePicker.js : Instanciation et injection, par Javascript, de votre composant

Il est a noter que le constructeur du composant DatePicker peut accepter deux paramètres. Le premier correspond à la date initialement sélectionnée par votre composant (à défaut c'est la date du jour qui sera considérée). Le second permet de fixer la langue à utiliser pour l'affichage.

Il faut maintenant déployer votre application Web dans votre serveur J2EE. Pour ce faire, cliquez avec le bouton droit de la souris sur votre projet (toujours dans la vue "Package Explorer"), puis sélectionnez "Run As / Run on serveur" : acceptez le déploiement sur le serveur. Enfin prenez votre navigateur favoris et invoquez l'URL adaptée : certainement http://localhost:8080/TestDatePickers/JwtDatePicker.wp : un composant DatePicker similaire à celui-ci devrait apparaître.

Activation du mode d'édition rapide

Il est a noter que le composant DatePicker accepte deux modes d'édition. La section précédente vous a présenté le composant en mode d'édition standard. Il est néanmoins possible de configurer vos composants en mode d'édition rapide (QuickEdit mode). Pour ce faire, il vous suffit d'invoquer la méthode setDisplayMode et lui passant le paramètre DatePicker.QUICK_EDIT. En voici un petit exemple.

01 importPackage( "corelib/services/web/javascript/jwt/DatePicker.js" );
02 
03 addEventHandler( window, "onload", function ( event ) {
04     var frenchJwtDatePicker = new DatePicker( new Date( 2008, 0, 1 ), new Locale( "fr" ) );
04     frenchJwtDatePicker.setDisplayMode( DatePicker.QUICK_EDIT );
06     frenchJwtDatePicker.injectInDocument( document.getElementById( "forFrenchJwtDatePicker" ) );
07 });

JwtDatePicker.js : Définition d'un composant DatePicker en mode QuickEdit

Voici le résultat produit par ces quelques lignes de code. Notez bien que dans ce mode (QuickEdit), seuls quatre clicks souris sont nécessaire pour sélectionner une nouvelle date, et ce quelque soit l'année considérée.

Gestion de l'internationalisation

De manière similaire à Java, le librairie JWT propose aussi une classe Locale permettant la gestion de la localisation (langages et pays utilisés par vos composants). Le composant JWT DatePicker supporte pour l'heure deux langues pour son affichage : le français et l'anglais (utilisé par défaut) et ne tient pas compte de l'information de localisation géographique. En passant cette instance new Locale("fr"), votre composant devrait s'afficher en français. En utilisant la valeur "en", il devrait s'afficher en anglais.

Gestion des événements en Javascript

Comme présenté dans certains autres documents de ce tutorial, le framework Ellipse, et plus précisément la librairie JWT, propose des extensions pour la gestion des événements en Javascript. Le composant JWT DatePicker tire profit de ces extensions et permet de réagir à un changement de sélection de date du composant. Pour ce faire, rajoutez un gestionnaire à l'événement onDateSelected de votre composant. Les exemples de codes suivants montrent comment modifier une zone de saisie de texte en cas de changement de date.

01 <?xml version="1.0" encoding="ISO-8859-1" ?>
02 <web:Html xmlns:web="corelib.services.web.components"
03           codeBehind="corelib.services.web.webapplications.WebPage">
04     <head>
05         <title>DatePicker Tests</title>
06         <link rel="stylesheet" type="text/css"
07               href="corelib/services/web/javascript/jwt/Jwt.css" />
08     </head>
09     <body>
10         <h1 align="center">DatePicker Tests</h1>
11 
12         <div id="forFrenchJwtDatePicker" style="width: 200px"> </div>
13         <div>Selected date = <input id="forSelectedDate" /></div>
14 
15     </body>
16 </web:Html>

JwtDatePicker.wp : On rajoute un champ <input /> (ligne 13)

01 importPackage( "corelib/services/web/javascript/jwt/DatePicker.js" );
02 
03 addEventHandler( window, "onload", function ( event ) {
04     var frenchJwtDatePicker = new DatePicker( new Date( 2008, 0, 1 ), new Locale( "fr" ) );
05     frenchJwtDatePicker.injectInDocument( document.getElementById( "forFrenchJwtDatePicker" ) );
06     addEventHandler( frenchJwtDatePicker, "onDateSelected", function( event ) {
07         document.getElementById( "forSelectedDate" ).value = frenchJwtDatePicker.getSelectedDate();
08     });
09 });

JwtDatePicker.js : On rajoute le gestionnaire d'événements (ligne 06)

Un petit test du gestionnaire d'événements :

Selected date =

Utilisation sous forme de composant Ellipse

L'utilisation du composant DatePicker en tant que composant web Ellipse est encore plus simple qu'en JWT. Qui plus est, le transport de la date saisie jusqu'au serveur HTTP est automatiquement prise en charge et le support de gestionnaires d'événements côté serveur est offert. Le composant <web:DatePicker /> est proposé par le biais du package corelib.services.web.components : il faut donc utiliser l'espace de nom (namespace) XML adapté. Voici un exemple d'utilisation sous forme de composant Ellipse.

Je vous conseille de créer (via le plugin Ellipse et l'assistant de création de page Web) une nouvelle page Web appelée DatePickerSamples.wp. Pensez à ajouter un classe de code coté serveur (classe corelib.services.web.samples.virtualcaddy.webpages.samples.DatePickerSamples).

01 <?xml version="1.0" encoding="ISO-8859-1" ?>
02 <web:Html xmlns:web="corelib.services.web.components"
03           codeBehind="corelib.services.web.samples.virtualcaddy.webpages.samples.DatePickerSamples">
04     <head>
05         <title>DatePicker Tests</title>
06         <link rel="stylesheet" type="text/css"
07               href="corelib/services/web/javascript/jwt/Jwt.css" />
08     </head>
09     <body>
10         <h1 align="center">DatePicker Tests</h1>
11 
12         <web:Form method="POST">
13             <web:DatePicker id="calDemo2" cssStyle="width: 200px;" autoPost="true" />
14             Selected date is : <web:TextBox id="txtDate" /> <br/>
15         </web:Form>
16 
17     </body>
18 </web:Html>

DatePickerSamples.wp : Utilisation sous forme d'un composant Ellipse (ligne 13)

Remarque importante : si vous utilisez ce composant comme un champ de formulaire, alors il ne faudra pas oublier d'inclure un formulaire dans votre page web. Notez aussi que dans ce cas, aucune ligne de code Javascript n'est requise, contrairement à l'exemple exploitant la librairie JWT. En fait ces lignes seront générées automatiquement par le serveur Web lors du traitement de la page Web.

Si vous souhaitez exploiter les mécanismes de gestion d'événements côtés serveur, il vous suffit de rajouter la classe de code serveur suivante. Elle rajoute un écouteur de type FormInputListener afin de réagir à un changement de valeur. En tant que champ de formulaire, le composant DatePicker propose aussi la propriété autoPost : elle permet de forcer automatiquement une soumission du formulaire au serveur dès lors qu'un changement de date intervient au sein du navigateur. Il se peut que cette propriété ne vous intéresse pas toujours.

01 package corelib.services.web.samples.virtualcaddy.webpages.samples;
02 
03 import corelib.services.web.components.DatePicker;
04 import corelib.services.web.components.TextBox;
05 import corelib.services.web.components.events.FormInputEvent;
06 import corelib.services.web.components.events.FormInputListener;
07 import corelib.services.web.webapplications.WebPage;
08 import corelib.services.web.webapplications.events.WebPageEvent;
09 
10 public class DatePickerSamples extends WebPage {
11 
12 	private DatePicker dpDemo2;
13 	private TextBox txtDate;
14 	
15 	
16 	@Override public void page_load( WebPageEvent webPageEvent ) {
17 		dpDemo2.addFormInputListener( new FormInputListener() {
18 			@Override public void valueChanged( FormInputEvent event ) {
19 				dpDemo2_valueChanged( event );
20 			}
21 		});
22 	}
23 	
24 	public void dpDemo2_valueChanged( FormInputEvent event ) {
25 		txtDate.setValue( dpDemo2.getSelectedDate().toString() );		
26 	}
27 	
28 }

DatePickerSamples.java : Classe de code serveur ratachée à la page web

Pour ce qui est de l'internationalisation de votre composant <web:DatePicker />, il est à noter que cela fonctionne de la même manière que pour le composant <web:Calendar />. Je vous renvois donc vers la fiche technique de ce dernier composant pour de plus amples informations.

Bien entendu, vous pouvez aussi configurer votre composant <web:DatePicker /> pour supporter le mode d'édition rapide. Pour ce faire, il vous faudra ajouter l'attribut XML displayMode, comme le montre l'exemple ci-dessous.

01    <web:DatePicker id="calDemo3" cssStyle="width: 300px;" displayMode="quick_edit" />

Exemple d'utilisation du composant en mode QuickEdit.

Adaptez le look de votre composant DatePicker

Le composant <web:DatePicker /> utilise notamment un composant <web:Calendar /> pour son affichage. Les principaux besoins en terme de look and feel sont donc relatifs au composant de calendrier. Pour de plus amples informations, je vous renvois donc encore une fois vers la fiche technique de ce composant.