Widgets

Un article de OviWiki.


Cette librairie facilite la création des interfaces en proposant des objets associés à chaque élément connu d'une page Web : champ de formulaire, tableau, lien avec puce, popup calendrier de sélection d'un jour...

Le chemin complet de la fonctionnalité
Widgets
Documentation du parent
Pas de parent
Module
widgets
version du module
0.1.9


Sommaire

getDescription

Méthode commune à toutes les librairies pour obtenir la description de l'objet partagé.

$instance = bab_functionality::get('Widgets');

$description = $instance->getDescription();

Initialisation

Fichier addonini.php

Pour accéder aux widgets dans un module d'Ovidentia, il est nécessaire d'installer la librairie Widgets et le module jQuery.

De manière a éviter tout problème ces pré-requis devront être signalés dans le fichier addonini.php du module en y ajoutant quelques lignes :

;<?php/*
 
[general]
name="my_addon"
.
.
.
 
[addons]
widgets="0.2.0"
 
[functionalities]
jquery="Available"
 
*/?>

Utilisation de la librairie

Pour utiliser la librairie dans un code PHP, il est nécessaire d'utiliser la fonction bab_functionality(). Il est conseillé d'inclure les styles utiles à quelques widgets :

$W = bab_functionality::get('Widgets');
$W->includeCss();

Les pages

La page est le point de départ d'une interface. C'est elle qui contient tous les éléments.

On définit une page grâce à l'objet Widget_BabPage.

La page créée est insérée dans le corps du site Ovidentia : le bandeau et les sections du site apparaîtront autour de la page.

$page = $W->BabPage();

Il est possible de définir le positionnement des éléments à l'intérieur de chaque élément. Ici, on définit le positionnement pour la page en cours :

  1. La méthode VBoxLayout() définit une mise en page verticale.
  2. La méthode HBoxLayout() définit une mise en page horizontale.
  3. La méthode FlowLayout() définit une mise en page horizontale en 'écoulement' : les éléments reviennent à la ligne automatiquement.
$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());

Pour travailler avec des applications en pleine page ou avec des popups, vous pouvez désactiver le mode intégré avec la méthode setEmbedded(). Le bandeau et les sections du site n'apparaîtront pas :

$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$page->setEmbedded(false);

Pour afficher le contenu de la page, on utilise la méthode displayHtml() :

$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$bonjourLabel = $W->Label('Bonjour');
$page->addItem($bonjourLabel);
 
$page->displayHtml();

Définir un titre de page :

$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$page->setTitle('Configuration');
 
$page->displayHtml();

Ajouter un message d'erreurs à la page :

$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
 $page->addError("Vous n'avez pas les droits d'accès");
 
$page->displayHtml();

Insérer des éléments

On ajoute des éléments via la méthode addItem() sur un élément conteneur (objet Widget_BabPage par exemple). Dans l'exemple ci-dessous, on ajoute un texte dans notre page.

$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$bonjourLabel = $W->Label('Bonjour');
$page->addItem($bonjourLabel);
 
$page->displayHtml();

Navigation horizontale avec les onglets

La méthode addItemMenu() sur l'objet Widget_BabPage permet de définir un onglet. La méthode setCurrentItemMenu() permet de définir l'onglet courant.

Dans cet exemple, on affiche 2 onglets : configuration et droits. Droits est l'onglet en cours.

$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$addon = bab_getAddonInfosInstance('monmodule');
$page->addItemMenu('configuration', 'Configuration', $addon->getUrl().'user&idx=config');
$page->addItemMenu('droits', 'Droits', $addon->getUrl().'user&idx=droits');
$page->setCurrentItemMenu('droits');
 
$page->displayHtml();

Les textes

Les textes sont gérés par les objets Widget_Label et Widget_RichText.

Widget_Label permet d’ajouter un élément texte simple. Si le contenu du texte contient un code javascript, il ne sera pas interprété. Une balise HTML s’affichera à l’écran et ne sera pas interprétée.

$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$texte = $W->Label('Qui vivra verra.');
$page->addItem($texte);
 
$page->displayHtml();

