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,
        'value' => '',
        'title' => null
    )
);

Produira le code HTML suivant :

<input type="checkbox" name="online" checked="checked" value="" />

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 exemple checked="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>

Ajouter un label avec l'attribut 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 une div class="form-label" et l'élément dans une div class="form-element".
  • left : le label sera placé à gauche de l'élément. Le texte &nbsp;: 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.

Créer un groupe de boites à cocher avec le type 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(02)
    )
);
<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>
Trois chiffres

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.

Définissez les options de vos éléments avec l'attribut 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>
Trois chiffres

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

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.

Définissez les enfants de vos éléments avec l’attribut 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 => array
        (
            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 &amp; 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 !

Laisser un commentaire

2 commentaires

reno
reno

pas mal du tout ton système ! juste deux corrections sur le code que tu donnes en exemple.

Pour l'attribut spécial T_OPTIONS : corriger pour mettre echo new WdElement (facile)

Et pour l’attribut spécial T_CHILDREN, le premier élément de T_CHILDREN doit être un array, donc le code devient : (désolé pour la mise en page pourrie)

<?php

echo new WdElement('p', 
    array(
        WdElement::T_CHILDREN => (
        array(
            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'))
        )
        )
    ));

Et sinon pour le forum tu peux donner un exemple ou bien ? En tout cas merci pour ce boulot et pour l'avoir mis à disposition.

Olivier
Olivier

Salut Reno,

J'ai publié un article qui présente comment réaliser un formulaire de contact avec gestion d'erreurs et validation de données en utilisant le framework WdElements.

J'espère que tu le trouveras aussi intéressant.