Créer et rendre des éléments composites

Dans la dernière section, nous avions un exemple traitant un élément "date de naissance":

<div class="element">
    <?php echo $form->dateOfBirth->renderLabel() ?>
    <?php echo $this->formText('dateOfBirth[day]', '', array(
        'size' => 2, 'maxlength' => 2)) ?>
    /
    <?php echo $this->formText('dateOfBirth[month]', '', array(
        'size' => 2, 'maxlength' => 2)) ?>
    /
    <?php echo $this->formText('dateOfBirth[year]', '', array(
        'size' => 4, 'maxlength' => 4)) ?>
</div>

Comment représenteriez-vous cet élément en tant que Zend_Form_Element? Comment écrire un décorateur qui s'assure de son rendu ?

L'élément

Les questions à se poser sur le fonctionnement de l'élément sont:

Comment affecter et récupérer une valeur?
Comment valider la valeur?
Comment proposer l'affectation personnalisée d'une valeur composées de trois segments (jour, mois, année)?

Les deux première questions se positionnent sur l'élément de formulaire lui-même, comment vont fonctionner les méthodes setValue() et getValue()? L'autre question nous suggère de nous questionner sur comment récupérer les segments représentant la date, ou comment les affecter dans l'élément?

La solution est de surcharger la méthode setValue() dans l'élément pour proposer sa propre logique. Dans le cas de notre exemple, notre élément devrait avoir trois comportements distincts:

Si un timestamp entier est utilisé, il doit aider à la détermination des entités jour, mois, année.
Si une chaine est utilisée, elle devrait être transformée en timestamp, et cette valeur sera utiliser pour déterminer les entités jour, mois, année.
Si un tableau contenant les clés jour, mois, année est utilisé, alors les valeurs doivent être stockées.

En interne, les jour, mois et année seront stockés distinctement. Lorsque la valeur de l'élément sera demandée, nous récupèrerons une chaine formatée et normalisée. Nous surchargerons getValue() pour assembler les segments élémentaires composant la date.

Voici à quoi ressemblerait la classe:

class My_Form_Element_Date extends Zend_Form_Element_Xhtml
{
    protected $_dateFormat = '%year%-%month%-%day%';
    protected $_day;
    protected $_month;
    protected $_year;
 
    public function setDay($value)
    {
        $this->_day = (int) $value;
        return $this;
    }
 
    public function getDay()
    {
        return $this->_day;
    }
 
    public function setMonth($value)
    {
        $this->_month = (int) $value;
        return $this;
    }
 
    public function getMonth()
    {
        return $this->_month;
    }
 
    public function setYear($value)
    {
        $this->_year = (int) $value;
        return $this;
    }
 
    public function getYear()
    {
        return $this->_year;
    }
 
    public function setValue($value)
    {
        if (is_int($value)) {
            $this->setDay(date('d', $value))
                 ->setMonth(date('m', $value))
                 ->setYear(date('Y', $value));
        } elseif (is_string($value)) {
            $date = strtotime($value);
            $this->setDay(date('d', $date))
                 ->setMonth(date('m', $date))
                 ->setYear(date('Y', $date));
        } elseif (is_array($value)
                  && (isset($value['day'])
                      && isset($value['month'])
                      && isset($value['year'])
                  )
        ) {
            $this->setDay($value['day'])
                 ->setMonth($value['month'])
                 ->setYear($value['year']);
        } else {
            throw new Exception('Valeur de date invalide');
        }
 
        return $this;
    }
 
    public function getValue()
    {
        return str_replace(
            array('%year%', '%month%', '%day%'),
            array($this->getYear(), $this->getMonth(), $this->getDay()),
            $this->_dateFormat
        );
    }
}

Cette classe est fléxible : nous pouvons affecter les valeurs par défaut depuis une base de données et être certains qu'elles seront stockées correctement. Aussi, la valeur peut être affectée depuis un tableau provenant des entrées du formulaire. Enfin, nous avons tous les accesseurs distincts pour chaque segment de la date, un décorateur pourra donc créer l'élément comme il le voudra.

Le décorateur

Toujours en suivant notre exemple, imaginons que nous voulions que notre utilisateur saisissent chaque segment jour, mois, année séparément. Heureusement, PHP permet d'utiliser la notation tableau pour créer des éléments, ainsi nous pourrons capturer ces trois valeurs en une seule et nous crérons un élément Zend_Form traitant avec des valeurs en tableau.

Le décorateur est relativement simple: Il va récupérer le jour, le mois et l'année de l'élément et passer chaque valeur à une aide de vue qui rendra chaque champ individuellement. Nous les rassemblerons ensuite dans le rendu final.

