Klasa Zend_Form_Element używa klasy Zend_Loader_PluginLoader aby umożliwić programistom określenie ścieżek, w których znajdują się alternatywne weryfikatory, filtry i dekoratory. Każda z tych wtyczek ma przypisaną własną klasę ładującą je, a do ich modyfikacji używany jest zestaw metod dostępowych.

W metodach obsługujących ładowanie wtyczek używane są następujące typy: 'validate', 'filter' oraz 'decorator'. Wielkość liter w nazwach typów nie jest istotna.

Metody używane do obsługi ładowania wtyczek to:

Własne weryfikatory, filtry i dekoratory są łatwym sposobem na użycie pewnej własnej funkcjonalności w wielu formularzach.

class My_Decorator_Label extends Zend_Form_Decorator_Abstract
{
    protected $_placement = 'PREPEND';

    public function render($content)
    {
        if (null === ($element = $this->getElement())) {
            return $content;
        }
        if (!method_exists($element, 'getLabel')) {
            return $content;
        }

        $label = $element->getLabel() . ':';

        if (null === ($view = $element->getView())) {
            return $this->renderLabel($content, $label);
        }

        $label = $view->formLabel($element->getName(), $label);

        return $this->renderLabel($content, $label);
    }

    public function renderLabel($content, $label)
    {
        $placement = $this->getPlacement();
        $separator = $this->getSeparator();

        switch ($placement) {
            case 'APPEND':
                return $content . $separator . $label;
            case 'PREPEND':
            default:
                return $label . $separator . $content;
        }
    }
}

            

$element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');

            

$form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');

            

It's often useful and/or necessary to perform some normalization on input prior to validation – for instance, you may want to strip out all HTML, but run your validations on what remains to ensure the submission is valid. Or you may want to trim empty space surrounding input so that a StringLength validator will not return a false positive. These operations may be performed using Zend_Filter, and Zend_Form_Element has support for filter chains, allowing you to specify multiple, sequential filters to utilize. Filtering happens both during validation and when you retrieve the element value via getValue():

$filtered = $element->getValue();

        

Filtry mogą być dodane na dwa sposoby:

Zobaczmy kilka przykładów:

// Konkretny egzemplarz obiektu filtra:
$element->addFilter(new Zend_Filter_Alnum());

// Pełna nazwa filtra:
$element->addFilter('Zend_Filter_Alnum');

// Krótka nazwa filtra:
$element->addFilter('Alnum');
$element->addFilter('alnum');

        

Krótkie nazwy są zazwyczaj nazwą klasy filtra pozbawioną przedrostka. W domyślnym przypadku, będzie to oznaczało że pomijamy przedrostek 'Zend_Filter_'. Nie jest też konieczne aby pierwsza litera była wielka.

$element->addPrefixPath('My_Filter', 'My/Filter/', 'filter');

            

Jęśli w potrzebujesz niefiltrowaną wartość użyj metody getUnfilteredValue():

$unfiltered = $element->getUnfilteredValue();

        

Aby uzyskać więcej informacji o filtrach zobacz dokumentację klasy Zend_Filter.

Metody powiązane z filtrami to:

If you subscribe to the security mantra of "filter input, escape output," you'll want to validate ("filter input") your form input. In Zend_Form, each element includes its own validator chain, consisting of Zend_Validate_* validators.

Weryfikatory mogą być dodane na dwa sposoby:

Zobaczmy kilka przykładów:

// Konkretny egzemplarz obiektu weryfikatora:
$element->addValidator(new Zend_Validate_Alnum());

// Pełna nazwa klasy:
$element->addValidator('Zend_Validate_Alnum');

// Krótka nazwa weryfikatora:
$element->addValidator('Alnum');
$element->addValidator('alnum');

        

Krótkie nazwy są zazwyczaj nazwą klasy weryfikatora pozbawioną przedrostka. W domyślnym przypadku, będzie to oznaczało że pomijamy przedrostek 'Zend_Validate_'. Nie jest też konieczne aby pierwsza litera była wielka.

$element->addPrefixPath('My_Validator', 'My/Validator/', 'validate');

            

If failing a particular validation should prevent later validators from firing, pass boolean true as the second parameter:

$element->addValidator('alnum', true);

        

If you are using a string name to add a validator, and the validator class accepts arguments to the constructor, you may pass these to the third parameter of addValidator() as an array:

$element->addValidator('StringLength', false, array(6, 20));

        

Arguments passed in this way should be in the order in which they are defined in the constructor. The above example will instantiate the Zend_Validate_StringLenth class with its $min and $max parameters:

$validator = new Zend_Validate_StringLength(6, 20);

        

Możesz także ustawić wiele weryfikatorów na raz, używając metody addValidators(). Podstawowym sposobem użycia jest przekazanie tablicy tablic, gdzie każda z tablic posiada od 1 do 3 wartości, zgodnych z wywołaniem metody addValidator():

