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.

Voila la structure qui sera adoptée pour la création de notre mini widget HelloWorld :

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

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.

• config.php : ce script centralise les chemins d'inclusions et les paramètres globaux des widgets.
• 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.

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 :

<?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);
  }
}
 
?>

Chemin exact : templates/HelloWorld/default/world.gif

Cette image est une ressource 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

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.

<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>

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; ?>.

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;
}

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

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;
}

Chemin exact : templates/HelloWorld/default/i18n/fr_FR.php

Ceci est le fichier de traduction en français (de FRance) 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').

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

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.

Chemin exact : templates/HelloWorld/default/i18n/en_GB.php

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

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

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.

$obj = new HelloWorld();

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)

$params = array();
$params["Lang"] = 'en_GB';
$params["montexte"] = 'Exemple de traduction du titre en anglais';
$obj = new HelloWorld($params);

$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);

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 :

<?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
?>

Voila l'explication du code :

1. Chargement de la configuration du widget.
2. Déclaration de la classe du widget HelloWorld
3. Instanciation du widget sans aucun paramètre (paramètres du constructeur vides)
4. 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.
5. On exécute ensuite le widget (équivalent au putWidget que l'on verra un peu plus loin)
6. 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 :

class Root extends Pxxo_Widget {
...
  function index()
  {
    ...
    require_once 'HelloWorld.php';
    $o = new HelloWorld();
    $this->putWidget('CONTENT', $o);

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 :

<?php echo $CONTENT; ?>

Vous trouverez des informations sur la page décrivant les différents types d'intégrations possibles.

Le widget HelloWorld + la librairie Pxxo : helloworld.tar.gz

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