class My_Form_Decorator_Date extends Zend_Form_Decorator_Abstract
{
    public function render($content)
    {
        $element = $this->getElement();
        if (!$element instanceof My_Form_Element_Date) {
            // Nous ne rendons que des éléments Date
            return $content;
        }
 
        $view = $element->getView();
        if (!$view instanceof Zend_View_Interface) {
            // Nous utilisons des aides de vue, si aucune vue n'existe
            // nous ne rendons rien
            return $content;
        }
 
        $day   = $element->getDay();
        $month = $element->getMonth();
        $year  = $element->getYear();
        $name  = $element->getFullyQualifiedName();
 
        $params = array(
            'size'      => 2,
            'maxlength' => 2,
        );
        $yearParams = array(
            'size'      => 4,
            'maxlength' => 4,
        );
 
        $markup = $view->formText($name . '[day]', $day, $params)
                . ' / ' . $view->formText($name . '[month]', $month, $params)
                . ' / ' . $view->formText($name . '[year]', $year, $yearParams);
 
        switch ($this->getPlacement()) {
            case self::PREPEND:
                return $markup . $this->getSeparator() . $content;
            case self::APPEND:
            default:
                return $content . $this->getSeparator() . $markup;
        }
    }
}

Il faut maintenant préciser à notre élément d'utiliser notre décorateur par défaut. Pour ceci, il faut informer l'élément du chemin vers notre décorateur. Nous pouvons effectuer ceci par le constructeur:

class My_Form_Element_Date extends Zend_Form_Element_Xhtml
{
    // ...
 
    public function __construct($spec, $options = null)
    {
        $this->addPrefixPath(
            'My_Form_Decorator',
            'My/Form/Decorator',
            'decorator'
        );
        parent::__construct($spec, $options);
    }
 
    // ...
}

Notez que l'on fait cela en constructeur et non dans la méthode init(). Ceci pour deux raisons. D'abord, ceci permet d'étendre dans le futur notre élément afin d'y ajouter de la logique dans init sans se soucier de l'appel à parent::init(). Ensuite, celà permet aussi de redéfinir le décorateur par défaut Date dans le futur si celà devient nécessaire, via le constructeur ou la méthode init.

Ensuite, nous devons réécrire la méthode loadDefaultDecorators() pour lui indiquer d'utiliser notre décorateur Date:

class My_Form_Element_Date extends Zend_Form_Element_Xhtml
{
    // ...
 
    public function loadDefaultDecorators()
    {
        if ($this->loadDefaultDecoratorsIsDisabled()) {
            return;
        }
 
        $decorators = $this->getDecorators();
        if (empty($decorators)) {
            $this->addDecorator('Date')
                 ->addDecorator('Errors')
                 ->addDecorator('Description', array(
                     'tag'   => 'p',
                     'class' => 'description'
                 ))
                 ->addDecorator('HtmlTag', array(
                     'tag' => 'dd',
                     'id'  => $this->getName() . '-element'
                 ))
                 ->addDecorator('Label', array('tag' => 'dt'));
        }
    }
 
    // ...
}

A qyuoi ressemble le rendu final ? Considérons l'élément suivant:

$d = new My_Form_Element_Date('dateOfBirth');
$d->setLabel('Date de naissance: ')
  ->setView(new Zend_View());
 
// Ces deux procédés sont équivalents:
$d->setValue('20 April 2009');
$d->setValue(array('year' => '2009', 'month' => '04', 'day' => '20'));

Si vous affichez cet élément, vous obtiendrez ce rendu (avec quelques modifications concernant la mise en page du manuel et sa lisibilité):

<dt id="dateOfBirth-label"><label for="dateOfBirth" class="optional">
    Date de naissance:
</label></dt>
<dd id="dateOfBirth-element">
    <input type="text" name="dateOfBirth[day]" id="dateOfBirth-day"
        value="20" size="2" maxlength="2"> /
    <input type="text" name="dateOfBirth[month]" id="dateOfBirth-month"
        value="4" size="2" maxlength="2"> /
    <input type="text" name="dateOfBirth[year]" id="dateOfBirth-year"
        value="2009" size="4" maxlength="4">
</dd>

Conclusion

Nous avons maintenant un élément qui peut rendre de multiples champs de formulaire, et les traiter comme une seule entité -- la valeur dateOfBirth sera passée comme un tableau à l'élément et celui-ci créra les segments de date appropriés et retournera une valeur normalisée.

Aussi, nous pouvons toujours utiliser des décorateurs différents avec l'élément. Si nous avions voulu utiliser un décorateur » Dojo DateTextBox -- qui accepte et retourne des chaines -- we aurions pu, sans modification sur l'élément lui-même.

Enfin, vous avez une API uniforme pour décrire un élement se composant se plusieurs segments distincts.