====== Tutoriel : le widget HelloWorld ======

Pxxo est un groupe de classes PHP (framework non intrusif) dont le but est la création de composants graphiques indépendants et inter-opérables. Un composant graphique (ou **widget**), est une micro application Web pouvant être facilement imbriquée dans une application ou même dans un autre composant graphique. Quelques exemples de composants: un calendrier, un menu, un formulaire de contact, un lecteur de fil RSS...

Ce tutoriel s'adresse aux développeurs désireux de comprendre comment programmer eux-mêmes des widgets pxxo.

Dans ce tutoriel, il sera expliqué comment créer un composant pxxo affichant la chaîne "hello world". Nous nous attarderons sur les détails d'implémentations suivants : 
  * création de la classe du widget
  * utilisation des ressources
  * gestion multi-langues

Ce tutoriel a également pour vocation de proposer quelques "bonnes manières" pour écrire des composants Pxxo.
















===== Structure =====

Voila la structure qui sera adoptée pour la création de notre mini widget ''HelloWorld'' :
<code>
helloworld _ 
            | index.php
            | classes _
            |          | HelloWorld.php
            | templates _
            |            | HelloWorld _
            |            |             | default _
            |            |             |          | index.php.html
            |            |             |          | style.php.css
            |            |             |          | world.gif
            |            |             |          | i18n _
            |            |             |          |       | fr_FR.php
            |            |             |          |       | en_GB.php
            |            |             | blue _
            |            |             |       | style.php.css
            | tmp
            | rsc
            | pear