Widget_RichText permet d’ajouter un élément texte complexe (texte mis en forme comme du HTML). Par défaut le fonctionnement est le même l’objet Widget_Label concernant l’affichage du texte. Cependant il possible d’utiliser la méthode setRenderingOptions() pour indiquer le format d’affichage du texte :

  • BAB_HTML_ALL : valeur par défaut : combinaison de toutes les options suivantes
  • BAB_HTML_ENTITIES : les caractères spéciaux seront convertis en caractères HTML
  • BAB_HTML_AUTO : des balises paragraphes seront ajoutées pour remplacer les retours à la ligne dans le texte
  • BAB_HTML_P : des balises paragraphes seront ajoutées pour remplacer les doubles retours à la ligne
  • BAB_HTML_BR : des balises BR seront ajoutées pour remplacer les retours à la ligne
  • BAB_HTML_LINKS : les URL et les e-mails seront remplacés par des liens
  • BAB_HTML_JS : les caractères \ , ' et " seront protégés pour un code javascript, ce format n’est inclut dans BAB_HTML_ALL
$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$texte = $W->RichText('<b>Qui vivra verra.</b>');
$texte->setRenderingOptions(BAB_HTML_AUTO);
$page->addItem($texte);
 
$page->displayHtml();

Code Html libre

Vous pouvez insérer du code Html quelconque via l'objet Widget_Html :

