Get ZK Up and Running with MVC fr"

From Documentation
m
Line 14: Line 14:
  
  
 +
= Objectif du tutoriel =
 +
Notre application consiste simplement en un catalogue de voitures. Cette application a deux fonctions:
 +
# Chercher des voitures.
 +
#: Entrez un mot-clé dans le champ d'entrée, cliquez <b>Search</b> et les résultats seront affichés dans la liste en dessous.
 +
# Voir les détails.
 +
#: Cliquez sur un élément de la liste, la zone sous la liste de voiture affichera alors les détails de la voiture sélectionnée dont le modèle, le prix, une description et un aperçu.
  
  
{{Template:tutorial common chapters}}
+
[[File:tutorial-searchexample.png| 400px | center]]
 +
 
 +
= Échauffement =
 +
 
 +
Cette section vous guide pour mettre en place un projet et utiliser ZK dans Eclipse. Si vous voulez d'abord savoir comment construire l'application avec ZK, démarrez d'abord depuis [[#Declaring Domain Class| Declaring Domain Class]]. Pour commencer, nous allons voir comment préparer un environnement pour construire une application web ZK à savoir configurer l'IDE, installer ZK et lancer l'application dans un serveur.
 +
 
 +
 
 +
==Configurer Eclipse ==
 +
 
 +
Dans ce tutoriel, Eclipse IDE 3.7 (indigo) pour Java EE developer [[File:Eclipse-javaee.png]] est utilisé pour montrer la construction de l'application 'catalogue de voitures'. ([http://www.eclipse.org/downloads/packages/release/indigo/sr2 Télécharger Eclipse] ici, extraire le fichier zip téléchargé dans un dossier et exécuter eclipse.exe pour lancer Eclipse.)
 +
 
 +
Pour pouvoir éditer les pages ZK UI dans Eclipse, ajoutez "zul" (nom des extensions des fichiers ZK UI) comme type de contenu de format XML en suivant les étapes suivantes:
 +
 
 +
# Sélectionnez '''Window \ Preferences''' pour ouvrir la fenêtre Preferences
 +
# À gauche, sélectionnez '''General --> Content Types'''. À droite, ouvrez le nœud ''Text''' dans la boîte "Content types" et sélectionnez '''XML'''
 +
# Cliquez sur '''Add''' et ajoutez le type de contenu que vous souhaitez ajouter à savoir '''*.zul''' dans ce cas-ci, ensuite cliquez sur '''OK'''
 +
 
 +
[[File:Tutorial-add-contenttype.png| 400px | center]]
 +
 
 +
 
 +
Une fois ceci terminé, Eclipse va utiliser l'éditeur XML pour ouvrir votre fichier zul.
 +
 
 +
== Installer ZK dans un Web Project==
 +
 
 +
'''Télécharger ZK'''
 +
 
 +
