Previous Next

Creando elementos de formulario usando Zend_Form_Element

Un formulario esta compuesto de elementos, que normalmente corresponden al elemento HTML input. Zend_Form_Element encapsula elementos de formulario individualmente, con las siguientes áreas de responsabilidad:

  • validación (¿los datos enviados son válidos?)

    • captura de códigos y mensajes de error

  • filtrado (¿cómo es escapado y normalizado el elemento para su validación y/o salida?

  • generación (¿cómo es mostrado el elemento?)

  • metadatos y atributos (¿qué información amplía la definición del elemento?)

La clase base, Zend_Form_Element , funciona por defecto para varios casos, pero es mejor extender la clase para elementos con fines especiales de uso común. Adicionalmente, Zend Framework contiene un número de elementos XHTML estándar; puede leer de ellos en el capítulo Elementos Estándares

Cargadores de Plugin

Zend_Form_Element hace uso de Zend_Loader_PluginLoader para permitir a los desarrolladores especificar ubicaciones de validadores, filtros y decoradores alternos. Cada uno tiene su propio cargador de plugin asociado a él y métodos de acceso generales usados para su recuperación y modificación.

Los siguientes tipos de cargadores son usados con los varios métodos del cargador de plugin: 'validate', 'filter', y 'decorator'. Los nombres son sensibles a mayúsculas y minúsculas.

Los métodos usados para interactuar con los cargadores de plugin son los siguientes:

  • setPluginLoader($loader, $type) : $loader es el propio objeto cargador, mientras es uno de los tipos arriba mencionados. Esto establece el cargador de plugin para el tipo dado en el objeto cargador recién especificado.

  • getPluginLoader() : obtiene el cargador de plugin asociado con .

  • addPrefixPath($prefix, $path, $type = null) : agrega una asociación prefijo/ruta para el cargador especificado por $type . Si $type es NULL, se intentará agregar la ruta a todos los cargadores, añadiendo el prefijo a cada "_Validate", "_Filter" y "_Decorator"; y agregandole "Validate/", "Filter/" y "Decorator/" a la ruta. Si tiene todas sus clases extras para elementos de formulario dentro de una jerarquía común, este método es conveniente para establecer el prefijo para todas ellas.

  • addPrefixPaths(array $spec) : le permite añadir varias rutas de una sola vez a uno o más cargadores de plugin. Se espera cada elemento de la matriz sea un array con claves 'path', 'prefix', y 'type'.

Validadores, filtros y decoradores personalizados son una manera simple de compartir funcionalidad entre formularios y encapsular funcionalidad personalizada.

Ejemplo #1 Etiqueta personalizada

Un uso común de los plugins es proveer reemplazos para las clases estándares. Por ejemplo, si desea proveer una implementación diferente del decorador 'Label' -- por ejemplo, para añadir siempre dos puntos -- puede crear su propio decorador 'Label' con su propio prefijo de clase, y entonces añadirlo a su prefijo de ruta.

Comencemos con un decorador de etiqueta personalizado. Le daremos el prefijo "My_Decorator", y la clase estará en el archivo "My/Decorator/Label.php".

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

Ahora diremos al elemento que use esta ruta cuando busque por decoradores:

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

Alternativamente, podemos hacerlo en el formulario para asegurar que todos los decoradores usen esta ruta:

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

Con esta ruta añadida, cuando agregue un decorador, la ruta 'My/Decorator' será consultada primero en búsqueda de la existencia del decorador en este lugar. Como resultado, 'My_Decorator_Label' ahora será utilizado cuando el decorador 'Label' sea requerido.

Filters

A menudo es útil y/o necesario realizar alguna normalización en la entrada antes de la validación – por ejemplo, puede querer eliminar todo el HTML , pero realizar las validaciones sobre lo restante para asegurarse que el envío es válido. O puede eliminar los espacios en blanco al inicio o fin de la entrada para asegurarse de que un validador StringLenth (longitud de la cadena) no regrese un positivo falso. Estas operaciones pueden realizarse usando Zend_Filter , y Zend_Form_Element que soportan cadenas de filtros, permitiéndole especificar múltiples filtros secuenciales a utilizar. El filtrado sucede tanto en la validación como cuando recupera el valor del elemento vía getValue() :

$filtered = $element->getValue();

Los filtros pueden ser agregados a la pila de dos maneras:

  • pasándolo en una instancia de filtro específica

  • proveyendo un nombre de filtro – el correspondiente nombre corto o completo de la clase

Veamos algunos ejemplos:

// Instancia específica del filtro
$element->addFilter(new Zend_Filter_Alnum());

// El correspondiente nombre completo de la clase:
$element->addFilter('Zend_Filter_Alnum');

// Nombre corto del filtro:
$element->addFilter('Alnum');
$element->addFilter('alnum');

Los nombres cortos son típicamente el nombre del filtro sin el prefijo. En el caso predeterminado, esto se refiere a sin el prefijo 'Zend_Filter_'. Además, la primera letra no necesita estar en mayúscula.

Nota: Usando clases de filtros personalizados

Si tiene su propio conjunto de clases de filtro, puede informarle de ellas a Zend_Form_Element usando addPrefixPath() . Por ejemplo, si tiene filtros con el prefijo 'My_Filter', puede indicárselo a Zend_Form_Element de la siguiente manera:

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

(Recuerde que el tercer argumento indica el cargador de plugin sobre el cual ha de ejecutarse la acción.)

Si en algún momento necesita un valor no filtrado, use el método getUnfilteredValue() :

$unfiltered = $element->getUnfilteredValue();

Para mayor información sobre filtros, vea la documentación de Zend_Filter .

Métodos asociados con filtros incluyen:

  • addFilter($nameOfFilter, array $options = null)

  • addFilters(array $filters)

  • setFilters(array $filters) (sobreescribe todos los filtros)

  • getFilter($name) (recupera un objeto filtro por su nombre)

  • getFilters() (recupera todos los filtros)

  • removeFilter($name) (elimina un filtro por su nombre)

  • clearFilters() (elimina todos los filtros)

Validadores

Si sigue el mantra de seguridad "filtrar la entrada, escapar la salida" querrá validar ("filtrar la entrada") los datos de los formularios. En Zend_Form cada elemento contiene su propia cadena de validadores, consistente en validadores Zend_Validate_* .

Los validadores pueden ser agregados de dos maneras:

  • pasándolo en una instancia de validador específica

  • proveyendo un nombre de validador – el correspondiente nombre corto o completo de clase

Veamos algunos ejemplos:

// Instancia específica del validador:
$element->addValidator(new Zend_Validate_Alnum());

// El correspondiente nombre completo de la clase:
$element->addValidator('Zend_Validate_Alnum');

// Nombre corto del validador:
$element->addValidator('Alnum');
$element->addValidator('alnum');

Los nombres cortos son típicamente el nombre del validador sin el prefijo. En el caso predeterminado, esto se refiere a sin el prefijo 'Zend_Validate_'. Además, la primera letra no necesita estar en mayúscula.

Nota: Usando clases de validación personalizadas

Si tiene su propio conjunto de clases de validación, puede informarle de ellas a Zend_Form_Element usando addPrefixPath() . Por ejemplo, si tiene validadores con el prefijo 'My_Validator', puede indicárselo a Zend_Form_Element de la siguiente manera:

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

(Recuerde que el tercer argumento indica el cargador de plugin sobre el cual ha de ejecutarse la acción.)

Si el fallo de un validador debe evitar validaciones posteriores, pase el boleano TRUE como segundo parámetro:

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

Si está usando la cadena nombre para añadir el validador, y la clase del validador acepta argumentos para su constructor, puede pasarlos a el tercer parámetro de addValidator() como un array:

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

Los argumentos pasados de esta manera deben estar en el orden en el cual son definidos en el constructor. El ejemplo de arriba instanciará la clase Zend_Validate_StringLenth con los parámetros $min y $max :

$validator = new Zend_Validate_StringLength(6, 20);

Nota: Estipulando mensajes de error de validación personalizados

Algunos desarrolladores querrán estipular mensajes de error personalizados para un validador. El argumento $options de Zend_Form_Element::addValidator() le permite hacerlo proporcionando la clave 'messages' y estableciendolos en un array de pares clave/valor para especificar las plantillas de mensaje. Necesitará conocer los códigos de error de los diferentes tipos de error de un validador en particular.

Una opción mejor es usar Zend_Translate_Adapter con su formulario. Los códigos de error son automáticamente pasados al adaptador por el decorador Errors por defecto; puede especificar su propias cadenas de mensaje de error mediante la creación de traducciones para los varios códigos de error de sus validadores.

Puede también establecer varios validadores a la vez, usando addValidators() . Su uso básico es pasar una matriz de arrays, donde cada array contenga de 1 a 3 valores, correspondientes al constructor de addValidator() :

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

Si quiere ser más detallado o explícito, puede utilizar las claves 'validator', 'breakChainOnFailure', y 'options' en el array:

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

Este uso es bueno para ilustrar cómo puede configurar validadores en un archivo de configuración:

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

Note que cada elemento tiene una clave, la necesite o no; esta es una limitación del uso de archivos de configuración -- pero también ayuda a hacer más explicito el para qué son usados los argumentos. Sólo recuerde que cualesquiera opciones del validador deben ser especificadas en orden.

Para validar un elemento, pase el valor a isValid() :

if ($element->isValid($value)) {
    // válido
} else {
    // no válido
}

Nota: Validación operando en valores filtrados

Zend_Form_Element::isValid() > siempre filtra los valores antes de la validación a través de la cadena de filtros. Vea la sección de filtros para más información.

Nota: Contexto de validación

Zend_Form_Element::isValid() > soporta un argumento adicional, $context . Zend_Form::isValid() pasa todo el conjunto de datos procesados a $context cuando valida un formulario, y Zend_Form_Element::isValid() >, a su vez, lo pasa a cada validador. Esto significa que puede escribir validadores que son conscientes de los datos pasados a otros elementos del formulario. Como ejemplo, considere un formulario de registro estándar que tiene campos para la contraseña y la confirmación de la contraseña; una validación sería que los dos campos coincidan. Este validador puede tener un aspecto como el siguiente:

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

Los validadores son procesados en orden. Cada validador es procesado, a menos que un validador creado con un valor true para breakChainOnFailure falle su validación. Asegúrese de especificar sus validadores en un orden razonable.

Después de una validación fallida, puede recuperar los códigos y mensajes de error de la cadena del validador:

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

(Nota: los mensajes de error retornados son un array asociativo de pares código / mensaje de error.)

En adición a los validadores, puede especificar que un elemento es necesario, usando setRequired(true) . Por defecto, esta bandera es FALSE , lo que significa que pasará su cadena de validadores si ningún valor es pasado a isValid() . Puede modificar este comportamiento en un número de maneras:

  • Por defecto, cuando un elemento es requerido, una bandera, 'allowEmpty', también es true. Esto quiere decir que si un valor empty es evaluado pasándolo a isValid() , los validadores serán saltados. Puede intercalar esta bandera usando el método de acceso setAllowEmpty($flag) ; cuando la bandera es false, si un valor es pasado, los validadores seguirán ejecutándose.

  • Por defecto, si un elemento es requerido, pero no contiene un validador 'NotEmpty', isValid() añadirá uno en la cima de la pila, con la bandera breakChainOnFailure establecido. Esto hace que la bandera requerida tenga un significado semántico: si ningún valor es pasado, inmediatamente invalidamos el envío y se le notifica al usuario, e impedimos que otros validadores se ejecuten en lo que ya sabemos son datos inválidos.

    Si no quiere este comportamiento, puede desactivarlo pasando un valor false a setAutoInsertNotEmptyValidator($flag) ; esto prevendrá a isValid() de colocar un validador 'NotEmpty' en la cadena de validaciones.

Para mayor información sobre validadores, vea la documentación de Zend_Validate .

Nota: Usando Zend_Form_Elements como validador de propósito general

Zend_Form_Element implementa Zend_Validate_Interface , significando un elemento puede también usarse como un validador en otro, cadenas de validación no relacionadas al formulario.

Métodos asociados con validación incluyen:

  • setRequired($flag) y isRequired() permiten establecer y recuperar el estado de la bandera 'required'. Cuando se le asigna un booleano TRUE , esta bandera requiere que el elemento esté presente en la información procesada por Zend_Form .

  • setAllowEmpty($flag) y getAllowEmpty() permiten modificar el comportamiento de elementos opcionales (p.e., elementos donde la bandera required es FALSE). Cuando la bandera 'allow empty' es TRUE , valores vacíos no pasarán la cadena de validadores.

  • setAutoInsertNotEmptyValidator($flag) permite especificar si realmente un validador 'NotEmpty' será añadido el inicio de la cadena de validaciones cuando un elemento es requerido. Por defecto, esta bandera es TRUE .

  • addValidator($nameOrValidator, $breakChainOnFailure = false, array $options = null)

  • addValidators(array $validators)

  • setValidators(array $validators) (sobreescribe todos los validadores)

  • getValidator($name) (recupera un objeto validador por nombre)

  • getValidators() (recupera todos los validadores)

  • removeValidator($name) (elimina un validador por nombre)

  • clearValidators() (elimina todos los validadores)

Errores de mensaje personalizados

Alguna veces, querrá especificar uno o más mensajes de error para usarlos en lugar de los mensajes de error generados por los validadores adjuntos a los elementos. Adicionalmente, algunas veces usted mismo querrá marcar al elemento como inválido. A partir de 1.6.0, esta funcionalidad es posible vía los siguientes métodos.

  • addErrorMessage($message) : añade un mensaje de error para mostrarlos en forma de errores de validación. Puede llamarlo más de una vez, y los nuevos mensajes nuevos son añadidos a la pila.

  • addErrorMessages(array $messages) : añade múltiples mensajes de error para mostrarlos en forma de errores de validación.

  • setErrorMessages(array $messages) : añade múltiples mensajes de error para mostrarlos en forma de errores de validación, sobreescribiendo todos los mensajes de error previamente establecidos.

  • getErrorMessages() : recupera la lista de mensajes de error personalizados que fueron definidos.

  • clearErrorMessages() : remueve todos los mensajes de error personalizados que hayan sido definidos.

  • markAsError() : marca al elemento como que falló la validación.

  • hasErrors() : determina si el elemento ha fallado la validación o ha sido marcado como inválido.

  • addError($message) : añade un mensaje a la pila de mensaje de error personalizados y marca al elemento como inválido.

  • addErrors(array $messages) : añade varios mensajes a la pila de mensajes de error personalizados y marca al elemento como inválido.

  • setErrors(array $messages) : sobreescribe el mensaje de error personalizado en la pila con los mensajes previstos y marca al elemento como inválido.

Todos los errores establecidos de este modo pueden ser traducidos. Adicionalmente, puede insertar el marcador "%value%" para representar el valor del elemento; este valor actual del elemento será sustituido cuando el mensaje de error sea recuperado.

Decoradores

Una dolencia particular para muchos desarrolladores web es la creación del XHTML para formularios por ellos mismos. Para cada elemento, el desarrollador necesita crear la marcación para el elemento mismo, comúnmente una etiqueta (label), y, si son amables con sus usuarios, la marcación para mostrar mensajes de errores de validación. Cuanto más elementos en una página, menos trivial se convierte esta tarea.

Zend_Form_Element intenta resolver este problema mediante el uso de "decoradores". Los decoradores son clases simples que tienen métodos de acceso al elemento y métodos para generar el contenido. Para obtener mayor información sobre cómo trabajan los decoradores, consulte por favor la sección sobre Zend_Form_Decorator .

Los decoradores usados por defecto por Zend_Form_Element son:

  • ViewHelper : especifica un view helper que usar para general el elemento. El atributo 'helper' del elemento puede usarse para especificar qué auxiliar vista usar. Por defecto, Zend_Form_Element especifica el auxiliar vista 'formText', pero cada subclase especifica diferentes auxiliares.

  • Errors : añade mensajes de error al elemento usando Zend_View_Helper_FormErrors . Si no está presente, no se añade nada.

  • Description: añade la descripción del elemento. Si no está presente, no se añade nada. Por defecto, la descripción es generada dentro de una etiqueta <p> con un class 'description'.

  • HtmlTag: envuelve el elemento y los errores en una etiqueta HTML <dd>.

  • Label : añade al comienzo una etiqueta al elemento usando Zend_View_Helper_FormLabel, y envolviéndola en una etiqueta <dt>. Si ninguna etiqueta es provista, solo la etiqueta de la definición es generada.

Nota: Decoradores por defecto no necesitan ser cargados

Por defecto, los decoradores por defecto son cargados durante la inicialización del objeto. Puede deshabilitar esto pasando la opción 'disableLoadDefaultDecorators' al constructor:

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

Esta opción puede ser combinada junto con cualquier otra opción que pase, ya sea como un array de opciones o en un objeto Zend_Config .

Ya que el orden en el cual los decoradores son registrados importa -- el primer decorador registrado es ejecutado primero -- necesitará estar seguro de registrar sus decoradores en el orden apropiado, o asegurarse de que estableció las opciones de colocación en el modo apropiado. Por dar un ejemplo, aquí esta el código que registran los decoradores por defecto:

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

El contenido inicial es creado por el decorador 'ViewHelper', que crea el propio elemento. En seguida, el decorador 'Errors' consulta los mensajes de error del elemento, y, si hay alguno presente, los pasa al auxiliar vista 'FormErrors' para mostrarlos. Si una descripción está presente, el decorador 'Description' añadirá un párrafo con class 'description' conteniendo el texto descriptivo para el contenido agregado. El siguiente decorador, 'HtmlTag', envuelve al elemento, los errores, y la descripción en una etiqueta HTML <dd>. Finalmente, el último decorador, 'label', recupera la etiqueta del elemento y la pasa al auxiliar vista 'FormLabel', envolviéndolo en una etiqueta <dt>; por default el valor es añadido al inicio del contenido. El resultado de la salida básicamente se ve así:

  • "123" is not an alphanumeric value

This is some descriptive text regarding the element.

Para más información sobre decoradores, lea la sección de Zend_Form_Decorator .

Nota: Usando múltiples decoradores al mismo tiempo

Internamente, Zend_Form_Element utiliza una clase decorador como mecanismo de búsqueda para la recuperación de decoradores. Como resultado, no puede registrar múltiples decoradores del mismo tipo; decoradores subsecuentes simplemente sobreescribirán aquellos que ya existían.

Para evitar esto, puede usar alias . En lugar de pasar un decorador o nombre de decorador como primer argumento a addDecorator() , pase una matriz con un solo elemento, con el alias apuntando al nombre o objeto decorador:

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

// Y recuperandolo posteriormente:
$decorator = $element->getDecorator('FooBar');

En los métodos addDecorators() y setDecorators() , necesitará pasar la opción 'decorator' en la matriz representando el decorador:

// Y dos decoradores 'HtmlTag', 'FooBar' como alias:
$element->addDecorators(
    array('HtmlTag', array('tag' => 'div')),
    array(
        'decorator' => array('FooBar' => 'HtmlTag'),
        'options' => array('tag' => 'dd')
    ),
);

// Y recuperándolos posteriormente:
$htmlTag = $element->getDecorator('HtmlTag');
$fooBar  = $element->getDecorator('FooBar');

Métodos asociados con decoradores incluyen:

  • addDecorator($nameOrDecorator, array $options = null)

  • addDecorators(array $decorators)

  • setDecorators(array $decorators) (sobreescribe todos los decoradores)

  • getDecorator($name) (recupera un objeto decorador por su nombre)

  • getDecorators() (recupera todos los decoradores)

  • removeDecorator($name) (elimina un decorador por su nombre)

  • clearDecorators() (elimina todos los decoradores)

Zend_Form_Element también utiliza la sobrecarga para permitir generar decoradores específicos. __call() interceptará métodos que comiencen con el texto 'render' y utilizará el resto del nombre del método para buscar un decorador; si se encuentra, entonces será generado sólo ese decorador. Cualquier argumento pasado al llamado del método será usado como contenido para pasar al método render() del decorador. Como ejemplo:

// Genera solo el decorador ViewHelper:
echo $element->renderViewHelper();

// Genera solo el decorador HtmlTag, pasándole contenido:
echo $element->renderHtmlTag("This is the html tag content");

Si el decorador no existe, una excepción es lanzada.

Metadatos y atributos

Zend_Form_Element manipula una variedad de atributos y medatados del elemento. Atributos básicos incluyen:

  • name : el nombre del elemento. Emplea los métodos de acceso setName() y getName() .

  • label : la etiqueta del elemento. Emplea los métodos de acceso setLabel() y getLabel() .

  • order : el índice en el cual los elementos deben ir mostrándose en el formulario. Emplea los métodos de acceso setOrder() y getOrder() .

  • value : El valor del elemento actual. Emplea los métodos de acceso setValue() y getValue() .

  • description : una descripción del elemento; a menudo utilizada para proveer un tooltip o ayuda contextual con javascript describiendo el propósito del elemento. Emplea los métodos de acceso setDescription() y getDescription() .

  • required : bandera que indica si un elemento es requerido o no cuando se efectúa la validación del formulario. Emplea los métodos de acceso setRequired() y getRequired() . Esta bandera es FALSE por defecto.

  • allowEmpty : bandera indicando si un elemento no-requerido (opcional) debe intentar validar o no valores vacíos. Cuando es TRUE , y la bandera required es FALSE , valores vacíos no pasarán la cadena de validación, y se supone verdadero. Emplea los métodos de acceso setAllowEmpty() y getAllowEmpty() . Esta bandera es TRUE por defecto.

  • autoInsertNotEmptyValidator : bandera indicando insertar o no un validador 'NotEmpty' cuando un elemento es requerido. Por defecto, esta bandera es TRUE . Establezca la bandera con setAutoInsertNotEmptyValidator($flag) y determine el valor con autoInsertNotEmptyValidator() .

Los elementos del formulario pueden requerir metainformación adicional. Para elementos XHTML del formuladio, por ejemplo, puede querer especificar atributos como el class o id. Para facilitar esto hay un conjunto de métodos de acceso:

  • setAttrib($name, $value) : añade un atributo

  • setAttribs(array $attribs) : como addAttribs(), pero sobreescribiendo

  • getAttrib($name) : recupera el valor de solo un atributo

  • getAttribs() : recupera todos los atributos como pares clave/valor

La mayoría de las veces, como sea, puede simplemente acceder a ellos como propiedades de objeto, ya que Zend_Form_Element utiliza la sobrecarga para facilitar el acceso a ellos:

// Equivalente a $element->setAttrib('class', 'text'):
$element->class = 'text;

Por defecto, todos los atributos son pasados al auxiliar vista usado por el elemento durante la generación, y generados como atributos de la etiqueta del elemento.

Elementos Estándar

Zend_Form contiene un buen número de elementos estándar; por favor lea el capítulo Elementos Estándar para todos los detalles.

Métodos de Zend_Form_Element

Zend_Form_Element tiene muchos, muchos métodos. Lo que sigue es un sumario de sus funciones, agrupados por tipo:

  • Configuración:

    • setOptions(array $options)

    • setConfig(Zend_Config $config)

  • I18n:

    • setTranslator(Zend_Translate_Adapter $translator = null)

    • getTranslator()

    • setDisableTranslator($flag)

    • translatorIsDisabled()

  • Propiedades:

    • setName($name)

    • getName()

    • setValue($value)

    • getValue()

    • getUnfilteredValue()

    • setLabel($label)

    • getLabel()

    • setDescription($description)

    • getDescription()

    • setOrder($order)

    • getOrder()

    • setRequired($flag)

    • getRequired()

    • setAllowEmpty($flag)

    • getAllowEmpty()

    • setAutoInsertNotEmptyValidator($flag)

    • autoInsertNotEmptyValidator()

    • setIgnore($flag)

    • getIgnore()

    • getType()

    • setAttrib($name, $value)

    • setAttribs(array $attribs)

    • getAttrib($name)

    • getAttribs()

  • Cargadores y rutas de plugin:

    • setPluginLoader(Zend_Loader_PluginLoader_Interface $loader, $type)

    • getPluginLoader($type)

    • addPrefixPath($prefix, $path, $type = null)

    • addPrefixPaths(array $spec)

  • Validación:

    • addValidator($validator, $breakChainOnFailure = false, $options = array())

    • addValidators(array $validators)

    • setValidators(array $validators)

    • getValidator($name)

    • getValidators()

    • removeValidator($name)

    • clearValidators()

    • isValid($value, $context = null)

    • getErrors()

    • getMessages()

  • Filtros:

    • addFilter($filter, $options = array())

    • addFilters(array $filters)

    • setFilters(array $filters)

    • getFilter($name)

    • getFilters()

    • removeFilter($name)

    • clearFilters()

  • Generación:

    • setView(Zend_View_Interface $view = null)

    • getView()

    • addDecorator($decorator, $options = null)

    • addDecorators(array $decorators)

    • setDecorators(array $decorators)

    • getDecorator($name)

    • getDecorators()

    • removeDecorator($name)

    • clearDecorators()

    • render(Zend_View_Interface $view = null)

Configuración

El constructor de Zend_Form_Element acepta tanto una matriz de opciones como un objeto Zend_Config conteniendo opciones, y esto puede configurarse usando setOptions() o setConfig() . Hablando de manera general, las claves son nombradas de la siguiente manera:

  • Si 'set' + clave se refiere a un método de Zend_Form_Element , entonces el valor provisto será pasado a el método.

  • De otra manera, el valor será usado para establecer un atributo.

Excepciones a la regla incluyen las siguientes:

  • prefixPath será pasado a addPrefixPaths()

  • Los siguientes setters no pueden establecerse de esta manera:

    • setAttrib (aunque setAttribs funcionará

    • setConfig

    • setOptions

    • setPluginLoader

    • setTranslator

    • setView

Como ejemplo, aquí esta un archivo de configuración pasado para cada tipo de dato configurable:

[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"
; sets 'onclick' attribute
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"

Elementos personalizados

Usted puede crear sus propios elementos personalizados simplemente extendiendo la clase Zend_Form_Element . Las razones comunes para hacer esto incluyen:

  • Elementos que comparten validadores y/o filtros comunes

  • Elementos que tienen decoradores con funcionalidad personalizada

Hay dos métodos típicamente usados para extender un elemento: init() , el cual puede usarse para añadir una lógica de inicialización personalizada a su elemento, y loadDefaultDecorators() , el cual puede usarse para establecer una lista de decoradores usados por su elemento de manera predeterminada.

Como un ejemplo, digamos que todos los elementos de tipo texto en un formulario que está creando, necesitan ser filtrados con StringTrim , validados con una expresión regular, y que quiere usar un decorador personalizado que ha creado para mostrarlos, 'My_Decorator_TextItem'; adicionalmente, tiene un número de atributos estándars, incluyendo 'size', 'maxLength', y 'class' que quisiera especificar. Puede definir un elemento tal como sigue:

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

Entonces puede informar a su objeto formulario acerca del prefijo de ruta para elementos de ese tipo, y comenzar creando elementos:

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

El elemento 'foo' será ahora del tipo My_Element_Text , y mostrará el comportamiento que ha especificado.

Otro método que puede querer sobreescribir cuando extienda Zend_Form_Element es el método loadDefaultDecorators() . Este método carga condicionalmente un grupo de decoradores predefinidos para su elemento; puede querer sustituir su propio decorador en su clase extendida:

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

Hay muchas maneras de personalizar elementos; asegúrese de leer la documentación de la API de Zend_Form_Element para conocer todos los métodos disponibles.

Previous Next
Introducción a Zend Framework
Descripción general
Instalación
Aprendiendo Zend Framework
Inicio Rápido con Zend Framework
Zend Framework & MVC Introduction
Create Your Project
Create A Layout
Create a Model and Database Table
Create A Form
Congratulations!
Autocarga o Carga automática en Zend Framework
Introduction
Goals and Design
Basic Autoloader Usage
Resource Autoloading
Conclusion
Plugins en Zend Framework
Introduction
Using Plugins
Conclusion
Primeros pasos con Zend_Layout
Introduction
Using Zend_Layout
Zend_Layout: Conclusions
Introducción a Zend_View Placeholders
Introduction
Basic Placeholder Usage
Standard Placeholders
View Placeholders: Conclusion
Comprensión y uso de Zend Form Decorators
Introduction
Decorator Basics
Layering Decorators
Rendering Individual Decorators
Creating and Rendering Composite Elements
Conclusion
Primeros pasos con Zend_Session, Zend_Auth, and Zend_Acl
Building Multi-User Applications With Zend Framework
Managing User Sessions In ZF
Authenticating Users in Zend Framework
Building an Authorization System in Zend Framework
Primeros pasos con Zend_Search_Lucene
Zend_Search_Lucene Introduction
Lucene Index Structure
Index Opening and Creation
Indexing
Searching
Supported queries
Search result pagination
Primeros pasos con Zend_Paginator
Introduction
Simple Examples
Pagination Control and ScrollingStyles
Putting it all Together
Referencia de Zend Framework
Zend_Acl
Introducción
Perfeccionamiento de los controles de acceso
Uso Avanzado
Zend_Amf
Introducción
Zend_Amf_Server
Zend_Application
Introducción
Inicio rápido con Zend_Application
Teoría de Operación
Ejemplos
Funcionalidad Básica
Plugins de Recursos Disponibles
Zend_Auth
Introducción
Tabla de base de datos de autenticación
Autenticación "Digest"
Adaptador de Autenticación HTTP
LDAP Authentication
Autenticación con Open ID
Zend_Barcode
Introduction
Barcode creation using Zend_Barcode class
Zend_Barcode Objects
Zend_Barcode Renderers
Zend_Cache
Introducción
The Theory of Caching
Zend_Cache Frontends
Zend_Cache Backends
The Cache Manager
Zend_Captcha
Introducción
Captcha Operation
CAPTCHA Adapters
Zend_CodeGenerator
Introducción
Ejemplos de Zend_CodeGenerator
Referencias de Zend_CodeGenerator
Zend_Config
Introducción
Aspectos Teóricos
Zend_Config_Ini
Zend_Config_Xml
Zend_Config_Writer
Zend_Config_Writer
Zend_Console_Getopt
Introduction
Declaring Getopt Rules
Fetching Options and Arguments
Configuring Zend_Console_Getopt
Zend_Controller
Inicio rápido a Zend_Controller
Conceptos Básicos de Zend_Controller
El Front Controller
La solicitud del Objeto
El Router Standard
El Despachador
Controladores de Acción
Action Helpers
The Response Object
Plugins
Using a Conventional Modular Directory Structure
Excepciones MVC
Zend_Currency
Introduction to Zend_Currency
Using Zend_Currency
Options for currencies
What makes a currency?
Where is the currency?
How does the currency look like?
How much is my currency?
Calculating with currencies
Exchanging currencies
Additional informations on Zend_Currency
Zend_Date
Introducción
Theory of Operation
Basic Methods
Zend_Date API Overview
Creation of Dates
Constants for General Date Functions
Working Examples
Zend_Db
Zend_Db_Adapter
Zend_Db_Statement
Zend_Db_Profiler
Zend_Db_Select
Zend_Db_Table
Zend_Db_Table_Row
Zend_Db_Table_Rowset
Zend_Db_Table Relationships
Zend_Db_Table_Definition
Zend_Debug
Mostrar información de variables(Dumping Variables)
Zend_Dojo
Introducción
Zend_Dojo_Data: Envolturas de dojo.data
Ayudantes de Dojo View
Elementos y Decoradores de Dojo Form
Zend_Dojo build layer support
Zend_Dom
Introducción
Zend_Dom_Query
Zend_Exception
Uso de Excepciones
Basic usage
Previous Exceptions
Zend_Feed
Introduction
Importing Feeds
Retrieving Feeds from Web Pages
Consuming an RSS Feed
Consuming an Atom Feed
Consuming a Single Atom Entry
Modifying Feed and Entry structures
Custom Feed and Entry Classes
Zend_Feed_Reader
Zend_Feed_Writer
Zend_Feed_Pubsubhubbub
Zend_File
Zend_File_Transfer
Validators for Zend_File_Transfer
Filters for Zend_File_Transfer
Zend_Filter
Introducción
Standard Filter Classes
Filter Chains
Writing Filters
Zend_Filter_Input
Zend_Filter_Inflector
Zend_Form
Zend_Form
Inicio rápido a Zend_Form
Creando elementos de formulario usando Zend_Form_Element
Creando formularios usando Zend_Form
Creando un personalizado marcado de formulario usando Zend_Form_Decorator
Elementos Enviados en el Formulario Estandard de Zend Framework
Decoradores de Formulario (Form Decorartors) estándar contenidos en Zend Framework
Internacionalización de Zend_Form
Uso avanzado de Zend_Form
Zend_Gdata
Introduction
Authenticating with AuthSub
Using the Book Search Data API
Authenticating with ClientLogin
Using Google Calendar
Using Google Documents List Data API
Using Google Health
Using Google Spreadsheets
Using Google Apps Provisioning
Using Google Base
Using Picasa Web Albums
Using the YouTube Data API
Catching Gdata Exceptions
Zend_Http
Introduction
Zend_Http_Client - Advanced Usage
Zend_Http_Client - Connection Adapters
Zend_Http_Cookie and Zend_Http_CookieJar
Zend_Http_Response
Zend_InfoCard
Introduction
Zend_Json
Introducción
Uso Básico
Uso Avanzado de Zend_Json
Conversión de XML a JSON
Zend_Json_Server - servidor JSON-RPC
Zend_Layout
Introducción
Zend_Layout Quick Start
Zend_Layout Configuration Options
Zend_Layout Advanced Usage
Zend_Ldap
Introduction
API overview
Usage Scenarios
Tools
Object oriented access to the LDAP tree using Zend_Ldap_Node
Getting information from the LDAP server
Serializing LDAP data to and from LDIF
Zend_Loader
Cargando archivos y clases dinámicamente
The Autoloader
Resource Autoloaders
Loading Plugins
Zend_Locale
Introduction
Using Zend_Locale
Normalization and Localization
Working with Dates and Times
Supported locales
Zend_Log
Overview
Writers
Formatters
Filters
Using the Factory to Create a Log
Zend_Mail
Introduction
Sending via SMTP
Sending Multiple Mails per SMTP Connection
Using Different Transports
HTML E-Mail
Attachments
Adding Recipients
Controlling the MIME Boundary
Additional Headers
Character Sets
Encoding
SMTP Authentication
Securing SMTP Transport
Reading Mail Messages
Zend_Markup
Introduction
Getting Started With Zend_Markup
Zend_Markup Parsers
Zend_Markup Renderers
Zend_Measure
Introduction
Creation of Measurements
Outputting measurements
Manipulating Measurements
Types of measurements
Zend_Memory
Overview
Memory Manager
Memory Objects
Zend_Mime
Zend_Mime
Zend_Mime_Message
Zend_Mime_Part
Zend_Navigation
Introduction
Pages
Containers
Zend_Oauth
Introduction to OAuth
Zend_OpenId
Introduction
Zend_OpenId_Consumer Basics
Zend_OpenId_Provider
Zend_Paginator
Introduction
Usage
Configuration
Advanced usage
Zend_Pdf
Introducción
Creando y Cargando Documentos PDF
Guardar Cambios a Documentos PDF
Trabajando con Páginas
Dibujo
Interactive Features
Información del Documento y Metadatos
Ejemplo de Uso del módulo Zend_Pdf
Zend_ProgressBar
Zend_ProgressBar
Zend_Queue
Introduction
Example usage
Framework
Adapters
Customizing Zend_Queue
Stomp
Zend_Reflection
Introduction
Zend_Reflection Examples
Zend_Reflection Reference
Zend_Registry
Using the Registry
Zend_Rest
Introduction
Zend_Rest_Client
Zend_Rest_Server
Zend_Search_Lucene
Overview
Building Indexes
Searching an Index
Query Language
Query Construction API
Character Set
Extensibility
Interoperating with Java Lucene
Advanced
Best Practices
Zend_Serializer
Introduction
Zend_Serializer_Adapter
Zend_Server
Introduction
Zend_Server_Reflection
Zend_Service
Introduction
Zend_Service_Akismet
Zend_Service_Amazon
Zend_Service_Amazon_Ec2
Zend_Service_Amazon_Ec2: Instances
Zend_Service_Amazon_Ec2: Windows Instances
Zend_Service_Amazon_Ec2: Reserved Instances
Zend_Service_Amazon_Ec2: CloudWatch Monitoring
Zend_Service_Amazon_Ec2: Amazon Machine Images (AMI)
Zend_Service_Amazon_Ec2: Elastic Block Storage (EBS)
Zend_Service_Amazon_Ec2: Elastic IP Addresses
Zend_Service_Amazon_Ec2: Keypairs
Zend_Service_Amazon_Ec2: Regions and Availability Zones
Zend_Service_Amazon_Ec2: Security Groups
Zend_Service_Amazon_S3
Zend_Service_Amazon_Sqs
Zend_Service_Audioscrobbler
Zend_Service_Delicious
Zend_Service_DeveloperGarden
Zend_Service_Flickr
Zend_Service_LiveDocx
Zend_Service_Nirvanix
Zend_Service_ReCaptcha
Zend_Service_Simpy
Zend_Service_SlideShare
Zend_Service_StrikeIron
Zend_Service_StrikeIron: Bundled Services
Zend_Service_StrikeIron: Advanced Uses
Zend_Service_Technorati
Zend_Service_Twitter
Zend_Service_WindowsAzure
Zend_Service_Yahoo
Zend_Session
Introduction
Basic Usage
Advanced Usage
Global Session Management
Zend_Session_SaveHandler_DbTable
Zend_Soap
Zend_Soap_Server
Zend_Soap_Client
WSDL Accessor
AutoDiscovery
Zend_Tag
Introduction
Zend_Tag_Cloud
Zend_Test
Introducción
Zend_Test_PHPUnit
Zend_Test_PHPUnit_Db
Zend_Text
Zend_Text_Figlet
Zend_Text_Table
Zend_TimeSync
Introduction
Working with Zend_TimeSync
Zend_Tool
Using Zend_Tool On The Command Line
Extending Zend_Tool
Zend_Tool_Framework
Introduction
Usando la herramienta CLI
Architecture
Creando Proveedores para usar con Zend_Tool_Framework
Shipped System Providers
Extending and Configuring Zend_Tool_Framework
Zend_Tool_Project
Introduction
Create A Project
Zend_Tool Project Providers
Zend_Tool_Project Internos
Zend_Translate
Introduction
Adapters for Zend_Translate
Using Translation Adapters
Creating source files
Additional features for translation
Plural notations for Translation
Zend_Uri
Zend_Uri
Zend_Validate
Introducción
Clases de Validación Estándar
Cadenas de Validadores
Escribiendo Validadores
Validation Messages
Zend_Version
Obteniendo la versión de Zend Framework Version
Zend_View
Introduction
Controller Scripts
View Scripts
View Helpers
Zend_View_Abstract
Zend_Wildfire
Zend_Wildfire
Zend_XmlRpc
Introducción
Zend_XmlRpc_Client
Zend_XmlRpc_Server
ZendX_Console_Process_Unix
ZendX_Console_Process_Unix
ZendX_JQuery
Introduction
ZendX_JQuery View Helpers
ZendX_JQuery Form Elements and Decorators
Requisitos de Zend Framework
Versión de PHP
Extensiones de PHP
Componentes de Zend Framework
Dependencias de Zend Framework
Notas de Migración de Zend Framework
Zend Framework 1.10
Zend Framework 1.9
Zend Framework 1.8
Zend Framework 1.7
Zend Framework 1.6
Zend Framework 1.5
Zend Framework 1.0
Zend Framework 0.9
Zend Framework 0.8
Zend Framework 0.6
Estándares de codificación de Zend Framework para PHP
Introducción
Formato de archivos PHP
Convenciones de Nombres
Estilo de código
Zend Framework Documentation Standard
Overview
Documentation File Formatting
Recommendations
Recommended Project Structure for Zend Framework MVC Applications
Overview
Recommended Project Directory Structure
Module Structure
Rewrite Configuration Guide
Guía de Rendimiento de Zend Framework
Introduction
Class Loading
Zend_Db Performance
Internationalization (i18n) and Localization (l10n)
View Rendering
Copyright Information