ZK 5.0 and jQuery part 2 fr

{{Template:Smalltalk_Author_Translator|
|author=Timothy Clare, Technology Evangelist, Potix Corporation
|translator=Arnaud Dewulf, Belgium
|date=July 13, 2009
|version=ZK 5.0 preview release
}}


= Introduction =


ZK5 utilise jQuery coté client, offrant un large panel de possibilités. Un des plus grands bénéfices à utiliser jQuery est qu'il existe un nombre important d'excellents plug-ins. Dans ce document, nous allons montrer l'implémentation d'un effet coté client en utilisant le plug-in [http://jqueryui.com jQuery UI Tools] qui propose des animations, des abstractions pour des interactions bas-niveau et bien plus encore. 

Ce doucment est le second d'une série de 2 documents. La première partie est disponible [[Small_Talks/2009/July/ZK_5.0_and_jQuery_fr | ici]] et propose l'implémentation d'un effet plus simple.


== Description du fichier ZUL ==

Le fichier ZUL est composé de 3 parties. 
Nous trouvons premièrement le script coté client, qui se trouve dans les balises <script> et la directive du script (<?script src=... ?>).

<source lang="javascript">
        <!-- CLIENT SIDE FUNCTIONALITY!	-->
	<?script src="jquery-ui-1.7.2.custom.min.js"?>
	<script>
		<![CDATA[
			function updateWithExplosion (value, fromServer, updateColor) {
				
				if(this.desktop) {
					jq(this).effect("explode", 
							{}, 
							500);
				}
				
				this.$setValue(value, fromServer);
				
				if (this.desktop) {	
					if (updateColor) {
						jq(this.getCaveNode().parentNode.parentNode).css({background: ((value<0) ? 'red':'green')});
						this.setStyle('color: #FFFFFF');
					}
					jq(this).show("drop", {direction : "up"}, 1000);
				}
			}
			
			
			function updateWithColorAndExplosion (value, fromServer) {
				updateWithExplosion.call(this, value, fromServer, true);
			}
		]]>
	</script></source>

Ensuite, le code coté serveur se trouve dans les balises <zscript>. Attention que celles-ci peuvent être facilement confondus avec les balises <script>.

<source lang="java">
<!-- SERVER SIDE FUNCTIONALITY! -->
	<zscript>
		<![CDATA[
			public void updateStocks() {
				Object[] values = getStockValues();
				Label stockPrice = stockGrid.getFellow(values[0]);
				Label stockDifference = stockGrid.getFellow(values[1]);

				int newValue = ((Number)values[2]).intValue();
				int difference = newValue - Integer.parseInt(stockPrice.getValue());				

				stockPrice.setValue(Long.toString(newValue));
				stockDifference.setValue(Long.toString(difference));
			}
			
			public Object[] getStockValues() {
				int randomControl = (int)Math.ceil(Math.random() * 3);
				return new Object[] {"stockPrice" + randomControl,
					"stockDifference" + randomControl,
					(int)Math.ceil((Math.random() * 10) + 95)};
			}
		]]>
	</zscript></source>


Enfin, nous trouvons la balise ZUML qui décrit le GUI.

<source lang="xml">
<!-- ZUL MARKUP (UI IMPLEMENTATION!) -->
	<timer id="updateTimer" delay="3000" repeats="true" onTimer="updateStocks()" />
	
	<grid id="stockGrid" fixedLayout="true">
		<columns>
			<column label="Stock name" />
			<column label="Stock value" />
			<column label="Stock difference" />
		</columns>
		<rows>
			<row>
				<label id="stockName1" value="Ultra Corp: " />
				<label id="stockPrice1" value="100" w:setValue="updateWithExplosion"/>
				<label id="stockDifference1" value="0"  w:setValue="updateWithColorAndExplosion"/>
			</row>
			<row>
				<label id="stockName2" value="Amazing Corp: " />
				<label id="stockPrice2" value="100" w:setValue="updateWithExplosion"/>
				<label id="stockDifference2" value="0" w:setValue="updateWithColorAndExplosion"/>
			</row>
			<row>
				<label id="stockName3" value="Great Corp: " />
				<label id="stockPrice3" value="100" w:setValue="updateWithExplosion"/>
				<label id="stockDifference3" value="0" w:setValue="updateWithColorAndExplosion"/>
			</row>
		</rows>
	</grid></source>

= Le but de l'application =


Le but de cette application est de démontrer les fonctionnalités jQuery dans ZK 5 et à quoi cela peut servir. Dans cet exemple, nous illustrons comment surcharger la fonction setValue de certains composants chez le client. En faisant cela, nous pouvons ajouter des effets aux données lorsque ces dernières changent. Ces données peuvent être définies par le serveur ou par le client. Dans cet exemple, les données sont fournies par javascript au client.

= Démo =

<gflash width="750" height="200">JQuery_demo_stock.swf</gflash>

= Développer cet exemple =


Pour commencer, nous devons inclure jQuery UI dans la page, ce qui est fait grâce au composant script de ZK.

<source lang="xml">
<?script src="/scripts/tools.expose-1.0.3.js"?></source>

Nous pouvons dès lors utiliser les méthodes fournies par la librairie jQuery.

= La fonction setValue =


La fonction setValue est utilisée pour changer la valeur d'un Label. Si nous voulons appliquer un effet spécial à cette valeur lorsqu'elle change, nous devons surcharger la fonction setValue chez le client.

= Surcharger la fonction setValue chez le client =



== Utiliser un namespace coté client ==


Lorsque des fonctionnalités sont implémentées coté client, il est nécessaire de déclarer un namespace. En faisant cela, les évènements seront gérés du coté client et non du coté serveur. Sans ce namespace, ZK va penser que votre code est du code Java et qu'il devrait être exécuté du coté serveur.


== Définir un namespace ==


Définir un namespace est facile, il suffit d'ajouter le code suivant comme attribut de n'importe quelle balise ZK

<source lang="xml">
xmlns:w=http://www.zkoss.org/2005/zk/client</source>

Dans notre exemple, nous l'avons ajouté dans la balise ZK de sorte que le namespace soit disponible pour tous les composants.

<source lang="xml">
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"></source>


== Surcharger la fonction setValue ==


Dans cet exemple, nous utilisons des Labels pour afficher les informations. Par conséquent, nous devons surcharger la méthode setValue des labels. Pour le faire, nous déclarons un attribut setValue. Le code se trouve ci-après. Remarquez que l'attribut est précédé de w: qui est le nom de notre namespace.


<source lang="xml">
<label id="stockPrice1" value="100" w:setValue="updateWithExplosion"/>
</source>


=== Créer les fonctions de surcharge ===


Deux fonctions sont utilisées dans cet exemple: la première est la fonction updateWithExplosion et la seconde est la fonction updateWithColorAndExplosion. Pour surcharger setValue, nous devons écrire une fonction avec le squelette suivant:

<source lang="javascript">
function NAME (value, fromServer) {

        this.$setValue(value, fromServer);
				
	if (this.desktop) {	
		jq(this).WHATEVER_EFFECT
	}
}</source>


Les structures des 2 fonctions diffèrent par le fait qu'une des deux prends un argument en plus que l'autre, mais cela ne change en rien le mécanisme de surcharge. Par exemple, updateExplosion requiert un argument de plus. Quand cette méthode est utilisée pour surcharger la fonction setValue,  le paramètre “updateColor” restera indéfini.

<source lang="javascript">
function updateWithExplosion (value, fromServer, updateColor) {
				
	if(this.desktop) {
	
        	jq(this).effect("explode", 
				{}, 
				500);
	}
				
	this.$setValue(value, fromServer);
				
	if (this.desktop) {	
		if (updateColor) {
			jq(this.getCaveNode().parentNode.parentNode).css({background: ((value<0) ? 'red':'green')});
			this.setStyle('color: #FFFFFF');
		}
	
        	jq(this).show("drop", {direction : "up"}, 1000);
	}
}</source>

Le code ci-dessous montre que si le troisième paramètre passé est à true, alors la couleur de la cellule est changée. Ceci est fait grâce à la fonction updateWithColorAndExplosion:

<source lang="javascript">
function updateWithColorAndExplosion (value, fromServer) {
	updateWithExplosion.call(this, value, fromServer, true);
}</source>


Cette méthode est intéressante dans la mesure où elle utilise la méthode javascript call pour exécuter updateWithExplosion. Vous pouvez aussi remarquer que le premier paramètre du call est “ this.” “this” dépend  du champ d'application, dans ce cas-ci, “this” doit être préservé comme widget. Si ce call n'était pas effectué, le type de “this” dans la fonction updateWithExplosion deviendrait l'objet script.

= Mettre à jour les données =


Les données sont mises à jour par l'intérmédiare d'un composant timer et d'un code se trouvant coté serveur. Au chargement de la page, le timer va démarrer et, toutes les 3 secondes, la fonction updateStocks() sera appelée. Elle pourra alors mettre à jour les stocks et envoyer les nouvelles informations au client.

<source lang="xml">
<timer id="updateTimer" delay="3000" repeats="true" onTimer="updateStocks()" /></source>

<source lang="java">
public void updateStocks() {
	Object[] values = getStockValues();
	Label stockPrice = stockGrid.getFellow(values[0]);
	Label stockDifference = stockGrid.getFellow(values[1]);

	int newValue = ((Number)values[2]).intValue();
	int difference = newValue - Integer.parseInt(stockPrice.getValue());				

	stockPrice.setValue(Long.toString(newValue));
	stockDifference.setValue(Long.toString(difference));
}
			
public Object[] getStockValues() {
	int randomControl = (int)Math.ceil(Math.random() * 3);
	return new Object[] {"stockPrice" + randomControl,
					"stockDifference" + randomControl,
					(int)Math.ceil((Math.random() * 10) + 95)};
}</source>

Dans une application réelle, ces données seraient récupérées depuis une base de données et le timer serait remplacé par le mécanisme d'envoie des données du serveur. Merci de regarder [[Small Talks/2008/May/Server Push with a Stock Chart Example| ici]] pour plus de détails.

= Source =

Téléchargez le code source [https://sourceforge.net/projects/zkforge/files/Small%20Talks/zk5jquerydemo2.zip/download ici]

= See Also =
[[Small Talks/2009/July/ZK 5.0 and jQuery part 2|ZK 5.0 and jQuery part 2 (English)]]

<comment>http://docs.zkoss.org/wiki/ZK_5.0_and_jQuery_part_2_fr</comment>