$element->addValidators(array(
    array('NotEmpty', true),
    array('alnum'),
    array('stringLength', false, array(6, 20)),
));

        

If you want to be more verbose or explicit, you can use the array keys 'validator', 'breakChainOnFailure', and 'options':

$element->addValidators(array(
    array(
        'validator'           => 'NotEmpty',
        'breakChainOnFailure' => true),
    array('validator' => 'alnum'),
    array(
        'validator' => 'stringLength',
        'options'   => array(6, 20)),
));

        

Ten przykład pokazuje w jaki sposób możesz skonfigurować weryfikatory w pliku konfiguracyjnym:

element.validators.notempty.validator = "NotEmpty"
element.validators.notempty.breakChainOnFailure = true
element.validators.alnum.validator = "Alnum"
element.validators.strlen.validator = "StringLength"
element.validators.strlen.options.min = 6
element.validators.strlen.options.max = 20

        

Notice that every item has a key, whether or not it needs one; this is a limitation of using configuration files -- but it also helps make explicit what the arguments are for. Just remember that any validator options must be specified in order.

Aby sprawdzić poprawność elementu przekaż wartość do metody: isValid():

if ($element->isValid($value)) {
    // prawidłowy
} else {
    // nieprawidłowy
}

        

class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract
{
    const NOT_MATCH = 'notMatch';

    protected $_messageTemplates = array(
        self::NOT_MATCH => 'Password confirmation does not match'
    );

    public function isValid($value, $context = null)
    {
        $value = (string) $value;
        $this->_setValue($value);

        if (is_array($context)) {
            if (isset($context['password_confirm'])
                && ($value == $context['password_confirm']))
            {
                return true;
            }
        } elseif (is_string($context) && ($value == $context)) {
            return true;
        }

        $this->_error(self::NOT_MATCH);
        return false;
    }
}

            

Validators are processed in order. Each validator is processed, unless a validator created with a true breakChainOnFailure value fails its validation. Be sure to specify your validators in a reasonable order.

Po nieudanej weryfikacji możesz pobrać kody i komunikaty błędów:

$errors   = $element->getErrors();
$messages = $element->getMessages();

        

(Uwaga: komunikaty o błędach są zwracane jako asocjacyjna tablica w postaci par kod / komunikat.)

In addition to validators, you can specify that an element is required, using setRequired(true). By default, this flag is false, meaning that your validator chain will be skipped if no value is passed to isValid(). You can modify this behavior in a number of ways:

Aby uzyskać więcej informacji o weryfikatorach, zobacz dokumentację klasy Zend_Validate.

Metody powiązane z weryfikatorami to:

One particular pain point for many web developers is the creation of the XHTML forms themselves. For each element, the developer needs to create markup for the element itself, typically a label, and, if they're being nice to their users, markup for displaying validation error messages. The more elements on the page, the less trivial this task becomes.

Zend_Form_Element tries to solve this issue through the use of "decorators". Decorators are simply classes that have access to the element and a method for rendering content. For more information on how decorators work, please see the section on Zend_Form_Decorator.

Domyśle dekoratory używane przez klasę Zend_Form_Element to:

$element = new Zend_Form_Element('foo',
                                 array('disableLoadDefaultDecorators' =>
                                      true)
                                 );

            

Z tego względu, że kolejność w jakiej rejestrowane są dekoratory ma znaczenie -- dekoratory są uruchamiane w takiej kolejności w jakiej zostały zarejestrowane -- musisz się upewnić, że rejestrujesz je w odpowiedniej kolejności lub użyć opcji pozwalającej na zarejestrowanie dekoratora w konkretnej pozycji. Poniżej jako przykład został zamieszczony przykładowy kod, który rejestruje domyślne dekoratory:

$this->addDecorators(array(
    array('ViewHelper'),
    array('Errors'),
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));

        

The initial content is created by the 'ViewHelper' decorator, which creates the form element itself. Next, the 'Errors' decorator fetches error messages from the element, and, if any are present, passes them to the 'FormErrors' view helper to render. The next decorator, 'HtmlTag', wraps the element and errors in an HTML <dd> tag. Finally, the last decorator, 'label', retrieves the element's label and passes it to the 'FormLabel' view helper, wrapping it in an HTML <dt> tag; the value is prepended to the content by default. The resulting output looks basically like this:

<dt><label for="foo" class="optional">Foo</label></dt>
<dd>
    <input type="text" name="foo" id="foo" value="123" />
    <ul class="errors">
        <li>"123" is not an alphanumeric value</li>
    </ul>
</dd>

        

Aby uzyskać więcej informacji o dekoratorach, zobacz dokumentację klasy Zend_Form_Decorator.

// Alias dla 'FooBar':
$element->addDecorator(array('FooBar' => 'HtmlTag'),
                       array('tag' => 'div'));

