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.

Użycie własnych klas filtrów

Jeśli posiadasz własny zestaw klas filtrów, możesz przekazać klasie Zend_Form_Element informacje o tym za pomocą metody addPrefixPath(). Na przykład jeśli posiadasz filtry z przedostkiem 'My_Filter' możesz przekazać do klasy Zend_Form_Element informację w taki sposób: $element->addPrefixPath('My_Filter', 'My/Filter/', 'filter'); (Zauważ że trzeci argument oznacza typ wtyczek dla którego określamy przedrostek)

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.

Użycie własnych klas weryfikatorów

Jeśli posiadasz własny zestaw klas weryfikatorów, możesz przekazać klasie Zend_Form_Element informacje o tym za pomocą metody addPrefixPath(). Na przykład jeśli posiadasz weryfikatory z przedostkiem 'My_Validator' możesz przekazać do klasy Zend_Form_Element informację w taki sposób: $element->addPrefixPath('My_Validator', 'My/Validator/', 'validate'); (Zauważ że trzeci argument oznacza typ wtyczek dla którego określamy przedrostek)

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);

        

Określanie własnych komunikatów o błędach

Some developers may wish to provide custom error messages for a validator. Zend_Form_Element::addValidator()'s $options argument allows you to do so by providing the key 'messages' and setting it to an array of key/value pairs for setting the message templates. You will need to know the error codes of the various validation error types for the particular validator. A better option is to use a Zend_Translate_Adapter with your form. Error codes are automatically passed to the adapter by the default Errors decorator; you can then specify your own error message strings by setting up translations for the various error codes of your validators.

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
}

        

	Weryfikowane są przefiltrowane wartości
	Zend_Form_Element::isValid() filtruje wartości za pomocą ustawionych filtrów zanim zostanie przeprowadzona weryfikacja. Zobacz rozdział Filtry aby uzyskać więcej informacji.

Weryfikacja w kontekście

Metoda Zend_Form_Element::isValid() obsługuje dodatkowy argument, $context. Metoda Zend_Form::isValid() podczas weryfikacji formularza przekazuje całą tablicę przetwarzanych danych do zmiennej $context, a metoda Zend_Form_Element::isValid() z kolei przekazuje ją do każdego weryfikatora. Oznacza to, że możesz stworzyć weryfikatory, które działają w oparciu o dane przekazane do innych elementów formularza. Przykładem może być standardowy formularz rejestracji, w którym są pola do wpisania hasła oraz do potwierdzenia hasła; powinno wtedy zostać zweryfikowane to, czy zawartość obu pól jest identyczna. Weryfikator mógłby wyglądać w taki sposób: 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; } }

Weryfikatory są uruchamiane w kolejności. Każdy weryfikator jest uruchamiany, chyba że weryfikator z ustawioną flagą breakChainOnFailure nie przejdzie pomyślnie weryfikacji. Upewnij się, że określisz swoje weryfikatory w określonej kolejności.

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.

	Użycie klasy Zend_Form_Elements jako weryfikatora
	Klasa Zend_Form_Element implementuje interfejs Zend_Validate_Interface, co oznacza, że element może być także użyty jako weryfikator, w zastosowaniu nie związanym z formularzami.

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:

	Domyślne dekoratory nie muszą być ładowane
	Domyślny zestaw dekoratorów jest ładowany podczas inicjowania obiektu. Możesz to zablokować określając opcję 'disableLoadDefaultDecorators' konstruktora: $element = new Zend_Form_Element('foo', array('disableLoadDefaultDecorators' => true) ); Ta opcja może być użyta równolegle wraz z dowolnymi innymi opcjami jakie przekażesz, zarówno w postaci tablicy opcji jak i obiektu Zend_Config.

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.

Użycie wielu dekoratorów tego samego typu

Internally, Zend_Form_Element uses a decorator's class as the lookup mechanism when retrieving decorators. As a result, you cannot register multiple decorators of the same type; subsequent decorators will simply overwrite those that existed before. To get around this, you can use aliases. Instead of passing a decorator or decorator name as the first argument to addDecorator(), pass an array with a single element, with the alias pointing to the decorator object or name: // Alias dla 'FooBar': $element->addDecorator(array('FooBar' => 'HtmlTag'), array('tag' => 'div')); // Pobieramy dekorator: $decorator = $element->getDecorator('FooBar'); Do metod addDecorators() oraz setDecorators() musisz przekazać opcję 'decorator' znajdującą się w tablicy reprezentującej dekorator. // 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:

Jako przykład poniżej zamieszczamy plik konfiguracyjny pokazujący wszystkie możliwe dane konfiguracyjne:

[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ć:

Dwie metody są najczęściej używane do rozszerzenia elementu: metoda init(), która może być użyta do dodania własnej logiki inicjującej element oraz metoda loadDefaultDecorators(), która może być użyta do ustawienia listy domyślnych dekoratorów używanych przez 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');

        

Element 'foo' będzie teraz typu My_Element_Text i będzie posiadał wyżej pokazaną funkcjonalność.

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'));
    }
}

        

Jest wiele sposobów na konfigurację elementów; pamiętaj aby przeczytać dokumentację API klasy Zend_Form_Element w celu poznania wszystkich dostępnych metod.