</code>
Ce cadre peut être réutilisé pour vos futures applications full pxxo. Cependant, comme expliqué dans la dernière partie de ce tutoriel, les widgets peuvent être également utilisés dans des applications php ne respectant pas forcement ce cadre.

  * ''[[http://sourcesup.cru.fr/cgi/viewvc.cgi/trunk/apps/helloworld/config.php?root=pxxo&view=markup|config.php]]'' : ce script centralise les chemins d'inclusions et les paramètres globaux des widgets.
  * ''[[http://sourcesup.cru.fr/cgi/viewvc.cgi/trunk/apps/helloworld/index.php?root=pxxo&view=markup|index.php]]'' : c'est le lanceur qui va instancier et afficher le widget HelloWorld dans une page html.
  * __''classes''__ : répertoire qui contient le fichier de la classe de notre widget
  * __''templates''__ : répertoire qui contient les ressources notre widget : modèles, images, styles et traductions
  * __''tmp''__ : répertoire privé (ne devant pas être visible par le navigateur) qui est utilisé par pxxo pour mettre en cache les données du widget. Le serveur web doit donc être autorisé à écrire dedans (''chmod a+w tmp''). 
  * __''rsc''__ : répertoire public (visible par le navigateur) qui est utilisé par pxxo pour mettre à disposition du navigateur les ressources (images, css...) du widget. Le serveur web doit donc être autorisé à écrire dedans (''chmod a+w rsc''). 
  * __''pear''__ : répertoire contenant pear et en particulier la librairie Pxxo (ceci permet de faire  fonctionner son widget sans avoir à installer Pxxo dans le dépôt PEAR de sa machine)


Nous allons maintenant expliquer la structure de notre widget HelloWorld fichiers par fichiers.




==== HelloWorld.php ====

Ce fichier contient la classe **''HelloWorld''** qui hérite de **''Pxxo_Widgets''**. Cette classe est constituée des éléments suivants :
  * __La méthode **''index()''**__ : la méthode ''index()'' est appelée automatiquement par pxxo lors de l'exécution de l'objet. Cette méthode se charge de réaliser une action de l'objet, exemples : connexion base de donnée, authentification, traitement divers ... Elle est également chargée de récupérer toutes les informations qui seront destinées à être affiché, ex: récupérer l'adresse postale et le téléphone d'une personne dans la base de donnée pour pouvoir afficher la carte de visite de cette personne en html.
  * __Les attributs de la classe__ : les attributs de la classe ''HelloWorld'' sont des paramètres que l'on récupère sous forme de simple variable dans les templates HTML et CSS, exemple: l'attribut **''var $montexte''** pourra être affiché et transformé dans les templates en utilisant la variable **''$montexte''**.\\ Attention : Les attributs préfixé par un souligné (_) sont considérés comme des attributs privés, ils ne sont seront donc pas utilisable dans les templates.
  * __Les ressources du widget__ : des ressources sont associées à notre widget ''HelloWorld''. Ces ressources sont placées dans le répertoire **''templates/HelloWorld/''**. Nous y trouvons : des templates HTML (modèles), des feuilles de styles CSS et des fichiers de traduction (i18n).

Le code source est le suivant :

<code php>
<?php
// vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4 encoding=utf-8 fdm=marker : 
// +--------------------------------------------------------------------------+
// | Pxxo_Widget - Bibliothèque de composants graphiques                      |
// +--------------------------------------------------------------------------+
// | Copyright (C) 2004 Nicolas Thouvenin                                     |
// +--------------------------------------------------------------------------+
// | This library is free software; you can redistribute it and/or            |
// | modify it under the terms of the GNU General Public License              |
// | as published by the Free Software Foundation; either  version 2          |
// | of the License, or (at your option) any later version.                   |
// |                                                                          |
// | This program is distributed in the hope that it will be useful,          |
// | but WITHOUT ANY WARRANTY; without even the implied warranty of           |
// | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU         |
// | General Public License for more details.                                 |
// |                                                                          |
// | You should have received a copy of the GNU General Public License        |
// | along with this library; if not, write to the Free Software              |
// | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA  |
// +--------------------------------------------------------------------------+
//

/**
 * @package Pxxo_Widget
 * @version $Id$
 */

/**
 * Dépendances
 */
require_once 'Pxxo/Widget.php';

/**
 * HelloWorld est un widget squelette qui peut être utilisé comme base pour la création d'un nouveau composant.
 * Ce composant illustre:
 *   - la notion de themes (couleurs du texte)
 *   - la notion de resources (insertion d'une image)
 *   - la gestion des langues (texte en anglais et français)
 *   - la notion de paramètre utilisateur
 *
 * @package Pxxo_Widget
 * @author Stéphane Gully <stephane.gully@gmail.com>
 * @license http://opensource.org/licenses/lgpl-license.php LGPL
 * @copyright 2006, Nicolas Thouvenin
 */
class HelloWorld extends Pxxo_Widget
{
  /**
   * Ceci est un paramètre utilisateur bidon
   * qui sera accessible dans notre template 'index.php.html'
   * @access	public
   */
  var $montexte = 'Param&egrave;tre par d&eacute;faut';

  /**
   * Ce tableau contient la liste des parametres utilisateurs autorisés
   * Il permettra au constructeur de Pxxo_Widget (le parent) d'enregistrer
   * automatiquement les paramètres utilisateurs dans les attributs de l'instance courante.
   * ex: dans notre cas, si $params['montexte'] est indiqué alors '$this->montexte' en prendra sa valeur
   * @private
   */
  var $_params = array('montexte');

  /**
   * Constructeur
   * Les paramètres utilisateurs sont passés au constructeur de Pxxo_Widget (le parent) où ils 
   * seront automatiquement assignés au attribut de l'instance de l'objet courant
   */
  function __construct($params = array())
  {
    parent::__construct($params, __FILE__);
  }
  
  /**
   * Action index
   * C'est le code qui sera executé par défaut par notre composant.
   * - opération bidon sur le paramètre utilisateur : passage de la chaîne en minuscule
   * - le template utilisé sera 'index.php.html' (tiré du nom de la méthode)
   * - l'image world.gif est ajoutée automatiquement par pxxo car elle se trouve dans le répertoire du thème
   * - la feuille de style style.php.css est ajoutée automatiquement par pxxo
   *   car elle se trouve également dans le répertoire du thème
   */
  function index() 
  {
    // operation bidon : passage en minuscule du parametre utilisateur 'montexte'
    $this->montexte = strtolower($this->montexte);
  }
}

?>
</code>




==== world.gif ====

__Chemin exact :__ ''templates/HelloWorld/default/world.gif''

Cette image est une ressources statique, elle ne dépend d'aucune autre ressource. Elle sera copiée automatiquement par pxxo dans le répertoire public ''rsc/'' lors de l'exécution du widget. Pxxo connait son emplacement et sait que l'on désire l'utiliser dans notre widget car le fichier se trouve dans le même répertoire que le fichier dans lequel est utilisé (index.php.html).
Son url sera alors disponible dans la variable **$world_gif** (le nom est déduit du nom du fichier de l'image) depuis le template **''index.php.html''**

{{:tutorials:helloworld:world.gif|:pxxo:world.gif}}









==== index.php.html ====

__Chemin exact :__ ''templates/HelloWorld/default/index.php.html''

Ceci est le template du code html qui sera généré par notre widget. Ce template contient le code html que notre composant va afficher ainsi que des balises php (''<?php ... ?>'') permettent d'afficher les attributs (transformés en variable) de notre widget au milieu du html.

Nous y retrouvons les éléments suivants :
  * **''$montexte''** provenant de l'attribut de notre widget
  * **''$world_gif''** provenant de notre image world.gif présente dans le même répertoire que index.php.html
  * **''$ClassID''** qui est une variable calculée automatiquement par pxxo contenant l'identifiant unique de notre widget (si deux instances sont présentes dans la même page alors cet ID permet de les différencier)
  * **''$this->Self->_('Hello World')''** est une fonction retournant la traduction dans la langue demandée de la chaîne passée en paramètre.

<code html>
<div id="<?php echo $ClassID; ?>">
  <!-- la variable $world_gif est crée automatiquement par pxxo
       car l'image 'world.gif' existe dans le répertoire courant -->
  <img src="<?php echo $world_gif ; ?>" alt="Mon image" />
  <h1><?php echo $this->Self->_('Hello World'); ?></h1>
  <p><?php echo $montexte; ?></p>
</div>
</code>




==== style.php.css (du thème 'default') ====

__Chemin exact :__ ''templates/HelloWorld/default/style.php.css''

Ceci est le //template// de la feuille de style (CSS) du thème par défaut de notre widget. Un thème correspond à un répertoire (ici ''default'') contenant les ressources du widget.\\ La feuille de style utilise **''$ClassID''** qui permet d'identifier l'instance de notre composant. En effet, si deux instances du widget utilisant deux thèmes différents sont affichées sur la même page, les règles CSS de ces deux instances n'entreront pas en conflit grâce à cet identifiant unique : ''<?php echo $ClassID; ?>''.

<code css>
div#<?php echo $ClassID; ?> * { margin:0; padding: 0; }

div#<?php echo $ClassID; ?> {
  padding: 10px;
  min-height: 120px;
  width: 500px;
  border: 1px solid #555;
  background-color: #EEE;
  color: #000;
}

div#<?php echo $ClassID; ?> img {
  float: left;
  padding: 10px;
  margin-right: 10px;
  height: 100px;
  border-right: 1px solid #555;
}
</code>




==== style.php.css (du thème 'blue') ====

__Chemin exact :__ ''templates/HelloWorld/blue/style.php.css''

Ceci est le template de la feuille de style (css) du thème alternatif ''blue'' de notre widget.

Pour créer le thème blue, procédez comme ceci :
  * copiez le fichier ''default/style.php.css'' vers ''blue/style.php.css''
  * personnalisez lu fichier ''blue/style.php.css'' : changement de la couleur de fond (''background-color:#EEF'') et de la couleur du texte (''color:#004'').

Pour activer le thème blue lors de l'instanciation du widget, passez lui le paramètre  **''$params['theme']='blue';''**. Pxxo se chargera automatiquement d'utiliser le fichier ''blue/style.php.css'' plutot que ''default/style.php.css''

<code css>
div#<?php echo $ClassID; ?> * { margin:0; padding: 0; }

div#<?php echo $ClassID; ?> {
  margin: auto;
  padding: 10px;
  min-height: 120px;
  width: 500px;
  border: 1px solid #6495ED;
  background-color: #D0E3FA;
  color: #3e60af;
}

div#<?php echo $ClassID; ?> img {
  float: left;
  padding: 10px;
  margin-right: 10px;
  height: 100px;
  border-right: 1px solid #6495ED;
}
</code>



==== fr_FR.php ====

__Chemin exact :__ ''templates/HelloWorld/default/i18n/fr_FR.php''

Ceci est le fichier de traduction en **fr**ançais (de **FR**ance) des labels du widget. Pour afficher ces labels, pxxo met à disposition la méthode **''$this->Self->_(...)''** qui prend en paramètre l'identifiant du label (dans notre cas 'Hello World'). 

<code php>
<?php
$this->TranslateData['Hello World'] = 'Bonjour le monde';
?>
</code>

Passez le paramètre **''$params['lang'] = 'fr_FR';''** lors de l'instanciation de votre widget. Cela demandera à votre widget d'utiliser ce fichier de traduction.

==== en_GB.php ====

__Chemin exact :__ ''templates/HelloWorld/default/i18n/en_GB.php''

Ceci est le fichier de traduction en anglais (de Grande Bretagne) des labels du widget.

<code php>
<?php
$this->TranslateData['Hello World'] = 'Hello World';
?>
</code>

Passez le paramètre **''$params['lang'] = 'en_GB';''** lors de l'instanciation de votre widget. Cela demandera à votre widget d'utiliser ce fichier de traduction.

===== Résultats : copies d'écrans =====



==== Avec les paramètres par défaut ====
<code php>
$obj = new HelloWorld();
</code>
{{:tutorials:helloworld:helloworld1.jpg|hello world (paramètres par défaut)}}

__Remarque :__ le widget sera alors traduit en utilisant la langue trouvée dans le navigateur du client (la copie d'écran a été faite avec un navigateur web français)


==== En spécifiant la langue en_GB ====
<code php>
$params = array();
$params["lang"] = 'en_GB';
$params["montexte"] = 'Exemple de traduction du titre en anglais';
$obj = new HelloWorld($params);
</code>
{{:tutorials:helloworld:helloworld2.jpg|hello world (avec une traduction en anglais)}}






==== En spécifiant le thème blue ====
<code php>
$params = array();
$params['lang']  = 'fr_FR';
$params['theme'] = 'blue';
$params['montexte'] = 'Exemple de traduction du titre en français + Utilisation du thème "blue"';
$obj = new HelloWorld($params);
</code>
{{:tutorials:helloworld:helloworld3.jpg|hello world (avec un thème blue)}}







===== Intégration du widget dans une application pxxo =====

Dans ce premier cas, je suppose que votre application respecte le cadre proposé ci-dessus (full pxxo). 

Votre widget est le seul présent dans l'application, il sera donc un widget racine. Dans le fichier index.php, ajoutez les lignes suivantes :
<code php>
<?php
require_once 'config.php';
require_once 'HelloWorld.php';
$o = new HelloWorld();
$o->addDecorator('Pxxo_Widget_Decorator_Core');                     // Ajoute un corps HTML autour de notre widget
$o->main();                                                         // Exécution de la classe principale
$o->dump();                                                         // Affichage
?>
</code>
Voila l'explication du code :
  - Chargement de la configuration du widget.
  - Déclaration de la classe du widget HelloWorld
  - Instanciation du widget sans aucun paramètres (paramètres du constructeur vides)
  - On décore ensuite le HelloWorld avec Core. Cette opération a le rôle de lui rajouter un corps HTML pour qu'il s'affiche correctement dans une page HTML valide.
  - On exécute ensuite le widget (équivalent au putWidget que l'on verra un peu plus loin)
  - On affiche ensuite le HTML du widget


Dans la pratique, ils sera très rare d'avoir à instancier un widget en tant que racine. Pxxo permet de construire des widgets hiérarchiques : c'est à dire qu'un widget peut-être fils d'un autre. Supposons que nous avons créé un widget ''Root'' et que nous souhaitons lui ajouter en tant que fils notre widget HelloWorld, voila comment il faudra procéder :
<code php>
class Root extends Pxxo_Widget {
...
  function index()
  {
    ...
    require_once 'HelloWorld.php';
    $o = new HelloWorld();
    $this->putWidget('CONTENT', $o);
</code>
Ici nous utilisons la méthode **''putWidget''** qui aura pour rôle d'exécuter le widget (équivalent de la méthode main) puis de mettre à disposition le HTML du widget dans la variable **''$CONTENT''**. On peut alors  afficher le widget là où nous le souhaitons dans le template de notre widget ''Root'' en utilisant ce code : <code php><?php echo $CONTENT; ?></code>




===== Intégration du widget dans une application php hétérogène =====

Vous trouverez des informations sur la page décrivant les [[:fr:integrations#dans_une_application_non_pxxo|différents types d'intégrations possibles]].


===== Télécharger la mini application du widget HelloWorld =====

Le widget ''HelloWorld'' + la librairie ''Pxxo'' : {{tutorials:helloworld:helloworld.tar.gz|helloworld.tar.gz}}

__Attention__ à ne pas oublier de donner les droits aux répertoires **''rsc''** et **''tmp''** avant d'exécuter votre widget HelloWorld.