// Pobieramy dekorator:
$decorator = $element->getDecorator('FooBar');

            

// Dodanie dwóch dekoratorów 'HtmlTag', ustawiając nazwę jednego z nich na 'FooBar':
$element->addDecorators(
    array('HtmlTag', array('tag' => 'div')),
    array(
        'decorator' => array('FooBar' => 'HtmlTag'),
        'options' => array('tag' => 'dd')
    ),
);

// I pobranie ich póżniej:
$htmlTag = $element->getDecorator('HtmlTag');
$fooBar  = $element->getDecorator('FooBar');

            

Metody powiązane z dekoratorami to:

Zend_Form_Element obsługuje wiele atrybutów i danych meta dla elementów. Te atrybuty to:

Elementy formularzy mogą wymagać dodatkowych danych meta. Przykładowo dla elementów formularzy XHTML możesz chcieć określić takie atrybuty jak 'class' czy 'id'. Do obsługi tego istnieje kilka metod dostępowych:

Most of the time, however, you can simply access them as object properties, as Zend_Form_Element utilizes overloading to facilitate access to them:

// Odpowiednik metody $element->setAttrib('class', 'text'):
$element->class = 'text;

        

By default, all attributes are passed to the view helper used by the element during rendering, and rendered as HTML attributes of the element tag.

Komponent Zend_Form posiada duży zestaw standardowych elementów; przeczytaj rozdział Standardowe Elementy aby poznać więcej szczegółów.

Klasa Zend_Form_Element posiada bardzo dużo metod. Poniżej zamieszczono podsumowanie ich sygnatur, pogrupowanych na podstawie typu:

Konstruktor klasy Zend_Form_Elementprzyjmuje w parametrze tablicę opcji lub obiekt Zend_Config zawierający pcje. Klasa może być także skonfigurowana za pomocą metod setOptions() oraz setConfig(). Generalnie klucze nazwane są w taki sposób:

Oto wyjątki od tej zasady:

As an example, here is a config file that passes configuration for every type of configurable data:

[element]
name = "foo"
value = "foobar"
label = "Foo:"
order = 10
required = true
allowEmpty = false
autoInsertNotEmptyValidator = true
description = "Foo elements are for examples"
ignore = false
attribs.id = "foo"
attribs.class = "element"
; ustawia atrybut 'onclick'
onclick = "autoComplete(this, '/form/autocomplete/element')"
prefixPaths.decorator.prefix = "My_Decorator"
prefixPaths.decorator.path = "My/Decorator/"
disableTranslator = 0
validators.required.validator = "NotEmpty"
validators.required.breakChainOnFailure = true
validators.alpha.validator = "alpha"
validators.regex.validator = "regex"
validators.regex.options.pattern = "/^[A-F].*/$"
filters.ucase.filter = "StringToUpper"
decorators.element.decorator = "ViewHelper"
decorators.element.options.helper = "FormText"
decorators.label.decorator = "Label"

        

Możesz tworzyć własne elementy po prostu rozszerzając klasę Zend_Form_Element. Powodami aby to zrobić mogą być:

There are two methods typically used to extend an element: init(), which can be used to add custom initialization logic to your element, and loadDefaultDecorators(), which can be used to set a list of default decorators used by your element.

As an example, let's say that all text elements in a form you are creating need to be filtered with StringTrim, validated with a common regular expression, and that you want to use a custom decorator you've created for displaying them, 'My_Decorator_TextItem'; additionally, you have a number of standard attributes, including 'size', 'maxLength', and 'class' you wish to specify. You could define such an element as follows:

class My_Element_Text extends Zend_Form_Element
{
    public function init()
    {
        $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
             ->addFilters('StringTrim')
             ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
             ->addDecorator('TextItem')
             ->setAttrib('size', 30)
             ->setAttrib('maxLength', 45)
             ->setAttrib('class', 'text');
    }
}

        

You could then inform your form object about the prefix path for such elements, and start creating elements:

<?php
$form->addPrefixPath('My_Element', 'My/Element/', 'element')
     ->addElement('foo', 'text');

        

The 'foo' element will now be of type My_Element_Text, and exhibit the behaviour you've outlined.

Another method you may want to override when extending Zend_Form_Element is the loadDefaultDecorators() method. This method conditionally loads a set of default decorators for your element; you may wish to substitute your own decorators in your extending class:

class My_Element_Text extends Zend_Form_Element
{
    public function loadDefaultDecorators()
    {
        $this->addDecorator('ViewHelper')
             ->addDecorator('DisplayError')
             ->addDecorator('Label')
             ->addDecorator('HtmlTag',
                            array('tag' => 'div', 'class' => 'element'));
    }
}

        

There are many ways to customize elements; be sure to read the API documentation of Zend_Form_Element to know all the methods available.