WdElement : une classe pour générer des éléments HTML
La classe WdElement est la classe de base du framework WdElements.
Elle permet de générer n'importe quel type d'élément HTML et même des arbres d'éléments. Elle propose en outre des types d'éléments ainsi que des attributs spéciaux pour, par exemple, créer rapidement des groupes de boites à cocher.
Il n'y a pas de restriction concernant les types d'éléments qui peuvent être générés ou les attributs que l'on peut utiliser pour les générer.
Les éléments sont générés en respectant les règles de structuration et d'échappement du XHTML.
Utilisation basique
Avant d'aborder les types et les attributs spéciaux, voyons comment créer une boîte à cocher en utilisant les attributs standard du HTML. Pour cela, nous allons simplement définir le type et les attributs de la boîte à cocher.
On utilise un tableau associatif pour définir les attributs de l'élément :
<?php
echo new WdElement
(
'input', array
(
'type' => 'checkbox',
'name' => 'online',
'checked' => true,
'disabled' => false,
'title' => null
)
);
?>
Produira le code HTML suivant :
<input type="checkbox" name="online" checked="checked" />
Soit une simple boite à cocher :
Remarque sur les attributs et la génération du code HTML
Si l'attribut a pour valeur
true, il est considéré comme un booléen. Il est ajouté au code HTML avec son nom pour valeur. Par exemplechecked="checked".Si l'attribut a pour valeur
false, il est ignoré lors de la génération du code HTML.Si l'attribut a pour valeur
null, il est également ignoré lors de la génération du code HTML.Si le contenu de l'élément est
null, il se ferme lui-même. Par exemple :<div />. Si le contenu est une chaine vide, l'élément généré est vide mais possède une balise d'ouverture et une balise de fermeture. Par exemple :<div></div>.Toutes les valeurs des attributs sont échappées en utilisant la fonction
wd_entities.
Types et attributs spéciaux
Comme je vous l'ai dis plus haut, la classe introduit également des types d'éléments spéciaux.
Plusieurs sont disponibles : E_CHECKBOX, E_CHECKBOX_GROUP, E_FILE, E_PASSWORD,
E_RADIO, E_RADIO_GROUP, E_TEXT… Les types sont préfixés d'un E_ (pour élément).
Les attributs spéciaux sont eux préfixés d'un T_ (pour tag).
Le code PHP suivant :
<?php
echo new WdElement
(
WdElement::E_CHECKBOX, array
(
WdElement::T_LABEL => 'A checkbox',
'name' => 'online',
'checked' => true,
'disabled' => false,
'title' => null
)
);
?>
Produira le code HTML suivant :
<label><input name="online" checked="checked" type="checkbox" /> A checkbox</label>
L'attribut spécial T_LABEL
L'attribut spécial T_LABEL peut être utilisé pour associer un label à un élément. Il est
possible de définir la position du label par rapport à l'élément en utilisant l'attribut
spécial T_LABEL_POSITION et l'une des valeurs suivantes :
top: le label sera placé au dessus de l'élément. Le label sera placé dans unediv class="form-label"et l'élément dans unediv class="form-element".left: le label sera placé à gauche de l'élément. Le texte :sera ajouté à la fin du label.right: (par défaut) le label sera placé à droite de l'élément, comme dans l'exemple ci-dessus.
Bon, un bouton radio avec un label c'est sympa, mais essayons quelque chose de plus complexe.
Le type d'élément spécial E_CHECKBOX_GROUP
Nous allons maintenant créer un groupe de trois boîtes à cocher, dont la première et la dernière sont cochées. Cela demande en général pas mal code, surtout si l'on doit gérer les boîtes cochées. Pour cela, nous allons recourir au type spécial E_CHECKBOX_GROUP. Ce type permet de créer des groupes de boîtes à cocher en prenant soin de gérer les états des boîtes :
<?php
echo new WdElement
(
WdElement::E_CHECKBOX_GROUP, array
(
WdElement::T_LEGEND => 'Trois chiffres',
WdElement::T_OPTIONS => array
(
'Un', 'Deux', 'Trois'
),
'name' => 'online',
'value' => array(0, 2)
)
);
?>
<fieldset><legend>Trois chiffres</legend><div class="checkbox-group"><label><input type="checkbox" name="online[0]" value="0" checked="checked" /> Un</label><label><input type="checkbox" name="online[1]" value="1" /> Deux</label><label><input type="checkbox" name="online[2]" value="2" checked="checked" /> Trois</label></div></fieldset>
L'attribut spécial T_LEGEND définit la légende à utiliser pour l'élément. L'élément est alors placé dans un élément fieldset dont la légende est la valeur de l'attribut.
L'attribut value est détourné par le type spécial E_CHECKBOX_GROUP pour permettre de définir les boîtes qui sont cochées. Dans notre exemple, les boîtes 0 et 2. L'attribut spécial T_OPTIONS est lui utilisé pour définir les valeurs des boîtes ainsi que leur label.
L'attribut spécial T_OPTIONS
L'attribut spécial T_OPTIONS permet de définir les différentes options pour un groupe de boîtes à cocher (E_CHECKBOX_GROUP), un groupe de boutons radio (E_RADIO_GROUP) ou encore un menu déroulant (avec le très classique select).
Les différentes options sont définies en utilisant un tableau associatif.
Les clés des entrées de ce tableau sont utilisées pour renseigner l'attribut value de l'option. Les valeurs, quand à elles, sont utilisées pour son label.
À noter que le label est traduit par la fonction t() puis échappé par la fonction wd_entities().
<?php
new WdElement
(
WdElement::E_RADIO_GROUP, array
(
WdElement::T_LEGEND => 'Trois chiffres',
WdElement::T_OPTIONS => array
(
'Un', 'Deux', 'Trois'
),
'name' => 'online',
'value' => 1
)
);
?>
<fieldset><legend>Trois chiffres</legend><div class="radio-group"><label><input type="radio" name="online" value="0" /> Un</label><label><input type="radio" name="online" value="1" checked="checked" /> Deux</label><label><input type="radio" name="online" value="2" /> Trois</label></div></fieldset>
Pour un menu déroulant utilisant le type select :
<fieldset><legend>Trois chiffres</legend><select name="online"><option value="0">Un</option><option value="1" selected="selected">Deux</option><option value="2">Trois</option></select></fieldset>
Il existe de nombreux autres types d'éléments et attributs spéciaux. Nous les aborderons certainement dans d’autres billets, celui-ci étant juste une introduction aux concepts fondamentaux du framework WdElement. Il nous reste d'ailleurs une dernière chose à voir dans cette introduction : la création d’arbres d’éléments.
Les arbres d’éléments
Comme je l’avais dis en introduction, la classe WdElement peut également créer des arbres d’éléments. On utilise pour cela l’attribut spécial T_CHILDREN.
L’attribut spécial T_CHILDREN
L’attribut spécial T_CHILDREN permet de définir les enfants d’un élément. Ces enfants peuvent être d’autres éléments de la classe WdElement, ou simplement des chaines de caractères.
Lorsque l’élément est converti en code HTML, ces enfants le sont également, puis ils sont concaténés pour former le code HTML interne de l’élément.
<?php
echo WdElement
(
'p', array
(
WdElement::T_CHILDREN =>
(
new WdElement
(
'a', array
(
'href' => 'http://www.google.fr/search?q=olivier+laviale',
'title' => 'Lien & autre',
WdElement::T_INNER_HTML => 'rechercher <em>olivier laviale</em>'
)
),
' <strong>un bout de texte avec emphase</strong> ',
new WdElement
(
WdElement::E_TEXT, array
(
'size' => 32,
'value' => 'Une chaîne'
)
)
)
)
);
?>
<p><a href="http://www.google.fr/search?q=olivier+laviale" title="Lien & autre">rechercher <em>olivier laviale</em></a> <strong>un bout de texte avec emphase</strong> <input size="32" value="Une chaîne" type="text" /></p>
rechercher olivier laviale un bout de texte avec emphase
À venir
« Évidement, générer des éléments HTML c'est bien joli, mais nous ce qu'on veut c'est du formulaire velu ! ». Et bien c'est ce que je vous propose de découvrir dans un prochain billet. Je vous présenterai alors la classe WdForm et ses deux sous classes Wd2CForm et WdTemplatedForm qui permettent de générer des formulaires de type label / élément pour l'une, et des formulaires à partir de gabarits HTML pour l'autre. À cette occasion nous découvrirons comment réaliser un formulaire de contact avec validation des données et gestion des erreurs.
Conclusion
J'espère en tout cas que cette petite introduction ne vous a pas fait peur. N'ayez crainte, tout deviendra limpide et presque excitant lorsque nous verrons tout cela appliqué dans de beaux formulaires.
En attendant je vous souhaite une bonne nuit et vous dit à bientôt !