$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$html = $W->Html('<ul>
                    <li>Choix 1</li>
                    <li>Choix 2</li>
                  </ul>');
$page->addItem($html);
$page->displayHtml();

Les formulaires

La création d'un formulaire utilise essentiellement les objets Widget_Form et Widget_InputWidget.

Widget_Form permet de définir un formulaire, la cible (attribut action d'une balise form) est automatiquement pré-renseignée au point d'entrée d'Ovidentia (index.php). Pour configurer une cible plus précise, utilisez la méthode setHiddenValue() comme dans l'exemple ci-dessous.

Par défaut, la méthode utilisée pour l'envoi des données est POST. Si vous désirez une méthode GET, appelez la méthode setReadOnly() :

$form = $W->Form();
$form->setReadOnly();
 
$form->setLayout($W->VBoxLayout());
 
$form->setHiddenValue('tg', $GLOBALS['babAddonTarget'].'/admin');
$form->setHiddenValue('idx', 'configurationsave');

Les champs :

Les champs des formulaires sont des objets Widget_InputWidget. Liste des champs utiles :

  • Checkbox : case à cocher
  • DatePicker : sélection d'une date avec popup de calendrier
  • GroupPicker : sélection d'un groupe d'utilisateurs
  • LineEdit : case de saisie
  • SimpleHtmlEdit : case de saisie avec mise en forme (éditeur wysiwyg simplifié)
  • TextEdit : case de saisie multi-lignes
  • TimePicker : sélection d'une heure
  • Uploader : champ fichier

Après la création d'un champ, il est essentiel de définir son nom (attribut name d'une balise input) par la méthode setName(). Une valeur d'initialisation peut être renseignée via la méthode setValue().

$champidentifiant = $W->LineEdit()->setName('identifiant')->setValue('Votre identifiant');

Les boutons :

L'objte Widget_SubmitButton permet de définir un bouton de soumission :

$form->addItem($W->SubmitButton()->setLabel('Enregistrer'));

Exemple avec l'affichage d'un formulaire contenant 2 cases de saisies Identifiant et Mot de passe :

$W = bab_functionality::get('Widgets');
$W->includeCss();
$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$form = $W->Form();
$form->setLayout($W->VBoxLayout());
$form->setHiddenValue('tg', $GLOBALS['babAddonTarget'].'/admin');
$form->setHiddenValue('idx', 'configurationsave');
 
$form->addItem($W->LineEdit()->setName('identifiant')->setValue('Votre identifiant'));
$form->addItem($W->LineEdit()->setName('passe')->setValue('Votre mot de passe'));
 
$page->addItem($form);
$page->displayHtml();

Exemple de création d'une liste déroulante sélectionnée sur le 3ème choix :

$select = $W->Select()->setName('notation');
$select->addOption(1, 'mauvais');
$select->addOption(2, 'bon');
$select->addOption(3, 'parfait');
$select->setValue(3);

La réception des données saisies :

La réception des données saisies dans un formulaire dépend des conteneurs utilisés avec le formulaire. Explication :

Dans notre exemple, l'objet Widget_Form n'a pas de nom et ne contient aucun conteneur (un conteneur est un objet Widget qui contient d'autres objets : une frame est un conteneur). Nos 2 champs identifiant et passe seront récupérés normalement par PHP :

$identifiantsaisit = bab_pp('identifiant', '');
$motdepassesaisit = bab_pp('identifiant', '');

Cependant dès l'instant que vous définissez des noms aux conteneurs présents dans le formulaire, les données envoyées seront envoyées sous forme de tableaux.

Si on définit un nom à l'objet Widget_Form :

$form = $W->Form()->setName('formulaire_identification');

Les données seront reçues dans un tableau :

$donneesformulaire = bab_rp('formulaire_identification', array());
$identifiantsaisit = '';
$motdepassesaisit = '';
if (isset($donneesformulaire['identifiant'])) {
   $identifiantsaisit = $donneesformulaire['identifiant'];
}
if (isset($donneesformulaire['passe'])) {
   $motdepassesaisit = $donneesformulaire['passe'];
}

Styliser les éléments

Vous pouvez styliser les éléments Widgets en appelant une feuille de styles CSS dans la page. Vous définissez alors des styles sur les classes générées par les widgets.

$W = bab_functionality::get('Widgets');
$W->includeCss();
$page = $W->BabPage();
$page->setLayout($W->VBoxLayout());
 
$page->addStyleSheet('styles.css');

Pour être plus précis, vous pouvez ajouter une classe sur tous les éléments widgets :

$field = $W->LineEdit()->setName('identifiant')->addClass('field-description');


Exemples

Hello world !

Commençons par un exemple simple qui se contentera d'afficher le texte "Hello world !" sur une page. L'exemple contient un certain nombre d'opérations qui seront nécessaires pour toutes les pages utilisant les widgets.

// Ici on récupère l'objet Func_Widgets qui servira notamment à créer tous les widgets et layouts
$W = bab_functionality::get('Widgets');
 
// On crée une page, qui sera le container principal.
$page = $W->BabPage();
 
// On associe à la page une mise en page (layout) verticale : les éléments qu'on y ajoutera seront disposés les uns sous les autres.
$page->setLayout($W->VBoxLayout());
 
// Création d'un simple texte (Label)
$helloLabel = $W->Label('Hello world !');
 
// On ajoute ce texte à la page.
$page->addItem($helloLabel);
 
// C'est fini, on affiche la page.
$page->displayHtml();

Diagramme d'héritage des classes

Voici un diagramme court montrant l'héritage et les relations entre les classes objets :

Diagramme
Diagramme

Un peu d'explications :

Sur la gauche de l'image, on aperçoit les classes Widget_ContainerWidget, Widget_Widget et Widget_Item. Tous les objets de la librairie héritent de la classe Widget_Item.

On a pris comme exemple la classe Widget_Form qui gère la construction d'un formulaire de saisie. On remarque que la classe Widget_Form hérite de Widget_ContainerWidget. En effet, dans le cas des objets qui peuvent contenir d'autres objets, on passe par la classe Widget_ContainerWidget pour gérer les sous-éléments.

Un second avantage est la relation de la classe Widget_ContainerWidget avec Widget_Layout. Widget_Layout gère la disposition des éléments dans un Widget_ContainerWidget. Ainsi, le choix d'une disposition VBoxLayout permettra d'afficher automatiquement les éléments à la verticale les uns en dessous des autres sans gérer nous-mêmes de retours à la ligne.

Sur la droite, on aperçoit les classes Canvas. Elles sont destinées à afficher ou exporter les données au format désiré. Toutes les méthodes display() des objets de la librairie prennent en paramètre un Canvas. Le Canvas le plus utilisé est Widgets_HtmlCanvas : il affiche les objets (Form, InputSelect, DatePicker, Page...) pour une page Web donc au format HTML, javascript, css...

Comprendre les Widgets un par un

Widget_CsvImportForm

Introduction

Ce widget permet de gérer automatiquement un import de données à partir d'une source CSV.

Un fichier CSV contient des enregistrements (un enregistrement par ligne) dont les données (nom, prénom, téléphone...) sont séparées par des virgules. Pour être compatible avec les formats CSV de Microsoft, le widget gère la séparation des données par des points-virgules.

L'import s'effectue en plusieurs étapes :

  • Affichage du formulaire de dépôt du fichier CSV
  • Affichage du formulaire d'association Champ de table-Colonne du fichier CSV
  • Import des données
  • Affichage des résultats et erreurs si elles existent
Implémentation

Tout d'abord il est nécessaire d'afficher le formulaire de dépôt du fichier CSV en créant un objet Widget_CsvImportForm.

Pour préparer l'étape suivante d'association Champ de table-Champ de colonne CSV, il est nécessaire d'indiquer les champs de table. La méthode addImportField() de la classe Widget_CsvImportForm permet d'indiquer ces champs. Elle prend en paramètres le nom du champ, son libellé et un booléen permettant d'indiquer si le champ est obligatoire au moment de l'étape d'association des champs. En effet, tant que l'utilisateur n'aura pas associé les champs obligatoires à des colonnes du fichier CSV, l'étape suivante ne s'exécutera pas.

$W = bab_Functionality::get('Widgets');
 
$importForm = $W->CsvImportForm()
	->addImportField('lastname', 'Nom', true)
	->addImportField('firstname', 'Prénom', true)
	->addImportField('email', 'E-mail')
	->addImportField('phone', 'Téléphone')
	;
 
$page = $W->Page();
$page->addItem($importForm);
$page->displayHtml();

Le formulaire aura cette apparence :

Formulaire d'import CSV

L'étape suivante (formulaire d'association des champs) est prise en charge automatiquement par le Widget. Ainsi, l'URL en cours sera automatiquement rappelée pour afficher le formulaire d'association suivant.

Le développeur doit donc prévoir que la page affichant le formulaire de départ affichera aussi la deuxième étape.

Aperçu de l'étape d'association :

Formulaire d'association des champs

Dès lors que l'étape d'association des champs est validée, l'objet Widget_CsvImportForm fournit un itérateur via la méthode getIterator(). Pour vérifier que l'étape d'association est terminée, utilisez le code suivant, la méthode getIterator() retourne un objet Widget_CsvIterator ou NULL :

if ($iterator = $import->getIterator()) {
 
}

L'itérateur va passer en revue chaque ligne du fichier source CSV.

Exemple de code PHP permettant de passer en revue chaque ligne du fichier CSV. L'itérateur retourne des objets Widget_CsvRow pour chaque ligne du fichier CSV :

foreach($iterator as $position => $row) { /* $row : object Widget_CsvRow */
 
}

L'objet Widget_CsvRow :

  • la méthode line() permet de connaître le numéro de ligne dans le fichier CSV
  • la méthode checkMandatory() retourne un booléen. Permet de vérifier si la ligne contient des valeurs pour les champs indiqués comme obligatoires à la configuration de l'import
  • les propriétés de l'objet ont pour noms les champs de configuration (définis via addImportField()). Les valeurs des propriétés correspondent aux valeurs trouvées dans le fichier CSV.

Exemple de code pour remonter tous les Nom et Prénom du fichier CSV :

foreach($iterator as $position => $row) { /* $row : object Widget_CsvRow */
   if (isset($row->firstname) && isset($row->lastname)) {
      echo $row->firstname.' '.$row->name;
   }
}

Mettre en place les Widget_Action dans un module

La librairie partagée Widgets d'Ovidentia propose un objet Widget_Action.

On appelle Action la définition d'un événement, d'une opération ou d'une destination. Elle est dissociée de la méthode (URL GET, URL POST, cookies...).

Méthodes principales de l'objet Widget_Action
  • fromRequest()
Charge l'objet Widget_Action avec les paramètres de la requête en cours (POST ou GET)
  • fromUrl($url)
Charge l'objet Widget_Action avec l'url passée en paramètre
  • setMethod($controller, $method, $parameters)
Définit la fonction PHP associée à l'action
  • url()
Retourne l'action sous la forme d'une URL GET (?tg=addon/...)
Actions et formulaires

La librairie partagée Widgets définit une action par l'objet Widget_Action.

La librairie partagée Widgets définit un formulaire par l'objet Widget_Form.

Il est possible sur les boutons de soumissions de formulaires (objets Widget_SubmitButton) de leurs associer automatiquement des actions :

$action = $W->action()->fromRequest();
$button = $W->SubmitButton()
                    ->setLabel('Create')
                    ->setAction($action);