====== Pxxo_Widgets_Decorator_Ajax ======

Ce widget est particulier, il a pour rôle d'offrir un "univers AJAX" à un autre widget. Il permet de donner les outils AJAX à un autre widget. Le widget ainsi "ajaxisé" possède alors les outils nécessaires pour se mettre à jour par des appels AJAX (sans recharger la page). Il permet également avec peu d'efforts de conserver l'accessibilité de son widget, c'est à dire que le widget sera  utilisable sans avoir javascript activé dans son navigateur.

Par ailleurs, le widget se présente comme un décorateur, pour savoir comment l'utiliser (je vous rassure, c'est très simple) il faut se référer à la [[:fr:doc:pxxo_widgets_decorator|documentation des décorateurs]].

  * [[http://demo.pxxo.net/widgets/demos/Game_MineSweeper/|Exemple d'utilisation en ligne sur le jeu du démineur]]
  * [[http://demo.pxxo.net/widgets/demos/Quiz/|Exemple d'utilisation en ligne sur le widget Quiz]]
  * [[fr:install|Installer]]

===== Paramètres =====

Aucuns

===== API =====

J'explique ici ce que doit respecter le widget que l'on souhaite "ajaxifier". Cela consiste en deux choses : respecter une structure HTML et appeler la fonction javascript pxxo_ajax_update(...) aux bons endroits.



==== Code HTML du template ====

Il est important de placer tout le code HTML de votre widget dans un div ayant comme id le ''ClassID'' de l'instance de votre widget.
Tous les templates HTML destinés à utiliser AJAX doivent donc se structurer de cette manière :
<code php>
<div id="<?php echo $ClassID; ?>">
Le contenu de votre widget. à compléter...
</div>
</code>












==== Fonction javascript : pxxo_ajax_update ====

Le secret réside dans l'utilisation de la fonction javascript ''pxxo_ajax_update(...)''. Cette fonction accepte les paramètres suivants :
  * 1er paramètre : le ClassID du widget à mettre à jour (chaîne de caractère)
  * 2nd paramètre : la méthode du widget à appeler (par défaut c'est 'defaut')
  * 3ème paramètre : les paramètres GET supplémentaires éventuels à passer au widget (facultatif)

Une fois appelée, elle mettra à jour le contenu du widget avec le html généré par l'appel de la méthode passée en paramètre. Exemple : pour le cas du lien "Recommencer" du démineur, sur l'évènement ''onclick'' la méthode "restart" du widget est appelée et elle aura pour effet de réinitialiser toute la grille à zéro. Cette fonction prendra également le soin de charger les éventuels nouveaux styles (putStyle) associés à cette méthode ainsi que les éventuels nouveaux scripts (putScript).

Pour que votre site garde la compatibilité pour les navigateurs non javascript (question d'accessibilité), il vous suffit d'écrire le lien en dur dans l'attribut href de votre ancre et de mettre l'équivalent dans l'attribut onclick en utilisant ''pxxo_ajax_update''. Voila un exemple théorique :
<code php>
<a href="<?php echo $ClassID; ?>=mamethode&amp;monextra=mavaleur"
onclick="pxxo_ajax_update('<?php echo $ClassID; ?>','mamethode','monextra=mavaleur'); return false;">
Mon lien chargé d appeler la méthode "mamethode" en donnant 
en paramètre GET la clé "monextra" associé à la valeur "mavaleur"
</a>
</code>

Remarquez l'utilisation du "return false" à la fin du onclick qui permet d'éviter de recharger la page une fois que l'appel AJAX est lancé.


Astuce pour "ajaxiser" des formulaires html. Il faut rajouter l'attribut onsubmit dans votre balise <form> comme ceci :

<code>

onsubmit="pxxo_ajax_update('<?php echo $ClassID; ?>','submit',Form.serialize(this));return false;" 

</code>

===== Exemples =====

Comment instancier le widget Pxxo_Widgets_Game_MineSweeper sans lui donner les outils ajax (méthode classique) :
<code php>
require_once 'Pxxo/Widgets/Game/MineSweeper.php';
$params = array();
$params['width'] = 20;
$params['height'] = 20;
$params['nb_landmine'] = 15;
$o =& Pxxo_Widgets_Game_MineSweeper($params);
</code>

Maintenant voila comment l'instancier de la même façon mais en lui donnant la possibilité de faire des appels ajax. Cela consiste à le décorer avec le widget AJAX :
<code php>
require_once 'Pxxo/Widgets/Game/MineSweeper.php';
$params = array();
$params['width'] = 20;
$params['height'] = 20;
$params['nb_landmine'] = 15;
$o =& Pxxo_Widgets_Game_MineSweeper($params);
$o->addDecorator('Pxxo_Widgets_Decorator_Ajax');
</code>

Le code doit bien sur être écrit en respectant quelques règles. Pour lancer des mise à jour ajax du widget tout en gardant la compatibilité pour les navigateur sans javascript :
  - Ici un clic sur le lien recharge le widget en changeant son étant (sans ajax) : <code php>
<a href="?<?php echo $ClassID; ?>=restart">
<?php echo _po('Restart'); ?>
</a>
</code>
  - La même action avec l'extension ajax : <code php>
<a href="?<?php echo $ClassID; ?>=restart"
onclick="pxxo_ajax_update('<?php echo $ClassID; ?>','restart');return false;">
<?php echo _po('Restart'); ?>
</a>
</code>