[http://www.zkoss.org/download/zk Téléchargez d'abord le ZK CE ] (le nom du fichier sera du genre ''zk-bin-[version].zip'') et extrayez le dans un dossier.
 +
 
 +
 
 +
'''Créer un Project'''
 +
 
 +
Pour construire une application web, il faut d'abord créer un "Dynamic Web Project" dans Eclipse:
 +
# Sélectionnez '''File \ New \ Dynamic Web Project'''
 +
# Entrez '''tutorial''' comme nom du Project et laissez le reste par défaut.
 +
 
 +
[[File:Tutorial-newproject.png | 400px | center]]
 +
 
 +
* Vous pouvez laisser "Target runtime" à "none".
 +
* Notez que l'on met la valeur de '''Dynamic web module version''' à 3.0 parce-que nous voulons utiliser Servlet 3.0 pour supprimer la configuration de l'application.
 +
 
 +
 
 +
'''Installer ZK JAR'''
 +
 
 +
Pour utiliser ZK dans votre projet, vous devez copier les fichiers ZK JAR dans le dossier des librairies de votre projet.
 +
 
 +
Copiez les fichiers JAR depuis le répertoire suivant vers '''WebContent\WEB-INF\lib''':
 +
* {YOUR_ZK_UNZIP_FOLDER}\dist\lib
 +
* {YOUR_ZK_UNZIP_FOLDER}\dist\lib\ext
 +
 
 +
 
 +
<div style="-webkit-border-radius:10px;-moz-border-radius:10px;border-radius:10px;-moz-background-clip:padding;-webkit-background-clip:padding-box;background-clip:padding-box;color:#c06330;padding:15px 40px;background:#fed no-repeat 13px 13px;margin-bottom:10px
 +
">
 +
[[File:Icon_info.png ]]    Si vous préférez utiliser un serveur d'applications qui supporte '''des spécifications Servlet (< 3.0)''' plus anciennes ou '''JDK 1.5''', vous devez ajouter des configurations supplémentaires dans web.xml. Merci de vous référer au Guide d'Installation ZK. <ref> [[ZK Installation Guide/Quick Start/Create and Run Your First ZK Application Manually| ZK Installation Guide \ Create and Run Your First ZK Application Manually]] </ref>
 +
</div>
 +
 
 +
 
 +
'''Créer une page simple'''
 +
 
 +
Après l'installation, vous pouvez créer un zul simple pour vérifier que l'installation fonctionne correctement.
 +
 
 +
Dans Eclipse,
 +
# Sélectionnez '''File \ New \ File''' (or '''File \ New \ Other \ File''' ) pour ajouter un nouveau fichier, '''hello.zul''', dans '''WebContent'''.
 +
# Cliquez sur '''Source'''  pour modifier la source.
 +
#: [[File:Tutorial-xmleditor.png| 400px | frame| center|c|creating a zul-file in eclipse's xml editor]]
 +
# Copiez et collez l'extrait de code suivant dans hello.zul et enregistrez.
 +
 
 +
'''hello.zul'''
 +
<source lang="xml">
 +
<window title="My First ZK Application" border="normal">
 +
Hello World!
 +
</window>
 +
</source>
 +
 
 +
 
 +
 
 +
 
 +
Maintenant, dans la vue '''Project Explorer''', votre projet devrait ressembler à ceci:
 +
 
 +
[[File:Tutorial-project-structure.png | 200px | center]]
 +
 
 +
Si vous ne trouvez pas la vue '''Project Explorer''', sélectionnez le menu '''Window \ Show View \ Project Explorer''' pour l'ouvrir.
 +
 
 +
== Lancer une Application ==
 +
<!--
 +
將 new server 及 run on the server 分成兩個步驟,後面的章節可隨時依照run on the server的步驟執行範例程式
 +
-->
 +
 
 +
 
 +
Avant de lancer une application web, nous devons créer un serveur dans Eclipse. Sélectionnez '''Window \ Preferences''' pour ouvrir la fenêtre Preferences et sélectionnez '''Server \ Runtime Environments''' sur la gauche. Cliquez sur '''Add''' pour ajouter un environnement d'exécution de serveur.
 +
 
 +
[[File:Tutorial-preference-server.png | 400px | center]]
 +
 
 +
 
 +
Sélectionnez '''Apache \ Tomcat v7.0 Server''' vu qu'il supporte Servlet 3.0 et cochez '''Create a new local server''', cliquez ensuite sur '''Next'''.
 +
 
 +
<div style="-webkit-border-radius:10px;-moz-border-radius:10px;border-radius:10px;-moz-background-clip:padding;-webkit-background-clip:padding-box;background-clip:padding-box;color:#c06330;padding:15px 40px;background:#fed no-repeat 13px 13px;margin-bottom:10px
 +
">
 +
[[File:Icon_info.png ]]    Si vous utilisez JDK 1.5, vous pouvez utiliser Tomcat v6.0 mais il faudra faire davantage de configurations dans web.xml. Merci de voir le ZK Installation Guide dans [[#References| References]] .
 +
</div>
 +
 
 +
[[File:Tutorial-newserver.png | 400px | center]]
 +
 
 +
 
 +
 
 +
Si vous avez précédemment installé Tomcat 7, fournissez simplement le chemin du répertoire. Si vous ne l'avez pas, suivez les étapes suivantes:
 +
# Cliquez sur '''Download and Install''' et choisissez un répertoire.
 +
#: '''Notez que le chemin d'installation ne peut contenir aucun caractère non-ASCII.'''
 +
#: [[File:Tutorial-downloadinstall.png | 400px | center]]
 +
# Acceptez la licence et attendez.
 +
#: '''Eclipse affichera un message d'erreur avant que l'installation ne s'achève, ignorez le.'''
 +
#: [[File:Tutorial-installing-unknown.png | 400px | center]]
 +
#: '''Patientez et n'interrompez pas l'installation pour être certain qu'elle s'effectue correctement.'''
 +
#: [[File:Tutorial-installing-progress.png | center]]
 +
#: Eclipse va télécharger et installer Tomcat dans le dossier que vous avez spécifié. 
 +
# Lordque l'installation est finie, cliquez sur '''Finish'''
 +
 
 +
 
 +
Vous devriez maintenant voir une nouvelle entrée dans '''Server runtime environments'''.
 +
 
 +
[[File:Tutorial-server-complete.png | 500px | center]]
 +
 
 +
 
 +
 
 +
Faites un clique droit sur hello.zul et sélectionnez '''Run As \ Run on Server''' pour faire tourner ce zul sur un serveur d'applications.
 +
 
 +
[[File:Tutorial-runonserver.png | 500px | center]]
 +
 
 +
 
 +
 
 +
Choisissez un Tomcat 7. Vous pouvez aussi cocher l'option '''Always use this server when running this project''' pour ne pas devoir choisir un serveur à chaque fois que vous lancerai l'application par la suite. Cliquez sur '''Finish''' et attendez que le serveur démarre.
 +
 
 +
[[File:Tutorial-choose-server.png | 400px | center]]
 +
 
 +
 
 +
 
 +
Une fois le serveur démarré, Eclipse va ouvrir un browser et vous connecter automatiquement à http://localhost:8080/tutorial/hello.zul . Si vous voyez l'image suivante, alors votre projet est prêt pour utiliser ZK.
 +
 
 +
[[File:Tutorial-hello.png | 400px | center]]
 +
 
 +
Vous pouvez revenir ici et suivre à nouveau ces étapes pour lancer votre application au cours de ce tutoriel
 +
 
 +
== Importer et lancer l'Application exemple ==
 +
 
 +
Nous avons préparé un ficher zip projet Eclipse qui contient le code source complet, vous pouvez le télécharger et l'importer dans votre Eclipse sans avoir à démarrer tout de 0.
 +
 
 +
Pour utiliser l'application exemple, suivez les étapes suivantes:
 +
# [http://sourceforge.net/projects/zkbook/files/GettingStarted/getzkup-20131127.zip/download Téléchargez le fichier zip du projet].
 +
# Dans Eclipse, sélectionnez '''File \ Import \ General \ Existing Projects into Workspace''', choisissez '''Select archive file''' pour importer le zip de l'application comme  projet dans Eclipse.
 +
# Suivez ensuite les instructions de [[#Run an Application |Run an Application]] pour lancer l'application.
 +
 
 +
<!--
 +
Nous décrivons les objets domaine ici pcq cette section est indépendante des sections MVC et MVVM et la partie domaine est identique pour ces 2 design patterns.
 +
-->
 +
 
 +
= Déclaration des classes du domaine =
 +
 
 +
Ce qui suit est l'objet du domaine qui représente une voiture.
 +
 
 +
<source lang="java">
 +
 
 +
public class Car {
 +
private Integer id;
 +
private String model;
 +
private String make;
 +
private String preview;
 +
private String description;
 +
private Integer price;
 +
//omit getter and setter for brevity
 +
}
 +
</source>
 +
* Merci de vous référer à la section References pour voir le code complet. <ref> [https://code.google.com/p/zkbooks/source/browse/trunk/gettingStarted/getZkUp/src/tutorial/Car.java Car.java] </ref>
 +
 
 +
On définit ensuite une classe de service pour effectuer la logique business (chercher des voitures) tel que montré ci-dessous:
 +
 
 +
<source lang="java">
 +
public interface CarService {
 +
 
 +
/**
 +
* Retrieve all cars in the catalog.
 +
* @return all cars
 +
*/
 +
public List<Car> findAll();
 +
 +
/**
 +
* search cars according to keyword in  model and make.
 +
* @param keyword for search
 +
* @return list of car that match the keyword
 +
*/
 +
public List<Car> search(String keyword);
 +
}
 +
</source>
 +
 
 +
Dans cet exemple, nous avons défini une classe - <tt>CarServeImpl</tt> qui implémente l'interface ci-dessus. Par soucis de simplicité, elle utilise une liste objet statique comme modèle de données. Vous pouvez la réécrire de sorte qu'elle se connecte à une base de données dans une application réelle. Les détails de l'implémentation ne sont pas l'objet de cet article, merci de vous référer à la section References.<ref> [https://code.google.com/p/zkbooks/source/browse/trunk/gettingStarted/getZkUp/src/tutorial/CarService.java CarService.java] [https://code.google.com/p/zkbooks/source/browse/trunk/gettingStarted/getZkUp/src/tutorial/CarServiceImpl.java CarServiceImpl.java] </ref>
 +
 
 +
=Construire l'interface utilisateur =
 +
 
 +
Le design de l'UI est un bon début pour construire une application vu qu'il vous aide à définir l'étendue de votre application. ZK fournit des centaines de composants UI prêts à l'emploi de sorte que les développeurs peuvent rapidement construire l'interface utilisateur de leur choix en combinant et en mélangeant ces composants sans avoir à les créer.
 +
 
 +
Dans ZK, vous pouvez utiliser ZK User Interface Markup Language (ZUML) <ref> [[ZUML Reference|ZUML Reference]] </ref>, un langage formaté XML, pour décrire les UI. Suivant la convention ZK, les fichiers décrivant les UI avec ZUML utilisent comme suffixe '''.zul'''. Dans les fichiers zul, un composant peut être représenté comme un élément XML (tag) et vous pouvez configurer pour chaque composant son style, son comportement et sa fonction via les attributs XML de cet élément.<ref> [[ZK Component Reference|ZK Component Reference]] </ref>
 +
 
 +
Dans cet exemple, nous voulons d'abord concevoir une fenêtre avec un titre spécifique et un bord normal qui sera la fenêtre de notre application.
 +
 
 +
 
 +
'''Extrait de search.zul'''
 +
<source lang="xml">
 +
 
 +
<window title="Search" width="600px" border="normal">
 +
<!-- put child components inside a tag's body -->
 +
</window>
 +
</source>
 +
 
 +
Vu que ''window'' et le composant 'englobant' principal, il est appelé ''root component''. ''Window'' est un container souvent utilisé parce-que c'est un élément d'affichage de base d'une application de type bureau et qui peut en même temps contenir d'autres composants. Tous les autres composants inclus dans ''window'' sont appelés ''child components'' et doivent être placés dans le body de la fenêtre. Nous mettons un texte dans la barre de titre de ''window''' grâce à l'attribut "title" et nous faisons en sorte que ''window'' s'affiche avec un bord normal grâce à l'attribut "border". Pour l'attribut "width", utilisez une syntaxe de type CSS comme "800px" ou "60%".
 +
 
 +
 
 +
De base, l'UI de notre application est divisée en 3 zones à l'intérieur de ''window'' qui sont, de haut en bas, la fonction de recherche, la liste des voitures et les détails de la voiture.
 +
 
 +
[[File:Tutorial-ui-3areas.png | 400px |center]]
 +
 
 +
 
 +
'''Zone de recherche:'''
 +
Les composants ZK sont comme des blocs à construire, vous pouvez combiner et mélanger les composants existants pour construire l'UI de votre choix. Pour permettre aux utilisateurs d'effectuer des recherches, il faut un texte incitant les utilisateurs à entrer une valeur, un endroit pour qu'ils tapent effectivement cette valeur-clé et un bouton qui va déclencher la recherche. Nus pouvons utiliser dans ce but les composants ZK suivants:
 +
 
 +
'''Extrait de search.zul'''
 +
<source lang="xml">
 +
 
 +
<hbox align="center">
 +
Keyword:
 +
<textbox id="keywordBox" />
 +
<button id="searchButton" label="Search" image="/img/search.png" />
 +
</hbox>
 +
 
 +
</source>
 +
 
 +
<tt>hbox</tt> est un composant de layout qui organise ses enfants de manière horizontale et vous avez donc deviné que le '''h''' signifie ''horizontal''. Vu que ces composants enfants ont des hauteurs différentes, nous mettons la valeur "center" à l'attribut "align" pour les aligner sur une ligne centrale. On spécifie aussi ici un attribut "id" pour certains composants de manière à pouvoir ensuite les contrôler grâce à cet ''id''. Vous pouvez aussi facilement afficher une image sur le bouton en spécifiant le chemin de celle-ci dans l'attribut "image".
 +
 
 +
 
 +
'''Zone de liste des voitures.'''
 +
ZK fournit quelques composants qui permettent d'afficher des collections de données comme ''listbox'', ''grid'', et ''tree''. Dans cet exemple, nous allons utiliser une ''listbox'' pour afficher une liste de voitures sur 3 colonnes: Model, Make et Price. Nous mettons l'attribut "height" à une valeur qui limite le nombre de lignes à une hauteur spécifiée; vous pouvez bouger la scroll-bar pour visualiser les autre lignes. L'attribut "emptyMessage" est utilisé pour afficher un message lorsque la ''listbox'' ne contient aucun élément. La ''listbox'' est un composant container et vous pouver ajouter ''listhead'' pour définir une colonne. Le ''listitem'' est utilisé pour afficher les données et le nombre de ''listcell'' dans un ''listitem'' doit être égal au nombre de ''listheader''. On utilise ici ''listcell'' avec un label statique pour montrer la structure d'un ''listitem'' et nous verrons comment créer dynamiquement un ''listitem'' qui respecte chaque objet de données dans le chapitre suivant.
 +
 
 +
'''Extrait de search.zul'''
 +
<source lang="xml">
 +
<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">
 +
<listhead>
 +
<listheader label="Model" />
 +
<listheader label="Make" />
 +
<listheader label="Price" width="20%"/>
 +
</listhead>
 +
<listitem>
 +
<listcell label="car model"></listcell>
 +
<listcell label="make"></listcell>
 +
<listcell>$<label value="price" /></listcell>
 +
</listitem>
 +
</listbox>
 +
</source>
 +
 
 +
 
 +
'''Zone de détail des voiture.'''
 +
Comme ''hbox'', ''vbox'' est aussi un composant de layout qui arrange ses composants enfants en ordre vertical. En combinant ces 2 composants de layout, nous pouvons présenter davantage d'informations sur un écran. L'attribut "style" vous permet de customiser le style du composant avec une syntaxe CSS.
 +
 
 +
'''Extrait de search.zul'''
 +
<source lang="xml">
 +
<hbox style="margin-top:20px">
 +
<image id="previewImage" width="250px" />
 +
<vbox>
 +
<label id="modelLabel" />
 +
<label id="makeLabel" />
 +
<label id="priceLabel" />
 +
<label id="descriptionLabel"/>
 +
</vbox>
 +
</hbox>
 +
</source>
 +
 
 +
 
 +
Vous pouvez visualiser le fichier zul complet grâce au lien dans la section References. <ref> [https://code.google.com/p/zkbooks/source/browse/trunk/gettingStarted/getZkUp/WebContent/search.zul search.zul] </ref>
 +
 
  
 
= Handling UI Logic =
 
= Handling UI Logic =

Revision as of 09:13, 10 April 2014

Introduction

Ce tutoriel est à destination des développeurs d'applications qui ont de l'expérience dans l'écriture de programmes Java. Vous apprendrez des concepts basiques à travers la construction d'une application web moderne avec ZK. L'application que nous allons construire consiste simplement en un catalogue de voitures. Nous allons pour cela utiliser l'approche MVC. Cette approche est à la fois très intuitive et à la fois flexible et vous donne le contrôle total des composants. De plus, vous pouvez aussi choisir l'approche MVVM qui est présentée dans un autre tutoriel. [1]

Vous pouvez télécharger le code source complet avec un fichier zip du projet Eclipse dans la section Import and Run Example Application.


Objectif du tutoriel

Notre application consiste simplement en un catalogue de voitures. Cette application a deux fonctions:

  1. Chercher des voitures.
    Entrez un mot-clé dans le champ d'entrée, cliquez Search et les résultats seront affichés dans la liste en dessous.
  2. Voir les détails.
    Cliquez sur un élément de la liste, la zone sous la liste de voiture affichera alors les détails de la voiture sélectionnée dont le modèle, le prix, une description et un aperçu.


Tutorial-searchexample.png

Échauffement

Cette section vous guide pour mettre en place un projet et utiliser ZK dans Eclipse. Si vous voulez d'abord savoir comment construire l'application avec ZK, démarrez d'abord depuis Declaring Domain Class. Pour commencer, nous allons voir comment préparer un environnement pour construire une application web ZK à savoir configurer l'IDE, installer ZK et lancer l'application dans un serveur.


Configurer Eclipse

Dans ce tutoriel, Eclipse IDE 3.7 (indigo) pour Java EE developer Eclipse-javaee.png est utilisé pour montrer la construction de l'application 'catalogue de voitures'. (Télécharger Eclipse ici, extraire le fichier zip téléchargé dans un dossier et exécuter eclipse.exe pour lancer Eclipse.)

Pour pouvoir éditer les pages ZK UI dans Eclipse, ajoutez "zul" (nom des extensions des fichiers ZK UI) comme type de contenu de format XML en suivant les étapes suivantes:

  1. Sélectionnez Window \ Preferences pour ouvrir la fenêtre Preferences
  2. À gauche, sélectionnez General --> Content Types'. À droite, ouvrez le nœud Text dans la boîte "Content types" et sélectionnez XML
  3. Cliquez sur Add et ajoutez le type de contenu que vous souhaitez ajouter à savoir *.zul dans ce cas-ci, ensuite cliquez sur OK
Tutorial-add-contenttype.png


Une fois ceci terminé, Eclipse va utiliser l'éditeur XML pour ouvrir votre fichier zul.

Installer ZK dans un Web Project

Télécharger ZK

Téléchargez d'abord le ZK CE (le nom du fichier sera du genre zk-bin-[version].zip) et extrayez le dans un dossier.


Créer un Project

Pour construire une application web, il faut d'abord créer un "Dynamic Web Project" dans Eclipse:

  1. Sélectionnez File \ New \ Dynamic Web Project
  2. Entrez tutorial comme nom du Project et laissez le reste par défaut.
Tutorial-newproject.png
  • Vous pouvez laisser "Target runtime" à "none".
  • Notez que l'on met la valeur de Dynamic web module version à 3.0 parce-que nous voulons utiliser Servlet 3.0 pour supprimer la configuration de l'application.


Installer ZK JAR

Pour utiliser ZK dans votre projet, vous devez copier les fichiers ZK JAR dans le dossier des librairies de votre projet.

Copiez les fichiers JAR depuis le répertoire suivant vers WebContent\WEB-INF\lib:

  • {YOUR_ZK_UNZIP_FOLDER}\dist\lib
  • {YOUR_ZK_UNZIP_FOLDER}\dist\lib\ext


Icon info.png Si vous préférez utiliser un serveur d'applications qui supporte des spécifications Servlet (< 3.0) plus anciennes ou JDK 1.5, vous devez ajouter des configurations supplémentaires dans web.xml. Merci de vous référer au Guide d'Installation ZK. [2]


Créer une page simple

Après l'installation, vous pouvez créer un zul simple pour vérifier que l'installation fonctionne correctement.

Dans Eclipse,

  1. Sélectionnez File \ New \ File (or File \ New \ Other \ File ) pour ajouter un nouveau fichier, hello.zul, dans WebContent.
  2. Cliquez sur Source pour modifier la source.
    creating a zul-file in eclipse's xml editor
  3. Copiez et collez l'extrait de code suivant dans hello.zul et enregistrez.

hello.zul

 <window title="My First ZK Application" border="normal">
 	Hello World!
 </window>



Maintenant, dans la vue Project Explorer, votre projet devrait ressembler à ceci:

Tutorial-project-structure.png

Si vous ne trouvez pas la vue Project Explorer, sélectionnez le menu Window \ Show View \ Project Explorer pour l'ouvrir.

Lancer une Application

Avant de lancer une application web, nous devons créer un serveur dans Eclipse. Sélectionnez Window \ Preferences pour ouvrir la fenêtre Preferences et sélectionnez Server \ Runtime Environments sur la gauche. Cliquez sur Add pour ajouter un environnement d'exécution de serveur.

Tutorial-preference-server.png


Sélectionnez Apache \ Tomcat v7.0 Server vu qu'il supporte Servlet 3.0 et cochez Create a new local server, cliquez ensuite sur Next.

Icon info.png Si vous utilisez JDK 1.5, vous pouvez utiliser Tomcat v6.0 mais il faudra faire davantage de configurations dans web.xml. Merci de voir le ZK Installation Guide dans References .

Tutorial-newserver.png


Si vous avez précédemment installé Tomcat 7, fournissez simplement le chemin du répertoire. Si vous ne l'avez pas, suivez les étapes suivantes:

  1. Cliquez sur Download and Install et choisissez un répertoire.
    Notez que le chemin d'installation ne peut contenir aucun caractère non-ASCII.
    Tutorial-downloadinstall.png
  2. Acceptez la licence et attendez.
    Eclipse affichera un message d'erreur avant que l'installation ne s'achève, ignorez le.
    Tutorial-installing-unknown.png
    Patientez et n'interrompez pas l'installation pour être certain qu'elle s'effectue correctement.
    Tutorial-installing-progress.png
    Eclipse va télécharger et installer Tomcat dans le dossier que vous avez spécifié.
  3. Lordque l'installation est finie, cliquez sur Finish


Vous devriez maintenant voir une nouvelle entrée dans Server runtime environments.

Tutorial-server-complete.png


Faites un clique droit sur hello.zul et sélectionnez Run As \ Run on Server pour faire tourner ce zul sur un serveur d'applications.

Tutorial-runonserver.png


Choisissez un Tomcat 7. Vous pouvez aussi cocher l'option Always use this server when running this project pour ne pas devoir choisir un serveur à chaque fois que vous lancerai l'application par la suite. Cliquez sur Finish et attendez que le serveur démarre.

Tutorial-choose-server.png


Une fois le serveur démarré, Eclipse va ouvrir un browser et vous connecter automatiquement à http://localhost:8080/tutorial/hello.zul . Si vous voyez l'image suivante, alors votre projet est prêt pour utiliser ZK.

Tutorial-hello.png

Vous pouvez revenir ici et suivre à nouveau ces étapes pour lancer votre application au cours de ce tutoriel

Importer et lancer l'Application exemple

Nous avons préparé un ficher zip projet Eclipse qui contient le code source complet, vous pouvez le télécharger et l'importer dans votre Eclipse sans avoir à démarrer tout de 0.

Pour utiliser l'application exemple, suivez les étapes suivantes:

  1. Téléchargez le fichier zip du projet.
  2. Dans Eclipse, sélectionnez File \ Import \ General \ Existing Projects into Workspace, choisissez Select archive file pour importer le zip de l'application comme projet dans Eclipse.
  3. Suivez ensuite les instructions de Run an Application pour lancer l'application.


Déclaration des classes du domaine

Ce qui suit est l'objet du domaine qui représente une voiture.

public class Car {
	private Integer id;
	private String model;
	private String make;
	private String preview;
	private String description;
	private Integer price;
	//omit getter and setter for brevity
}
  • Merci de vous référer à la section References pour voir le code complet. [3]

On définit ensuite une classe de service pour effectuer la logique business (chercher des voitures) tel que montré ci-dessous:

public interface CarService {

	/**
	 * Retrieve all cars in the catalog.
	 * @return all cars
	 */
	public List<Car> findAll();
	
	/**
	 * search cars according to keyword in  model and make.
	 * @param keyword for search
	 * @return list of car that match the keyword
	 */
	public List<Car> search(String keyword);
}

Dans cet exemple, nous avons défini une classe - CarServeImpl qui implémente l'interface ci-dessus. Par soucis de simplicité, elle utilise une liste objet statique comme modèle de données. Vous pouvez la réécrire de sorte qu'elle se connecte à une base de données dans une application réelle. Les détails de l'implémentation ne sont pas l'objet de cet article, merci de vous référer à la section References.[4]

Construire l'interface utilisateur

Le design de l'UI est un bon début pour construire une application vu qu'il vous aide à définir l'étendue de votre application. ZK fournit des centaines de composants UI prêts à l'emploi de sorte que les développeurs peuvent rapidement construire l'interface utilisateur de leur choix en combinant et en mélangeant ces composants sans avoir à les créer.

Dans ZK, vous pouvez utiliser ZK User Interface Markup Language (ZUML) [5], un langage formaté XML, pour décrire les UI. Suivant la convention ZK, les fichiers décrivant les UI avec ZUML utilisent comme suffixe .zul. Dans les fichiers zul, un composant peut être représenté comme un élément XML (tag) et vous pouvez configurer pour chaque composant son style, son comportement et sa fonction via les attributs XML de cet élément.[6]

Dans cet exemple, nous voulons d'abord concevoir une fenêtre avec un titre spécifique et un bord normal qui sera la fenêtre de notre application.


Extrait de search.zul

	<window title="Search" width="600px" border="normal">
		<!-- put child components inside a tag's body -->
	</window>

Vu que window et le composant 'englobant' principal, il est appelé root component. Window est un container souvent utilisé parce-que c'est un élément d'affichage de base d'une application de type bureau et qui peut en même temps contenir d'autres composants. Tous les autres composants inclus dans window sont appelés child components et doivent être placés dans le body de la fenêtre. Nous mettons un texte dans la barre de titre de window' grâce à l'attribut "title" et nous faisons en sorte que window s'affiche avec un bord normal grâce à l'attribut "border". Pour l'attribut "width", utilisez une syntaxe de type CSS comme "800px" ou "60%".


De base, l'UI de notre application est divisée en 3 zones à l'intérieur de window qui sont, de haut en bas, la fonction de recherche, la liste des voitures et les détails de la voiture.

Tutorial-ui-3areas.png


Zone de recherche: Les composants ZK sont comme des blocs à construire, vous pouvez combiner et mélanger les composants existants pour construire l'UI de votre choix. Pour permettre aux utilisateurs d'effectuer des recherches, il faut un texte incitant les utilisateurs à entrer une valeur, un endroit pour qu'ils tapent effectivement cette valeur-clé et un bouton qui va déclencher la recherche. Nus pouvons utiliser dans ce but les composants ZK suivants:

Extrait de search.zul

	 	<hbox align="center">
	 		Keyword:
	 		<textbox id="keywordBox" />
	 		<button id="searchButton" label="Search" image="/img/search.png" />
	 	</hbox>

hbox est un composant de layout qui organise ses enfants de manière horizontale et vous avez donc deviné que le h signifie horizontal. Vu que ces composants enfants ont des hauteurs différentes, nous mettons la valeur "center" à l'attribut "align" pour les aligner sur une ligne centrale. On spécifie aussi ici un attribut "id" pour certains composants de manière à pouvoir ensuite les contrôler grâce à cet id. Vous pouvez aussi facilement afficher une image sur le bouton en spécifiant le chemin de celle-ci dans l'attribut "image".


Zone de liste des voitures. ZK fournit quelques composants qui permettent d'afficher des collections de données comme listbox, grid, et tree. Dans cet exemple, nous allons utiliser une listbox pour afficher une liste de voitures sur 3 colonnes: Model, Make et Price. Nous mettons l'attribut "height" à une valeur qui limite le nombre de lignes à une hauteur spécifiée; vous pouvez bouger la scroll-bar pour visualiser les autre lignes. L'attribut "emptyMessage" est utilisé pour afficher un message lorsque la listbox ne contient aucun élément. La listbox est un composant container et vous pouver ajouter listhead pour définir une colonne. Le listitem est utilisé pour afficher les données et le nombre de listcell dans un listitem doit être égal au nombre de listheader. On utilise ici listcell avec un label statique pour montrer la structure d'un listitem et nous verrons comment créer dynamiquement un listitem qui respecte chaque objet de données dans le chapitre suivant.

Extrait de search.zul

	 	<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">
			<listhead>
				<listheader label="Model" />
				<listheader label="Make" />
				<listheader label="Price" width="20%"/>
			</listhead>
			<listitem>
				<listcell label="car model"></listcell>
				<listcell label="make"></listcell>
				<listcell>$<label value="price" /></listcell>
			</listitem>
		</listbox>


Zone de détail des voiture. Comme hbox, vbox est aussi un composant de layout qui arrange ses composants enfants en ordre vertical. En combinant ces 2 composants de layout, nous pouvons présenter davantage d'informations sur un écran. L'attribut "style" vous permet de customiser le style du composant avec une syntaxe CSS.

Extrait de search.zul

		<hbox style="margin-top:20px">
			<image id="previewImage" width="250px" />
			<vbox>
				<label id="modelLabel" />
				<label id="makeLabel" />
				<label id="priceLabel" />
				<label id="descriptionLabel"/>
			</vbox>
		</hbox>


Vous pouvez visualiser le fichier zul complet grâce au lien dans la section References. [7]


Handling UI Logic

The next step after building the UI is to make it respond to users. The approach we introduce here is to control UI component directly by yourself. This approach can be classified to Model-View-Controller (MVC) design pattern. [8] This pattern divides an application into three parts.

The Model consists of application data and business rules. CarService and other classes used by it represent this part in our example application.

The View means user interface. The zul page which contains ZK components represents this part. A user's interaction with components triggers events to be sent to controllers.

The Controller plays the role of a coordinator between View and Model. It receives events from View to update Model and retrieve data from Model to change View's presentation.


Tutorial-mvc.png
  1. When a user interacts with a component (e.g. click a button) on a ZUL, the user's action triggers an event.
  2. This event is sent to the controller and invokes corresponding event listener method.
  3. The event listener method usually executes business logic or accesses data, then manipulate ZK components.
  4. A component's state change in an event listener is reflected in its corresponding UI.


Declaring UI Controllers

In ZK, the controller is responsible for controlling ZK components and listening to events triggered by user interaction. We can create a such controller class by simply extending org.zkoss.zk.SelectorComposer :

package tutorial;

// omit import for brevity

public class SearchController extends SelectorComposer<Component> {

}


After a controller is created, we associate it with its corresponding UI component. Associating a controller with a component is just specifying full-qualified class name for the target component's apply attribute. The following code shows how to associate a controller with a window.

Extracted from searchMvc.zul

	<window title="Search" width="600px" border="normal"
	apply="tutorial.SearchController">
	<!-- omit other components for brevity -->
	</window>

See the complete zul in References.[9]


After associating the controller with the window component, the controller can listen to events sent from UI and retrieve components which allows us to implement application's function. Let's start from the search function: a user enters a keyword, clicks the "Search" button to trigger the search.

Steps to implement a function:

  1. Declare a method which listens to a component's event
  2. Control UI components to implement presentation and business logic in the listener method

Listening to User Action

When we associate a controller with a component, every event triggered by this component (and its child components) is sent to the controller. If there is a method which we assigned to listen to the triggered event, it will be invoked. As a user clicks "Search" button to trigger the search function, we have to listen to "Search" button's "onClick" event. We declare a method, search(), and specify it to be invoked when the "Search button" is clicked with the following annotation:

@Listen("[EVENT_NAME] = #[COMPONENT_ID]").

Such method serves as an event listener method.

The final code looks like:

public class SearchController extends SelectorComposer<Component> {

	@Listen("onClick = #searchButton")
	public void search(){

	}
}
  • Line 3: "searchButton" is the button component's id, and you can find it in previous zul. There are other syntax which can be specified in @Listen's parameter [10] to describe a component.
  • Line 4: It must be a public method.

Controlling UI Components

After establishing the relationship between an event and an event listener method, we can start to implement method's logic with components. But firstly we should retrieve the UI component's object by annotating @Wire on controller's member variables.

Steps to retrieve components:

  1. Declare a variable with target component type (e.g. Listbox, Label...)
  2. Name the variable as component's ID.
    Matching ID is the default rule to match a component for @Wire, and please refer to ZK Developer's Reference [11] to know other ways.
  3. Annotate the variable with @Wire.


Then ZK will "wire" a corresponding ZK component object to the variable we declared. After this has been done, we can then control and manipulate UI by accessing those annotated member variables.

public class SearchController extends SelectorComposer<Component> {

	@Wire
	private Textbox keywordBox;
	@Wire
	private Listbox carListbox;

	//other codes...
}
  • Line 5-6: In searchMvc.zul, there is a listbox whose id is carListbox. ZK will make the variable carListbox reference to the listbox object after components are created.


The search method performs a simple logic: call car service class to search with keyword and set result list to listbox. For a variable which references to a component, we can get component's attribute such as user's input with getter (getValue()) or change a component's status like making a label invisible with setter (setVisible(false)) to achieve some dynamic UI effect. Hence, we can easily get what keyword a user inputs by keywordBox.getValue() and change data item of listbox by carListbox.setModel() . The model of a component is the data the component holds and we can change the model to change the data rendering on the screen.

public class SearchController extends SelectorComposer<Component> {
	//omit codes to get components

	@Listen("onClick = #searchButton")
	public void search(){
		String keyword = keywordBox.getValue();
		List<Car> result = carService.search(keyword);
		carListbox.setModel(new ListModelList<Car>(result));
	}
}
  • Line 8: Notice that setModel() only accepts a ListModel object, so we can use org.zkoss.zul.ListModelList to wrap search result list. There are other ListModel objects for different collection types, please refer to References section. [12]

Displaying a Data Collection

We have successfully made clicking "Search" button to invoke its corresponding event listener, but we would still find that content of listbox doesn't show the search result correctly. That is because we haven't specified how to render data model on the listbox. Now, we will use a special tag, <template> [13], to control the rendering of each item. ZK will render template tag's content iteratively for each object in the data model.

Steps to use <template> :

  1. Use <template> to enclose components that we want to create iteratively.
  2. Set template's "name" attribute to "model". [14]
  3. Use implicit variable, each, to assign domain object's properties to component's attributes.

Extracted from searchMvc.zul

		<listbox id="carListbox" height="160px" emptyMessage="No car found in the result">
			<listhead>
				<listheader label="Model" />
				<listheader label="Make" />
				<listheader label="Price" width="20%"/>
			</listhead>
			<template name="model">
				<listitem>
					<listcell label="${each.model}"></listcell>
					<listcell label="${each.make}"></listcell>
					<listcell>$<label value="${each.price}" /></listcell>
				</listitem>
			</template>
		</listbox>
  • Line 7: The template tag should be put inside the listbox .
  • Line 8: The <listitem> in previous chapter's zul is for static data, we should replace it with current code.
  • Line 9: The "each" is a variable that references to a domain object in the model list which is Car in our example application. We can use it to access domain object's property with EL, e.g. ${each.price}.

Implementing the View Details Functionality

Previous sections describe the basic steps to implement a function with ZK. Let's recap them by implementing "view details" function. We declare a method to listen to "onSelect" event of listbox with @Listen, then use @Wire to get components like previewImage, modelLabel, priceLabel, and descriptionLabel and assign value to them with setter.

public class SearchController extends SelectorComposer<Component> {

	@Wire
	private Listbox carListbox;
	@Wire
	private Label modelLabel;
	@Wire
	private Label makeLabel;
	@Wire
	private Label priceLabel;
	@Wire
	private Label descriptionLabel;
	@Wire
	private Image previewImage;

	@Listen("onSelect = #carListbox")
	public void showDetail(){
		Car selected = carListbox.getSelectedItem().getValue();
		previewImage.setSrc(selected.getPreview());
		modelLabel.setValue(selected.getModel());
		makeLabel.setValue(selected.getMake());
		priceLabel.setValue(selected.getPrice().toString());
		descriptionLabel.setValue(selected.getDescription());
	}
	//omit other codes for brevity
}


For complete source code, please refer to References section [15]

References