documentation/manual/es/module_specs/Zend_Form-Elements.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20115 -->
   3     <!-- Reviewed: no -->
   4 <sect1 id="zend.form.elements">
   5     <title>Creando elementos de formulario usando Zend_Form_Element</title>
   6
   7     <para> Un formulario esta compuesto de elementos, que normalmente
   8         corresponden al elemento HTML input.
   9             <classname>Zend_Form_Element</classname> encapsula elementos de
  10         formulario individualmente, con las siguientes áreas de responsabilidad: </para>
  11
  12     <itemizedlist>
  13         <listitem>
  14             <para>validación (¿los datos enviados son válidos?)</para>
  15
  16             <itemizedlist>
  17                 <listitem>
  18                     <para>captura de códigos y mensajes de error</para>
  19                 </listitem>
  20             </itemizedlist>
  21         </listitem>
  22
  23         <listitem>
  24             <para>filtrado (¿cómo es escapado y normalizado el elemento para su
  25                 validación y/o salida?</para>
  26         </listitem>
  27
  28         <listitem>
  29             <para>generación (¿cómo es mostrado el elemento?)</para>
  30         </listitem>
  31
  32         <listitem>
  33             <para>metadatos y atributos (¿qué información amplía la definición
  34                 del elemento?)</para>
  35         </listitem>
  36     </itemizedlist>
  37
  38     <para> La clase base, <classname>Zend_Form_Element</classname> , funciona
  39         por defecto para varios casos, pero es mejor extender la clase para
  40         elementos con fines especiales de uso común. Adicionalmente, Zend
  41         Framework contiene un número de elementos <acronym>XHTML</acronym>
  42         estándar; puede leer de ellos <link linkend="zend.form.standardElements"
  43             >en el capítulo Elementos Estándares</link>
  44     </para>
  45
  46     <sect2 id="zend.form.elements.loaders">
  47         <title>Cargadores de Plugin</title>
  48
  49         <para>
  50             <classname>Zend_Form_Element</classname> hace uso de <link
  51                 linkend="zend.loader.pluginloader"
  52                 >Zend_Loader_PluginLoader</link> para permitir a los
  53             desarrolladores especificar ubicaciones de validadores, filtros y
  54             decoradores alternos. Cada uno tiene su propio cargador de plugin
  55             asociado a él y métodos de acceso generales usados para su
  56             recuperación y modificación. </para>
  57
  58         <para>Los siguientes tipos de cargadores son usados con los varios
  59             métodos del cargador de plugin: 'validate', 'filter', y 'decorator'.
  60             Los nombres son sensibles a mayúsculas y minúsculas.</para>
  61
  62         <para>Los métodos usados para interactuar con los cargadores de plugin
  63             son los siguientes:</para>
  64
  65         <itemizedlist>
  66             <listitem>
  67                 <para>
  68                     <methodname>setPluginLoader($loader, $type)</methodname> :
  69                         <varname>$loader</varname> es el propio objeto cargador,
  70                     mientras <varname></varname> es uno de los tipos arriba
  71                     mencionados. Esto establece el cargador de plugin para el
  72                     tipo dado en el objeto cargador recién especificado. </para>
  73             </listitem>
  74
  75             <listitem>
  76                 <para>
  77                     <methodname>getPluginLoader()</methodname> : obtiene el
  78                     cargador de plugin asociado con <varname></varname> .
  79                 </para>
  80             </listitem>
  81
  82             <listitem>
  83                 <para>
  84                     <methodname>addPrefixPath($prefix, $path, $type =
  85                         null)</methodname> : agrega una asociación prefijo/ruta
  86                     para el cargador especificado por <varname>$type</varname> .
  87                     Si <varname>$type</varname> es <constant>NULL</constant>, se intentará agregar la
  88                     ruta a todos los cargadores, añadiendo el prefijo a cada
  89                     "_Validate", "_Filter" y "_Decorator"; y agregandole
  90                     "Validate/", "Filter/" y "Decorator/" a la ruta. Si tiene
  91                     todas sus clases extras para elementos de formulario dentro
  92                     de una jerarquía común, este método es conveniente para
  93                     establecer el prefijo para todas ellas. </para>
  94             </listitem>
  95
  96             <listitem>
  97                 <para>
  98                     <methodname>addPrefixPaths(array $spec)</methodname> : le
  99                     permite añadir varias rutas de una sola vez a uno o más
 100                     cargadores de plugin. Se espera cada elemento de la matriz
 101                     sea un array con claves 'path', 'prefix', y 'type'. </para>
 102             </listitem>
 103         </itemizedlist>
 104
 105         <para>Validadores, filtros y decoradores personalizados son una manera
 106             simple de compartir funcionalidad entre formularios y encapsular
 107             funcionalidad personalizada.</para>
 108
 109         <example id="zend.form.elements.loaders.customLabel">
 110             <title>Etiqueta personalizada</title>
 111
 112             <para>Un uso común de los plugins es proveer reemplazos para las
 113                 clases estándares. Por ejemplo, si desea proveer una
 114                 implementación diferente del decorador 'Label' -- por ejemplo,
 115                 para añadir siempre dos puntos -- puede crear su propio
 116                 decorador 'Label' con su propio prefijo de clase, y entonces
 117                 añadirlo a su prefijo de ruta.</para>
 118
 119             <para>Comencemos con un decorador de etiqueta personalizado. Le
 120                 daremos el prefijo "My_Decorator", y la clase estará en el
 121                 archivo "My/Decorator/Label.php".</para>
 122
 123             <programlisting language="php"><![CDATA[
 124 class My_Decorator_Label extends Zend_Form_Decorator_Abstract
 125 {
 126     protected $_placement = 'PREPEND';
 127
 128     public function render($content)
 129     {
 130         if (null === ($element = $this->getElement())) {
 131             return $content;
 132         }
 133         if (!method_exists($element, 'getLabel')) {
 134             return $content;
 135         }
 136
 137         $label = $element->getLabel() . ':';
 138
 139         if (null === ($view = $element->getView())) {
 140             return $this->renderLabel($content, $label);
 141         }
 142
 143         $label = $view->formLabel($element->getName(), $label);
 144
 145         return $this->renderLabel($content, $label);
 146     }
 147
 148     public function renderLabel($content, $label)
 149     {
 150         $placement = $this->getPlacement();
 151         $separator = $this->getSeparator();
 152
 153         switch ($placement) {
 154             case 'APPEND':
 155                 return $content . $separator . $label;
 156             case 'PREPEND':
 157             default:
 158                 return $label . $separator . $content;
 159         }
 160     }
 161 }
 162 ]]></programlisting>
 163
 164             <para>Ahora diremos al elemento que use esta ruta cuando busque por
 165                 decoradores:</para>
 166
 167             <programlisting language="php"><![CDATA[
 168 $element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
 169 ]]></programlisting>
 170
 171             <para>Alternativamente, podemos hacerlo en el formulario para
 172                 asegurar que todos los decoradores usen esta ruta:</para>
 173
 174             <programlisting language="php"><![CDATA[
 175 $form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
 176 ]]></programlisting>
 177
 178             <para>Con esta ruta añadida, cuando agregue un decorador, la ruta
 179                 'My/Decorator' será consultada primero en búsqueda de la
 180                 existencia del decorador en este lugar. Como resultado,
 181                 'My_Decorator_Label' ahora será utilizado cuando el decorador
 182                 'Label' sea requerido.</para>
 183         </example>
 184     </sect2>
 185
 186     <sect2 id="zend.form.elements.filters">
 187         <title>Filters</title>
 188
 189         <para> A menudo es útil y/o necesario realizar alguna normalización en
 190             la entrada antes de la validación – por ejemplo, puede querer
 191             eliminar todo el <acronym>HTML</acronym> , pero realizar las
 192             validaciones sobre lo restante para asegurarse que el envío es
 193             válido. O puede eliminar los espacios en blanco al inicio o fin de
 194             la entrada para asegurarse de que un validador StringLenth (longitud
 195             de la cadena) no regrese un positivo falso. Estas operaciones pueden
 196             realizarse usando <classname>Zend_Filter</classname> , y
 197                 <classname>Zend_Form_Element</classname> que soportan cadenas de
 198             filtros, permitiéndole especificar múltiples filtros secuenciales a
 199             utilizar. El filtrado sucede tanto en la validación como cuando
 200             recupera el valor del elemento vía
 201                 <methodname>getValue()</methodname> : </para>
 202
 203         <programlisting language="php"><![CDATA[
 204 $filtered = $element->getValue();
 205
 206 ]]></programlisting>
 207
 208         <para>Los filtros pueden ser agregados a la pila de dos maneras:</para>
 209
 210         <itemizedlist>
 211             <listitem>
 212                 <para>pasándolo en una instancia de filtro específica</para>
 213             </listitem>
 214
 215             <listitem>
 216                 <para>proveyendo un nombre de filtro – el correspondiente nombre
 217                     corto o completo de la clase</para>
 218             </listitem>
 219         </itemizedlist>
 220
 221         <para>Veamos algunos ejemplos:</para>
 222
 223         <programlisting language="php"><![CDATA[
 224 // Instancia específica del filtro
 225 $element->addFilter(new Zend_Filter_Alnum());
 226
 227 // El correspondiente nombre completo de la clase:
 228 $element->addFilter('Zend_Filter_Alnum');
 229
 230 // Nombre corto del filtro:
 231 $element->addFilter('Alnum');
 232 $element->addFilter('alnum');
 233 ]]></programlisting>
 234
 235         <para>Los nombres cortos son típicamente el nombre del filtro sin el
 236             prefijo. En el caso predeterminado, esto se refiere a sin el prefijo
 237             'Zend_Filter_'. Además, la primera letra no necesita estar en
 238             mayúscula.</para>
 239
 240         <note>
 241             <title>Usando clases de filtros personalizados</title>
 242
 243             <para> Si tiene su propio conjunto de clases de filtro, puede
 244                 informarle de ellas a <classname>Zend_Form_Element</classname>
 245                 usando <methodname>addPrefixPath()</methodname> . Por ejemplo,
 246                 si tiene filtros con el prefijo 'My_Filter', puede indicárselo a
 247                     <classname>Zend_Form_Element</classname> de la siguiente
 248                 manera: </para>
 249
 250             <programlisting language="php"><![CDATA[
 251 $element->addPrefixPath('My_Filter', 'My/Filter/', 'filter');
 252 ]]></programlisting>
 253
 254             <para>(Recuerde que el tercer argumento indica el cargador de plugin
 255                 sobre el cual ha de ejecutarse la acción.)</para>
 256         </note>
 257
 258         <para> Si en algún momento necesita un valor no filtrado, use el método
 259                 <methodname>getUnfilteredValue()</methodname> : </para>
 260
 261         <programlisting language="php"><![CDATA[
 262 $unfiltered = $element->getUnfilteredValue();
 263 ]]></programlisting>
 264
 265         <para> Para mayor información sobre filtros, vea la <link
 266                 linkend="zend.filter.introduction">documentación de
 267                 Zend_Filter</link> . </para>
 268
 269         <para>Métodos asociados con filtros incluyen:</para>
 270
 271         <itemizedlist>
 272             <listitem>
 273                 <para>
 274                     <methodname>addFilter($nameOfFilter, array $options =
 275                         null)</methodname>
 276                 </para>
 277             </listitem>
 278
 279             <listitem>
 280                 <para>
 281                     <methodname>addFilters(array $filters)</methodname>
 282                 </para>
 283             </listitem>
 284
 285             <listitem>
 286                 <para>
 287                     <methodname>setFilters(array $filters)</methodname>
 288                     (sobreescribe todos los filtros) </para>
 289             </listitem>
 290
 291             <listitem>
 292                 <para>
 293                     <methodname>getFilter($name)</methodname> (recupera un
 294                     objeto filtro por su nombre) </para>
 295             </listitem>
 296
 297             <listitem>
 298                 <para>
 299                     <methodname>getFilters()</methodname> (recupera todos los
 300                     filtros) </para>
 301             </listitem>
 302
 303             <listitem>
 304                 <para>
 305                     <methodname>removeFilter($name)</methodname> (elimina un
 306                     filtro por su nombre) </para>
 307             </listitem>
 308
 309             <listitem>
 310                 <para>
 311                     <methodname>clearFilters()</methodname> (elimina todos los
 312                     filtros) </para>
 313             </listitem>
 314         </itemizedlist>
 315     </sect2>
 316
 317     <sect2 id="zend.form.elements.validators">
 318         <title>Validadores</title>
 319
 320         <para> Si sigue el mantra de seguridad "filtrar la entrada, escapar la
 321             salida" querrá validar ("filtrar la entrada") los datos de los
 322             formularios. En <classname>Zend_Form</classname> cada elemento
 323             contiene su propia cadena de validadores, consistente en validadores
 324                 <methodname>Zend_Validate_*</methodname> . </para>
 325
 326         <para>Los validadores pueden ser agregados de dos maneras:</para>
 327
 328         <itemizedlist>
 329             <listitem>
 330                 <para>pasándolo en una instancia de validador específica </para>
 331             </listitem>
 332
 333             <listitem>
 334                 <para>proveyendo un nombre de validador – el correspondiente
 335                     nombre corto o completo de clase</para>
 336             </listitem>
 337         </itemizedlist>
 338
 339         <para>Veamos algunos ejemplos:</para>
 340
 341         <programlisting language="php"><![CDATA[
 342 // Instancia específica del validador:
 343 $element->addValidator(new Zend_Validate_Alnum());
 344
 345 // El correspondiente nombre completo de la clase:
 346 $element->addValidator('Zend_Validate_Alnum');
 347
 348 // Nombre corto del validador:
 349 $element->addValidator('Alnum');
 350 $element->addValidator('alnum');
 351 ]]></programlisting>
 352
 353         <para>Los nombres cortos son típicamente el nombre del validador sin el
 354             prefijo. En el caso predeterminado, esto se refiere a sin el prefijo
 355             'Zend_Validate_'. Además, la primera letra no necesita estar en
 356             mayúscula.</para>
 357
 358         <note>
 359             <title>Usando clases de validación personalizadas</title>
 360
 361             <para> Si tiene su propio conjunto de clases de validación, puede
 362                 informarle de ellas a <classname>Zend_Form_Element</classname>
 363                 usando <methodname>addPrefixPath()</methodname> . Por ejemplo,
 364                 si tiene validadores con el prefijo 'My_Validator', puede
 365                 indicárselo a <classname>Zend_Form_Element</classname> de la
 366                 siguiente manera: </para>
 367
 368             <programlisting language="php"><![CDATA[
 369 $element->addPrefixPath('My_Validator', 'My/Validator/', 'validate');
 370 ]]></programlisting>
 371
 372             <para>(Recuerde que el tercer argumento indica el cargador de plugin
 373                 sobre el cual ha de ejecutarse la acción.)</para>
 374         </note>
 375
 376         <para> Si el fallo de un validador debe evitar validaciones posteriores,
 377             pase el boleano <constant>TRUE</constant> como segundo parámetro: </para>
 378
 379         <programlisting language="php"><![CDATA[
 380 $element->addValidator('alnum', true);
 381 ]]></programlisting>
 382
 383         <para> Si está usando la cadena nombre para añadir el validador, y la
 384             clase del validador acepta argumentos para su constructor, puede
 385             pasarlos a el tercer parámetro de
 386                 <methodname>addValidator()</methodname> como un array: </para>
 387
 388         <programlisting language="php"><![CDATA[
 389 $element->addValidator('StringLength', false, array(6, 20));
 390 ]]></programlisting>
 391
 392         <para> Los argumentos pasados de esta manera deben estar en el orden en
 393             el cual son definidos en el constructor. El ejemplo de arriba
 394             instanciará la clase
 395                 <classname>Zend_Validate_StringLenth</classname> con los
 396             parámetros <varname>$min</varname> y <varname>$max</varname> : </para>
 397
 398         <programlisting language="php"><![CDATA[
 399 $validator = new Zend_Validate_StringLength(6, 20);
 400 ]]></programlisting>
 401
 402         <note>
 403             <title>Estipulando mensajes de error de validación
 404                 personalizados</title>
 405
 406             <para> Algunos desarrolladores querrán estipular mensajes de error
 407                 personalizados para un validador. El argumento
 408                     <varname>$options</varname> de
 409                     <methodname>Zend_Form_Element::addValidator()</methodname>
 410                 le permite hacerlo proporcionando la clave 'messages' y
 411                 estableciendolos en un array de pares clave/valor para
 412                 especificar las plantillas de mensaje. Necesitará conocer los
 413                 códigos de error de los diferentes tipos de error de un
 414                 validador en particular. </para>
 415
 416             <para> Una opción mejor es usar
 417                     <classname>Zend_Translate_Adapter</classname> con su
 418                 formulario. Los códigos de error son automáticamente pasados al
 419                 adaptador por el decorador Errors por defecto; puede especificar
 420                 su propias cadenas de mensaje de error mediante la creación de
 421                 traducciones para los varios códigos de error de sus
 422                 validadores. </para>
 423         </note>
 424
 425         <para> Puede también establecer varios validadores a la vez, usando
 426                 <methodname>addValidators()</methodname> . Su uso básico es
 427             pasar una matriz de arrays, donde cada array contenga de 1 a 3
 428             valores, correspondientes al constructor de
 429                 <methodname>addValidator()</methodname> : </para>
 430
 431         <programlisting language="php"><![CDATA[
 432 $element->addValidators(array(
 433     array('NotEmpty', true),
 434     array('alnum'),
 435     array('stringLength', false, array(6, 20)),
 436 ));
 437 ]]></programlisting>
 438
 439         <para>Si quiere ser más detallado o explícito, puede utilizar las claves
 440             'validator', 'breakChainOnFailure', y 'options' en el array:</para>
 441
 442         <programlisting language="php"><![CDATA[
 443 $element->addValidators(array(
 444     array(
 445         'validator'           => 'NotEmpty',
 446         'breakChainOnFailure' => true),
 447     array('validator' => 'alnum'),
 448     array(
 449         'validator' => 'stringLength',
 450         'options'   => array(6, 20)),
 451 ));
 452 ]]></programlisting>
 453
 454         <para>Este uso es bueno para ilustrar cómo puede configurar validadores
 455             en un archivo de configuración:</para>
 456
 457         <programlisting language="ini"><![CDATA[
 458 element.validators.notempty.validator = "NotEmpty"
 459 element.validators.notempty.breakChainOnFailure = true
 460 element.validators.alnum.validator = "Alnum"
 461 element.validators.strlen.validator = "StringLength"
 462 element.validators.strlen.options.min = 6
 463 element.validators.strlen.options.max = 20
 464 ]]></programlisting>
 465
 466         <para>Note que cada elemento tiene una clave, la necesite o no; esta es
 467             una limitación del uso de archivos de configuración -- pero también
 468             ayuda a hacer más explicito el para qué son usados los argumentos.
 469             Sólo recuerde que cualesquiera opciones del validador deben ser
 470             especificadas en orden.</para>
 471
 472         <para> Para validar un elemento, pase el valor a
 473                 <methodname>isValid()</methodname> : </para>
 474
 475         <programlisting language="php"><![CDATA[
 476 if ($element->isValid($value)) {
 477     // válido
 478 } else {
 479     // no válido
 480 }
 481 ]]></programlisting>
 482
 483         <note>
 484             <title>Validación operando en valores filtrados</title>
 485
 486             <para>
 487                 <methodname>Zend_Form_Element::isValid()</methodname> > siempre
 488                 filtra los valores antes de la validación a través de la cadena
 489                 de filtros. Vea <link linkend="zend.form.elements.filters">la
 490                     sección de filtros</link> para más información. </para>
 491         </note>
 492
 493         <note>
 494             <title>Contexto de validación</title>
 495
 496             <para>
 497                 <methodname>Zend_Form_Element::isValid()</methodname> > soporta
 498                 un argumento adicional, <varname>$context</varname> .
 499                     <methodname>Zend_Form::isValid()</methodname> pasa todo el
 500                 conjunto de datos procesados a <varname>$context</varname>
 501                 cuando valida un formulario, y
 502                     <methodname>Zend_Form_Element::isValid()</methodname> >, a
 503                 su vez, lo pasa a cada validador. Esto significa que puede
 504                 escribir validadores que son conscientes de los datos pasados a
 505                 otros elementos del formulario. Como ejemplo, considere un
 506                 formulario de registro estándar que tiene campos para la
 507                 contraseña y la confirmación de la contraseña; una validación
 508                 sería que los dos campos coincidan. Este validador puede tener
 509                 un aspecto como el siguiente: </para>
 510
 511             <programlisting language="php"><![CDATA[
 512 class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract
 513 {
 514     const NOT_MATCH = 'notMatch';
 515
 516     protected $_messageTemplates = array(
 517         self::NOT_MATCH => 'Password confirmation does not match'
 518     );
 519
 520     public function isValid($value, $context = null)
 521     {
 522         $value = (string) $value;
 523         $this->_setValue($value);
 524
 525         if (is_array($context)) {
 526             if (isset($context['password_confirm'])
 527                 && ($value == $context['password_confirm']))
 528             {
 529                 return true;
 530             }
 531         } elseif (is_string($context) && ($value == $context)) {
 532             return true;
 533         }
 534
 535         $this->_error(self::NOT_MATCH);
 536         return false;
 537     }
 538 }
 539 ]]></programlisting>
 540         </note>
 541
 542         <para> Los validadores son procesados en orden. Cada validador es
 543             procesado, a menos que un validador creado con un valor true para
 544                 <methodname>breakChainOnFailure</methodname> falle su
 545             validación. Asegúrese de especificar sus validadores en un orden
 546             razonable. </para>
 547
 548         <para>Después de una validación fallida, puede recuperar los códigos y
 549             mensajes de error de la cadena del validador:</para>
 550
 551         <programlisting language="php"><![CDATA[
 552 $errors   = $element->getErrors();
 553 $messages = $element->getMessages();
 554 ]]></programlisting>
 555
 556         <para>(Nota: los mensajes de error retornados son un array asociativo de
 557             pares código / mensaje de error.)</para>
 558
 559         <para> En adición a los validadores, puede especificar que un elemento
 560             es necesario, usando <methodname>setRequired(true)</methodname> .
 561             Por defecto, esta bandera es <constant>FALSE</constant> , lo que
 562             significa que pasará su cadena de validadores si ningún valor es
 563             pasado a <methodname>isValid()</methodname> . Puede modificar este
 564             comportamiento en un número de maneras: </para>
 565
 566         <itemizedlist>
 567             <listitem>
 568                 <para> Por defecto, cuando un elemento es requerido, una
 569                     bandera, 'allowEmpty', también es true. Esto quiere decir
 570                     que si un valor empty es evaluado pasándolo a
 571                         <methodname>isValid()</methodname> , los validadores
 572                     serán saltados. Puede intercalar esta bandera usando el
 573                     método de acceso
 574                         <methodname>setAllowEmpty($flag)</methodname> ; cuando
 575                     la bandera es false, si un valor es pasado, los validadores
 576                     seguirán ejecutándose. </para>
 577             </listitem>
 578
 579             <listitem>
 580                 <para> Por defecto, si un elemento es requerido, pero no
 581                     contiene un validador 'NotEmpty',
 582                         <methodname>isValid()</methodname> añadirá uno en la
 583                     cima de la pila, con la bandera
 584                         <methodname>breakChainOnFailure</methodname>
 585                     establecido. Esto hace que la bandera requerida tenga un
 586                     significado semántico: si ningún valor es pasado,
 587                     inmediatamente invalidamos el envío y se le notifica al
 588                     usuario, e impedimos que otros validadores se ejecuten en lo
 589                     que ya sabemos son datos inválidos. </para>
 590
 591                 <para> Si no quiere este comportamiento, puede desactivarlo
 592                     pasando un valor false a
 593                         <methodname>setAutoInsertNotEmptyValidator($flag)</methodname>
 594                     ; esto prevendrá a <methodname>isValid()</methodname> de
 595                     colocar un validador 'NotEmpty' en la cadena de
 596                     validaciones. </para>
 597             </listitem>
 598         </itemizedlist>
 599
 600         <para> Para mayor información sobre validadores, vea la <link
 601                 linkend="zend.validate.introduction">documentación de
 602                 Zend_Validate</link> . </para>
 603
 604         <note>
 605             <title>Usando Zend_Form_Elements como validador de propósito
 606                 general</title>
 607
 608             <para>
 609                 <classname>Zend_Form_Element</classname> implementa
 610                     <classname>Zend_Validate_Interface</classname> ,
 611                 significando un elemento puede también usarse como un validador
 612                 en otro, cadenas de validación no relacionadas al formulario.
 613             </para>
 614         </note>
 615
 616         <para>Métodos asociados con validación incluyen:</para>
 617
 618         <itemizedlist>
 619             <listitem>
 620                 <para>
 621                     <methodname>setRequired($flag)</methodname> y
 622                         <methodname>isRequired()</methodname> permiten
 623                     establecer y recuperar el estado de la bandera 'required'.
 624                     Cuando se le asigna un booleano <constant>TRUE</constant> ,
 625                     esta bandera requiere que el elemento esté presente en la
 626                     información procesada por <classname>Zend_Form</classname> .
 627                 </para>
 628             </listitem>
 629
 630             <listitem>
 631                 <para>
 632                     <methodname>setAllowEmpty($flag)</methodname> y
 633                         <methodname>getAllowEmpty()</methodname> permiten
 634                     modificar el comportamiento de elementos opcionales (p.e.,
 635                     elementos donde la bandera required es <constant>FALSE</constant>). Cuando la
 636                     bandera 'allow empty' es <constant>TRUE</constant> , valores
 637                     vacíos no pasarán la cadena de validadores. </para>
 638             </listitem>
 639
 640             <listitem>
 641                 <para>
 642                     <methodname>setAutoInsertNotEmptyValidator($flag)</methodname>
 643                     permite especificar si realmente un validador 'NotEmpty'
 644                     será añadido el inicio de la cadena de validaciones cuando
 645                     un elemento es requerido. Por defecto, esta bandera es
 646                         <constant>TRUE</constant> . </para>
 647             </listitem>
 648
 649             <listitem>
 650                 <para>
 651                     <methodname>addValidator($nameOrValidator,
 652                         $breakChainOnFailure = false, array $options =
 653                         null)</methodname>
 654                 </para>
 655             </listitem>
 656
 657             <listitem>
 658                 <para>
 659                     <methodname>addValidators(array $validators)</methodname>
 660                 </para>
 661             </listitem>
 662
 663             <listitem>
 664                 <para>
 665                     <methodname>setValidators(array $validators)</methodname>
 666                     (sobreescribe todos los validadores) </para>
 667             </listitem>
 668
 669             <listitem>
 670                 <para>
 671                     <methodname>getValidator($name)</methodname> (recupera un
 672                     objeto validador por nombre) </para>
 673             </listitem>
 674
 675             <listitem>
 676                 <para>
 677                     <methodname>getValidators()</methodname> (recupera todos los
 678                     validadores) </para>
 679             </listitem>
 680
 681             <listitem>
 682                 <para>
 683                     <methodname>removeValidator($name)</methodname> (elimina un
 684                     validador por nombre) </para>
 685             </listitem>
 686
 687             <listitem>
 688                 <para>
 689                     <methodname>clearValidators()</methodname> (elimina todos
 690                     los validadores) </para>
 691             </listitem>
 692         </itemizedlist>
 693
 694         <sect3 id="zend.form.elements.validators.errors">
 695             <title>Errores de mensaje personalizados</title>
 696
 697             <para>Alguna veces, querrá especificar uno o más mensajes de error
 698                 para usarlos en lugar de los mensajes de error generados por los
 699                 validadores adjuntos a los elementos. Adicionalmente, algunas
 700                 veces usted mismo querrá marcar al elemento como inválido. A
 701                 partir de 1.6.0, esta funcionalidad es posible vía los
 702                 siguientes métodos.</para>
 703
 704             <itemizedlist>
 705                 <listitem>
 706                     <para>
 707                         <methodname>addErrorMessage($message)</methodname> :
 708                         añade un mensaje de error para mostrarlos en forma de
 709                         errores de validación. Puede llamarlo más de una vez, y
 710                         los nuevos mensajes nuevos son añadidos a la pila.
 711                     </para>
 712                 </listitem>
 713
 714                 <listitem>
 715                     <para>
 716                         <methodname>addErrorMessages(array
 717                             $messages)</methodname> : añade múltiples mensajes
 718                         de error para mostrarlos en forma de errores de
 719                         validación. </para>
 720                 </listitem>
 721
 722                 <listitem>
 723                     <para>
 724                         <methodname>setErrorMessages(array
 725                             $messages)</methodname> : añade múltiples mensajes
 726                         de error para mostrarlos en forma de errores de
 727                         validación, sobreescribiendo todos los mensajes de error
 728                         previamente establecidos. </para>
 729                 </listitem>
 730
 731                 <listitem>
 732                     <para>
 733                         <methodname>getErrorMessages()</methodname> : recupera
 734                         la lista de mensajes de error personalizados que fueron
 735                         definidos. </para>
 736                 </listitem>
 737
 738                 <listitem>
 739                     <para>
 740                         <methodname>clearErrorMessages()</methodname> : remueve
 741                         todos los mensajes de error personalizados que hayan
 742                         sido definidos. </para>
 743                 </listitem>
 744
 745                 <listitem>
 746                     <para>
 747                         <methodname>markAsError()</methodname> : marca al
 748                         elemento como que falló la validación. </para>
 749                 </listitem>
 750
 751                 <listitem>
 752                     <para>
 753                         <methodname>hasErrors()</methodname> : determina si el
 754                         elemento ha fallado la validación o ha sido marcado como
 755                         inválido. </para>
 756                 </listitem>
 757
 758                 <listitem>
 759                     <para>
 760                         <methodname>addError($message)</methodname> : añade un
 761                         mensaje a la pila de mensaje de error personalizados y
 762                         marca al elemento como inválido. </para>
 763                 </listitem>
 764
 765                 <listitem>
 766                     <para>
 767                         <methodname>addErrors(array $messages)</methodname> :
 768                         añade varios mensajes a la pila de mensajes de error
 769                         personalizados y marca al elemento como inválido.
 770                     </para>
 771                 </listitem>
 772
 773                 <listitem>
 774                     <para>
 775                         <methodname>setErrors(array $messages)</methodname> :
 776                         sobreescribe el mensaje de error personalizado en la
 777                         pila con los mensajes previstos y marca al elemento como
 778                         inválido. </para>
 779                 </listitem>
 780             </itemizedlist>
 781
 782             <para>Todos los errores establecidos de este modo pueden ser
 783                 traducidos. Adicionalmente, puede insertar el marcador "%value%"
 784                 para representar el valor del elemento; este valor actual del
 785                 elemento será sustituido cuando el mensaje de error sea
 786                 recuperado.</para>
 787         </sect3>
 788     </sect2>
 789
 790     <sect2 id="zend.form.elements.decorators">
 791         <title>Decoradores</title>
 792
 793         <para> Una dolencia particular para muchos desarrolladores web es la
 794             creación del <acronym>XHTML</acronym> para formularios por ellos
 795             mismos. Para cada elemento, el desarrollador necesita crear la
 796             marcación para el elemento mismo, comúnmente una etiqueta (label),
 797             y, si son amables con sus usuarios, la marcación para mostrar
 798             mensajes de errores de validación. Cuanto más elementos en una
 799             página, menos trivial se convierte esta tarea. </para>
 800
 801         <para>
 802             <classname>Zend_Form_Element</classname> intenta resolver este
 803             problema mediante el uso de "decoradores". Los decoradores son
 804             clases simples que tienen métodos de acceso al elemento y métodos
 805             para generar el contenido. Para obtener mayor información sobre cómo
 806             trabajan los decoradores, consulte por favor la sección sobre <link
 807                 linkend="zend.form.decorators">Zend_Form_Decorator</link> . </para>
 808
 809         <para> Los decoradores usados por defecto por
 810                 <classname>Zend_Form_Element</classname> son: </para>
 811
 812         <itemizedlist>
 813             <listitem>
 814                 <para>
 815                     <emphasis>ViewHelper</emphasis> : especifica un view helper
 816                     que usar para general el elemento. El atributo 'helper' del
 817                     elemento puede usarse para especificar qué auxiliar vista
 818                     usar. Por defecto, <classname>Zend_Form_Element</classname>
 819                     especifica el auxiliar vista 'formText', pero cada subclase
 820                     especifica diferentes auxiliares. </para>
 821             </listitem>
 822
 823             <listitem>
 824                 <para>
 825                     <emphasis>Errors</emphasis> : añade mensajes de error al
 826                     elemento usando
 827                         <classname>Zend_View_Helper_FormErrors</classname> . Si
 828                     no está presente, no se añade nada. </para>
 829             </listitem>
 830
 831             <listitem>
 832                 <para>
 833                     <emphasis>Description</emphasis>: añade la descripción del
 834                     elemento. Si no está presente, no se añade nada. Por
 835                     defecto, la descripción es generada dentro de una etiqueta
 836                     &lt;p&gt; con un class 'description'. </para>
 837             </listitem>
 838
 839             <listitem>
 840                 <para>
 841                     <emphasis>HtmlTag</emphasis>: envuelve el elemento y los
 842                     errores en una etiqueta HTML &lt;dd&gt;. </para>
 843             </listitem>
 844
 845             <listitem>
 846                 <para>
 847                     <emphasis>Label</emphasis> : añade al comienzo una etiqueta
 848                     al elemento usando
 849                         <classname>Zend_View_Helper_FormLabel</classname>, y
 850                     envolviéndola en una etiqueta &lt;dt&gt;. Si ninguna
 851                     etiqueta es provista, solo la etiqueta de la definición es
 852                     generada. </para>
 853             </listitem>
 854         </itemizedlist>
 855
 856         <note>
 857             <title>Decoradores por defecto no necesitan ser cargados</title>
 858
 859             <para>Por defecto, los decoradores por defecto son cargados durante
 860                 la inicialización del objeto. Puede deshabilitar esto pasando la
 861                 opción 'disableLoadDefaultDecorators' al constructor:</para>
 862
 863             <programlisting language="php"><![CDATA[
 864 $element = new Zend_Form_Element('foo',
 865                                  array('disableLoadDefaultDecorators' =>
 866                                       true)
 867                                 );
 868 ]]></programlisting>
 869
 870             <para> Esta opción puede ser combinada junto con cualquier otra
 871                 opción que pase, ya sea como un array de opciones o en un objeto
 872                     <classname>Zend_Config</classname> . </para>
 873         </note>
 874
 875         <para>Ya que el orden en el cual los decoradores son registrados importa
 876             -- el primer decorador registrado es ejecutado primero -- necesitará
 877             estar seguro de registrar sus decoradores en el orden apropiado, o
 878             asegurarse de que estableció las opciones de colocación en el modo
 879             apropiado. Por dar un ejemplo, aquí esta el código que registran los
 880             decoradores por defecto:</para>
 881
 882         <programlisting language="php"><![CDATA[
 883 $this->addDecorators(array(
 884     array('ViewHelper'),
 885     array('Errors'),
 886     array('Description', array('tag' => 'p', 'class' => 'description')),
 887     array('HtmlTag', array('tag' => 'dd')),
 888     array('Label', array('tag' => 'dt')),
 889 ));
 890 ]]></programlisting>
 891
 892         <para>El contenido inicial es creado por el decorador 'ViewHelper', que
 893             crea el propio elemento. En seguida, el decorador 'Errors' consulta
 894             los mensajes de error del elemento, y, si hay alguno presente, los
 895             pasa al auxiliar vista 'FormErrors' para mostrarlos. Si una
 896             descripción está presente, el decorador 'Description' añadirá un
 897             párrafo con class 'description' conteniendo el texto descriptivo
 898             para el contenido agregado. El siguiente decorador, 'HtmlTag',
 899             envuelve al elemento, los errores, y la descripción en una etiqueta
 900             HTML &lt;dd&gt;. Finalmente, el último decorador, 'label',
 901             recupera la etiqueta del elemento y la pasa al auxiliar vista
 902             'FormLabel', envolviéndolo en una etiqueta &lt;dt&gt;; por
 903             default el valor es añadido al inicio del contenido. El resultado de
 904             la salida básicamente se ve así:</para>
 905
 906         <programlisting language="html"><![CDATA[
 907 <dt><label for="foo" class="optional">Foo</label></dt>
 908 <dd>
 909     <input type="text" name="foo" id="foo" value="123" />
 910     <ul class="errors">
 911         <li>"123" is not an alphanumeric value</li>
 912     </ul>
 913     <p class="description">
 914         This is some descriptive text regarding the element.
 915     </p>
 916 </dd>
 917 ]]></programlisting>
 918
 919         <para> Para más información sobre decoradores, lea la <link
 920                 linkend="zend.form.decorators"> sección de
 921                 Zend_Form_Decorator</link> . </para>
 922
 923         <note>
 924             <title>Usando múltiples decoradores al mismo tiempo</title>
 925
 926             <para> Internamente, <classname>Zend_Form_Element</classname>
 927                 utiliza una clase decorador como mecanismo de búsqueda para la
 928                 recuperación de decoradores. Como resultado, no puede registrar
 929                 múltiples decoradores del mismo tipo; decoradores subsecuentes
 930                 simplemente sobreescribirán aquellos que ya existían. </para>
 931
 932             <para> Para evitar esto, puede usar <emphasis>alias</emphasis> . En
 933                 lugar de pasar un decorador o nombre de decorador como primer
 934                 argumento a <methodname>addDecorator()</methodname> , pase una
 935                 matriz con un solo elemento, con el alias apuntando al nombre o
 936                 objeto decorador: </para>
 937
 938             <programlisting language="php"><![CDATA[
 939 // Alias a 'FooBar':
 940 $element->addDecorator(array('FooBar' => 'HtmlTag'),
 941                        array('tag' => 'div'));
 942
 943 // Y recuperandolo posteriormente:
 944 $decorator = $element->getDecorator('FooBar');
 945 ]]></programlisting>
 946
 947             <para> En los métodos <methodname>addDecorators()</methodname> y
 948                     <methodname>setDecorators()</methodname> , necesitará pasar
 949                 la opción 'decorator' en la matriz representando el decorador: </para>
 950
 951             <programlisting language="php"><![CDATA[
 952 // Y dos decoradores 'HtmlTag', 'FooBar' como alias:
 953 $element->addDecorators(
 954     array('HtmlTag', array('tag' => 'div')),
 955     array(
 956         'decorator' => array('FooBar' => 'HtmlTag'),
 957         'options' => array('tag' => 'dd')
 958     ),
 959 );
 960
 961 // Y recuperándolos posteriormente:
 962 $htmlTag = $element->getDecorator('HtmlTag');
 963 $fooBar  = $element->getDecorator('FooBar');
 964 ]]></programlisting>
 965         </note>
 966
 967         <para>Métodos asociados con decoradores incluyen:</para>
 968
 969         <itemizedlist>
 970             <listitem>
 971                 <para>
 972                     <methodname>addDecorator($nameOrDecorator, array $options =
 973                         null)</methodname>
 974                 </para>
 975             </listitem>
 976
 977             <listitem>
 978                 <para>
 979                     <methodname>addDecorators(array $decorators)</methodname>
 980                 </para>
 981             </listitem>
 982
 983             <listitem>
 984                 <para>
 985                     <methodname>setDecorators(array $decorators)</methodname>
 986                     (sobreescribe todos los decoradores) </para>
 987             </listitem>
 988
 989             <listitem>
 990                 <para>
 991                     <methodname>getDecorator($name)</methodname> (recupera un
 992                     objeto decorador por su nombre) </para>
 993             </listitem>
 994
 995             <listitem>
 996                 <para>
 997                     <methodname>getDecorators()</methodname> (recupera todos los
 998                     decoradores) </para>
 999             </listitem>
1000
1001             <listitem>
1002                 <para>
1003                     <methodname>removeDecorator($name)</methodname> (elimina un
1004                     decorador por su nombre) </para>
1005             </listitem>
1006
1007             <listitem>
1008                 <para>
1009                     <methodname>clearDecorators()</methodname> (elimina todos
1010                     los decoradores) </para>
1011             </listitem>
1012         </itemizedlist>
1013
1014         <para>
1015             <classname>Zend_Form_Element</classname> también utiliza la
1016             sobrecarga para permitir generar decoradores específicos.
1017                 <methodname>__call()</methodname> interceptará métodos que
1018             comiencen con el texto 'render' y utilizará el resto del nombre del
1019             método para buscar un decorador; si se encuentra, entonces será
1020             generado <emphasis>sólo ese</emphasis> decorador. Cualquier
1021             argumento pasado al llamado del método será usado como contenido
1022             para pasar al método <methodname>render()</methodname> del
1023             decorador. Como ejemplo: </para>
1024
1025         <programlisting language="php"><![CDATA[
1026 // Genera solo el decorador ViewHelper:
1027 echo $element->renderViewHelper();
1028
1029 // Genera solo el decorador HtmlTag, pasándole contenido:
1030 echo $element->renderHtmlTag("This is the html tag content");
1031 ]]></programlisting>
1032
1033         <para>Si el decorador no existe, una excepción es lanzada.</para>
1034     </sect2>
1035
1036     <sect2 id="zend.form.elements.metadata">
1037         <title>Metadatos y atributos</title>
1038
1039         <para>
1040             <classname>Zend_Form_Element</classname> manipula una variedad de
1041             atributos y medatados del elemento. Atributos básicos incluyen: </para>
1042
1043         <itemizedlist>
1044             <listitem>
1045                 <para>
1046                     <emphasis>name</emphasis> : el nombre del elemento. Emplea
1047                     los métodos de acceso <methodname>setName()</methodname> y
1048                         <methodname>getName()</methodname> . </para>
1049             </listitem>
1050
1051             <listitem>
1052                 <para>
1053                     <emphasis>label</emphasis> : la etiqueta del elemento.
1054                     Emplea los métodos de acceso
1055                         <methodname>setLabel()</methodname> y
1056                         <methodname>getLabel()</methodname> . </para>
1057             </listitem>
1058
1059             <listitem>
1060                 <para>
1061                     <emphasis>order</emphasis> : el índice en el cual los
1062                     elementos deben ir mostrándose en el formulario. Emplea los
1063                     métodos de acceso <methodname>setOrder()</methodname> y
1064                         <methodname>getOrder()</methodname> . </para>
1065             </listitem>
1066
1067             <listitem>
1068                 <para>
1069                     <emphasis>value</emphasis> : El valor del elemento actual.
1070                     Emplea los métodos de acceso
1071                         <methodname>setValue()</methodname> y
1072                         <methodname>getValue()</methodname> . </para>
1073             </listitem>
1074
1075             <listitem>
1076                 <para>
1077                     <emphasis>description</emphasis> : una descripción del
1078                     elemento; a menudo utilizada para proveer un tooltip o ayuda
1079                     contextual con javascript describiendo el propósito del
1080                     elemento. Emplea los métodos de acceso
1081                         <methodname>setDescription()</methodname> y
1082                         <methodname>getDescription()</methodname> . </para>
1083             </listitem>
1084
1085             <listitem>
1086                 <para>
1087                     <emphasis>required</emphasis> : bandera que indica si un
1088                     elemento es requerido o no cuando se efectúa la validación
1089                     del formulario. Emplea los métodos de acceso
1090                         <methodname>setRequired()</methodname> y
1091                         <methodname>getRequired()</methodname> . Esta bandera es
1092                         <constant>FALSE</constant> por defecto. </para>
1093             </listitem>
1094
1095             <listitem>
1096                 <para>
1097                     <emphasis>allowEmpty</emphasis> : bandera indicando si un
1098                     elemento no-requerido (opcional) debe intentar validar o no
1099                     valores vacíos. Cuando es <constant>TRUE</constant> , y la
1100                     bandera required es <constant>FALSE</constant> , valores
1101                     vacíos no pasarán la cadena de validación, y se supone
1102                     verdadero. Emplea los métodos de acceso
1103                         <methodname>setAllowEmpty()</methodname> y
1104                         <methodname>getAllowEmpty()</methodname> . Esta bandera
1105                     es <constant>TRUE</constant> por defecto. </para>
1106             </listitem>
1107
1108             <listitem>
1109                 <para>
1110                     <emphasis>autoInsertNotEmptyValidator</emphasis> : bandera
1111                     indicando insertar o no un validador 'NotEmpty' cuando un
1112                     elemento es requerido. Por defecto, esta bandera es
1113                         <constant>TRUE</constant> . Establezca la bandera con
1114                         <methodname>setAutoInsertNotEmptyValidator($flag)</methodname>
1115                     y determine el valor con
1116                         <methodname>autoInsertNotEmptyValidator()</methodname> .
1117                 </para>
1118             </listitem>
1119         </itemizedlist>
1120
1121         <para> Los elementos del formulario pueden requerir metainformación
1122             adicional. Para elementos <acronym>XHTML</acronym> del formuladio,
1123             por ejemplo, puede querer especificar atributos como el class o id.
1124             Para facilitar esto hay un conjunto de métodos de acceso: </para>
1125
1126         <itemizedlist>
1127             <listitem>
1128                 <para>
1129                     <emphasis>setAttrib($name, $value)</emphasis> : añade un
1130                     atributo </para>
1131             </listitem>
1132
1133             <listitem>
1134                 <para>
1135                     <emphasis>setAttribs(array $attribs)</emphasis> : como
1136                     addAttribs(), pero sobreescribiendo </para>
1137             </listitem>
1138
1139             <listitem>
1140                 <para>
1141                     <emphasis>getAttrib($name)</emphasis> : recupera el valor de
1142                     solo un atributo </para>
1143             </listitem>
1144
1145             <listitem>
1146                 <para>
1147                     <emphasis>getAttribs()</emphasis> : recupera todos los
1148                     atributos como pares clave/valor </para>
1149             </listitem>
1150         </itemizedlist>
1151
1152         <para> La mayoría de las veces, como sea, puede simplemente acceder a
1153             ellos como propiedades de objeto, ya que
1154                 <classname>Zend_Form_Element</classname> utiliza la sobrecarga
1155             para facilitar el acceso a ellos: </para>
1156
1157         <programlisting language="php"><![CDATA[
1158 // Equivalente a $element->setAttrib('class', 'text'):
1159 $element->class = 'text;
1160 ]]></programlisting>
1161
1162         <para>Por defecto, todos los atributos son pasados al auxiliar vista
1163             usado por el elemento durante la generación, y generados como
1164             atributos de la etiqueta del elemento.</para>
1165     </sect2>
1166
1167     <sect2 id="zend.form.elements.standard">
1168         <title>Elementos Estándar</title>
1169
1170         <para>
1171             <classname>Zend_Form</classname> contiene un buen número de
1172             elementos estándar; por favor lea el capítulo <link
1173                 linkend="zend.form.standardElements">Elementos Estándar</link>
1174             para todos los detalles. </para>
1175     </sect2>
1176
1177     <sect2 id="zend.form.elements.methods">
1178         <title>Métodos de Zend_Form_Element</title>
1179
1180         <para>
1181             <classname>Zend_Form_Element</classname> tiene muchos, muchos
1182             métodos. Lo que sigue es un sumario de sus funciones, agrupados por
1183             tipo: </para>
1184
1185         <itemizedlist>
1186             <listitem>
1187                 <para>Configuración:</para>
1188                 <itemizedlist>
1189                     <listitem>
1190                         <para>
1191                             <methodname>setOptions(array $options)</methodname>
1192                         </para>
1193                     </listitem>
1194                     <listitem>
1195                         <para>
1196                             <methodname>setConfig(Zend_Config
1197                                 $config)</methodname>
1198                         </para>
1199                     </listitem>
1200                 </itemizedlist>
1201             </listitem>
1202
1203             <listitem>
1204                 <para>I18n:</para>
1205                 <itemizedlist>
1206                     <listitem>
1207                         <para>
1208                             <methodname>setTranslator(Zend_Translate_Adapter
1209                                 $translator = null)</methodname>
1210                         </para>
1211                     </listitem>
1212                     <listitem>
1213                         <para>
1214                             <methodname>getTranslator()</methodname>
1215                         </para>
1216                     </listitem>
1217                     <listitem>
1218                         <para>
1219                             <methodname>setDisableTranslator($flag)</methodname>
1220                         </para>
1221                     </listitem>
1222                     <listitem>
1223                         <para>
1224                             <methodname>translatorIsDisabled()</methodname>
1225                         </para>
1226                     </listitem>
1227                 </itemizedlist>
1228             </listitem>
1229
1230             <listitem>
1231                 <para>Propiedades:</para>
1232                 <itemizedlist>
1233                     <listitem>
1234                         <para>
1235                             <methodname>setName($name)</methodname>
1236                         </para>
1237                     </listitem>
1238                     <listitem>
1239                         <para>
1240                             <methodname>getName()</methodname>
1241                         </para>
1242                     </listitem>
1243                     <listitem>
1244                         <para>
1245                             <methodname>setValue($value)</methodname>
1246                         </para>
1247                     </listitem>
1248                     <listitem>
1249                         <para>
1250                             <methodname>getValue()</methodname>
1251                         </para>
1252                     </listitem>
1253                     <listitem>
1254                         <para>
1255                             <methodname>getUnfilteredValue()</methodname>
1256                         </para>
1257                     </listitem>
1258                     <listitem>
1259                         <para>
1260                             <methodname>setLabel($label)</methodname>
1261                         </para>
1262                     </listitem>
1263                     <listitem>
1264                         <para>
1265                             <methodname>getLabel()</methodname>
1266                         </para>
1267                     </listitem>
1268                     <listitem>
1269                         <para>
1270                             <methodname>setDescription($description)</methodname>
1271                         </para>
1272                     </listitem>
1273                     <listitem>
1274                         <para>
1275                             <methodname>getDescription()</methodname>
1276                         </para>
1277                     </listitem>
1278                     <listitem>
1279                         <para>
1280                             <methodname>setOrder($order)</methodname>
1281                         </para>
1282                     </listitem>
1283                     <listitem>
1284                         <para>
1285                             <methodname>getOrder()</methodname>
1286                         </para>
1287                     </listitem>
1288                     <listitem>
1289                         <para>
1290                             <methodname>setRequired($flag)</methodname>
1291                         </para>
1292                     </listitem>
1293                     <listitem>
1294                         <para>
1295                             <methodname>getRequired()</methodname>
1296                         </para>
1297                     </listitem>
1298                     <listitem>
1299                         <para>
1300                             <methodname>setAllowEmpty($flag)</methodname>
1301                         </para>
1302                     </listitem>
1303                     <listitem>
1304                         <para>
1305                             <methodname>getAllowEmpty()</methodname>
1306                         </para>
1307                     </listitem>
1308                     <listitem>
1309                         <para>
1310                             <methodname>setAutoInsertNotEmptyValidator($flag)</methodname>
1311                         </para>
1312                     </listitem>
1313                     <listitem>
1314                         <para>
1315                             <methodname>autoInsertNotEmptyValidator()</methodname>
1316                         </para>
1317                     </listitem>
1318                     <listitem>
1319                         <para>
1320                             <methodname>setIgnore($flag)</methodname>
1321                         </para>
1322                     </listitem>
1323                     <listitem>
1324                         <para>
1325                             <methodname>getIgnore()</methodname>
1326                         </para>
1327                     </listitem>
1328                     <listitem>
1329                         <para>
1330                             <methodname>getType()</methodname>
1331                         </para>
1332                     </listitem>
1333                     <listitem>
1334                         <para>
1335                             <methodname>setAttrib($name, $value)</methodname>
1336                         </para>
1337                     </listitem>
1338                     <listitem>
1339                         <para>
1340                             <methodname>setAttribs(array $attribs)</methodname>
1341                         </para>
1342                     </listitem>
1343                     <listitem>
1344                         <para>
1345                             <methodname>getAttrib($name)</methodname>
1346                         </para>
1347                     </listitem>
1348                     <listitem>
1349                         <para>
1350                             <methodname>getAttribs()</methodname>
1351                         </para>
1352                     </listitem>
1353                 </itemizedlist>
1354             </listitem>
1355
1356             <listitem>
1357                 <para>Cargadores y rutas de plugin:</para>
1358                 <itemizedlist>
1359                     <listitem>
1360                         <para>
1361                             <methodname>setPluginLoader(Zend_Loader_PluginLoader_Interface
1362                                 $loader, $type)</methodname>
1363                         </para>
1364                     </listitem>
1365                     <listitem>
1366                         <para>
1367                             <methodname>getPluginLoader($type)</methodname>
1368                         </para>
1369                     </listitem>
1370                     <listitem>
1371                         <para>
1372                             <methodname>addPrefixPath($prefix, $path, $type =
1373                                 null)</methodname>
1374                         </para>
1375                     </listitem>
1376                     <listitem>
1377                         <para>
1378                             <methodname>addPrefixPaths(array $spec)</methodname>
1379                         </para>
1380                     </listitem>
1381                 </itemizedlist>
1382             </listitem>
1383
1384             <listitem>
1385                 <para>Validación:</para>
1386                 <itemizedlist>
1387                     <listitem>
1388                         <para>
1389                             <methodname>addValidator($validator,
1390                                 $breakChainOnFailure = false, $options =
1391                                 array())</methodname>
1392                         </para>
1393                     </listitem>
1394                     <listitem>
1395                         <para>
1396                             <methodname>addValidators(array
1397                                 $validators)</methodname>
1398                         </para>
1399                     </listitem>
1400                     <listitem>
1401                         <para>
1402                             <methodname>setValidators(array
1403                                 $validators)</methodname>
1404                         </para>
1405                     </listitem>
1406                     <listitem>
1407                         <para>
1408                             <methodname>getValidator($name)</methodname>
1409                         </para>
1410                     </listitem>
1411                     <listitem>
1412                         <para>
1413                             <methodname>getValidators()</methodname>
1414                         </para>
1415                     </listitem>
1416                     <listitem>
1417                         <para>
1418                             <methodname>removeValidator($name)</methodname>
1419                         </para>
1420                     </listitem>
1421                     <listitem>
1422                         <para>
1423                             <methodname>clearValidators()</methodname>
1424                         </para>
1425                     </listitem>
1426                     <listitem>
1427                         <para>
1428                             <methodname>isValid($value, $context =
1429                                 null)</methodname>
1430                         </para>
1431                     </listitem>
1432                     <listitem>
1433                         <para>
1434                             <methodname>getErrors()</methodname>
1435                         </para>
1436                     </listitem>
1437                     <listitem>
1438                         <para>
1439                             <methodname>getMessages()</methodname>
1440                         </para>
1441                     </listitem>
1442                 </itemizedlist>
1443             </listitem>
1444
1445             <listitem>
1446                 <para>Filtros:</para>
1447                 <itemizedlist>
1448                     <listitem>
1449                         <para>
1450                             <methodname>addFilter($filter, $options =
1451                                 array())</methodname>
1452                         </para>
1453                     </listitem>
1454                     <listitem>
1455                         <para>
1456                             <methodname>addFilters(array $filters)</methodname>
1457                         </para>
1458                     </listitem>
1459                     <listitem>
1460                         <para>
1461                             <methodname>setFilters(array $filters)</methodname>
1462                         </para>
1463                     </listitem>
1464                     <listitem>
1465                         <para>
1466                             <methodname>getFilter($name)</methodname>
1467                         </para>
1468                     </listitem>
1469                     <listitem>
1470                         <para>
1471                             <methodname>getFilters()</methodname>
1472                         </para>
1473                     </listitem>
1474                     <listitem>
1475                         <para>
1476                             <methodname>removeFilter($name)</methodname>
1477                         </para>
1478                     </listitem>
1479                     <listitem>
1480                         <para>
1481                             <methodname>clearFilters()</methodname>
1482                         </para>
1483                     </listitem>
1484                 </itemizedlist>
1485             </listitem>
1486
1487             <listitem>
1488                 <para>Generación:</para>
1489                 <itemizedlist>
1490                     <listitem>
1491                         <para>
1492                             <methodname>setView(Zend_View_Interface $view =
1493                                 null)</methodname>
1494                         </para>
1495                     </listitem>
1496                     <listitem>
1497                         <para>
1498                             <methodname>getView()</methodname>
1499                         </para>
1500                     </listitem>
1501                     <listitem>
1502                         <para>
1503                             <methodname>addDecorator($decorator, $options =
1504                                 null)</methodname>
1505                         </para>
1506                     </listitem>
1507                     <listitem>
1508                         <para>
1509                             <methodname>addDecorators(array
1510                                 $decorators)</methodname>
1511                         </para>
1512                     </listitem>
1513                     <listitem>
1514                         <para>
1515                             <methodname>setDecorators(array
1516                                 $decorators)</methodname>
1517                         </para>
1518                     </listitem>
1519                     <listitem>
1520                         <para>
1521                             <methodname>getDecorator($name)</methodname>
1522                         </para>
1523                     </listitem>
1524                     <listitem>
1525                         <para>
1526                             <methodname>getDecorators()</methodname>
1527                         </para>
1528                     </listitem>
1529                     <listitem>
1530                         <para>
1531                             <methodname>removeDecorator($name)</methodname>
1532                         </para>
1533                     </listitem>
1534                     <listitem>
1535                         <para>
1536                             <methodname>clearDecorators()</methodname>
1537                         </para>
1538                     </listitem>
1539                     <listitem>
1540                         <para>
1541                             <methodname>render(Zend_View_Interface $view =
1542                                 null)</methodname>
1543                         </para>
1544                     </listitem>
1545                 </itemizedlist>
1546             </listitem>
1547         </itemizedlist>
1548     </sect2>
1549
1550     <sect2 id="zend.form.elements.config">
1551         <title>Configuración</title>
1552
1553         <para> El constructor de <classname>Zend_Form_Element</classname> acepta
1554             tanto una matriz de opciones como un objeto
1555                 <classname>Zend_Config</classname> conteniendo opciones, y esto
1556             puede configurarse usando <methodname>setOptions()</methodname> o
1557                 <methodname>setConfig()</methodname> . Hablando de manera
1558             general, las claves son nombradas de la siguiente manera: </para>
1559
1560         <itemizedlist>
1561             <listitem>
1562                 <para> Si 'set' + clave se refiere a un método de
1563                         <classname>Zend_Form_Element</classname> , entonces el
1564                     valor provisto será pasado a el método. </para>
1565             </listitem>
1566
1567             <listitem>
1568                 <para>De otra manera, el valor será usado para establecer un
1569                     atributo.</para>
1570             </listitem>
1571         </itemizedlist>
1572
1573         <para>Excepciones a la regla incluyen las siguientes:</para>
1574
1575         <itemizedlist>
1576             <listitem>
1577                 <para>
1578                     <methodname>prefixPath</methodname> será pasado a
1579                         <methodname>addPrefixPaths()</methodname>
1580                 </para>
1581             </listitem>
1582
1583             <listitem>
1584                 <para>Los siguientes setters no pueden establecerse de esta
1585                     manera:</para>
1586
1587                 <itemizedlist>
1588                     <listitem>
1589                         <para>
1590                             <methodname>setAttrib</methodname> (aunque
1591                                 <methodname>setAttribs</methodname>
1592                             <emphasis>funcionará</emphasis>
1593                         </para>
1594                     </listitem>
1595
1596                     <listitem>
1597                         <para>
1598                             <methodname>setConfig</methodname>
1599                         </para>
1600                     </listitem>
1601
1602                     <listitem>
1603                         <para>
1604                             <methodname>setOptions</methodname>
1605                         </para>
1606                     </listitem>
1607
1608                     <listitem>
1609                         <para>
1610                             <methodname>setPluginLoader</methodname>
1611                         </para>
1612                     </listitem>
1613
1614                     <listitem>
1615                         <para>
1616                             <methodname>setTranslator</methodname>
1617                         </para>
1618                     </listitem>
1619
1620                     <listitem>
1621                         <para>
1622                             <methodname>setView</methodname>
1623                         </para>
1624                     </listitem>
1625                 </itemizedlist>
1626             </listitem>
1627         </itemizedlist>
1628
1629         <para>Como ejemplo, aquí esta un archivo de configuración pasado para
1630             cada tipo de dato configurable:</para>
1631
1632         <programlisting language="ini"><![CDATA[
1633 [element]
1634 name = "foo"
1635 value = "foobar"
1636 label = "Foo:"
1637 order = 10
1638 required = true
1639 allowEmpty = false
1640 autoInsertNotEmptyValidator = true
1641 description = "Foo elements are for examples"
1642 ignore = false
1643 attribs.id = "foo"
1644 attribs.class = "element"
1645 ; sets 'onclick' attribute
1646 onclick = "autoComplete(this, '/form/autocomplete/element')"
1647 prefixPaths.decorator.prefix = "My_Decorator"
1648 prefixPaths.decorator.path = "My/Decorator/"
1649 disableTranslator = 0
1650 validators.required.validator = "NotEmpty"
1651 validators.required.breakChainOnFailure = true
1652 validators.alpha.validator = "alpha"
1653 validators.regex.validator = "regex"
1654 validators.regex.options.pattern = "/^[A-F].*/$"
1655 filters.ucase.filter = "StringToUpper"
1656 decorators.element.decorator = "ViewHelper"
1657 decorators.element.options.helper = "FormText"
1658 decorators.label.decorator = "Label"
1659 ]]></programlisting>
1660     </sect2>
1661
1662     <sect2 id="zend.form.elements.custom">
1663         <title>Elementos personalizados</title>
1664
1665         <para> Usted puede crear sus propios elementos personalizados
1666             simplemente extendiendo la clase
1667                 <classname>Zend_Form_Element</classname> . Las razones comunes
1668             para hacer esto incluyen: </para>
1669
1670         <itemizedlist>
1671             <listitem>
1672                 <para>Elementos que comparten validadores y/o filtros comunes
1673                 </para>
1674             </listitem>
1675
1676             <listitem>
1677                 <para>Elementos que tienen decoradores con funcionalidad
1678                     personalizada</para>
1679             </listitem>
1680         </itemizedlist>
1681
1682         <para> Hay dos métodos típicamente usados para extender un elemento:
1683                 <methodname>init()</methodname> , el cual puede usarse para
1684             añadir una lógica de inicialización personalizada a su elemento, y
1685                 <methodname>loadDefaultDecorators()</methodname> , el cual puede
1686             usarse para establecer una lista de decoradores usados por su
1687             elemento de manera predeterminada. </para>
1688
1689         <para> Como un ejemplo, digamos que todos los elementos de tipo texto en
1690             un formulario que está creando, necesitan ser filtrados con
1691                 <methodname>StringTrim</methodname> , validados con una
1692             expresión regular, y que quiere usar un decorador personalizado que
1693             ha creado para mostrarlos, 'My_Decorator_TextItem'; adicionalmente,
1694             tiene un número de atributos estándars, incluyendo 'size',
1695             'maxLength', y 'class' que quisiera especificar. Puede definir un
1696             elemento tal como sigue: </para>
1697
1698         <programlisting language="php"><![CDATA[
1699 class My_Element_Text extends Zend_Form_Element
1700 {
1701     public function init()
1702     {
1703         $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
1704              ->addFilters('StringTrim')
1705              ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
1706              ->addDecorator('TextItem')
1707              ->setAttrib('size', 30)
1708              ->setAttrib('maxLength', 45)
1709              ->setAttrib('class', 'text');
1710     }
1711 }
1712 ]]></programlisting>
1713
1714         <para>Entonces puede informar a su objeto formulario acerca del prefijo
1715             de ruta para elementos de ese tipo, y comenzar creando
1716             elementos:</para>
1717
1718         <programlisting language="php"><![CDATA[
1719 $form->addPrefixPath('My_Element', 'My/Element/', 'element')
1720      ->addElement('foo', 'text');
1721 ]]></programlisting>
1722
1723         <para> El elemento 'foo' será ahora del tipo
1724                 <methodname>My_Element_Text</methodname> , y mostrará el
1725             comportamiento que ha especificado. </para>
1726
1727         <para> Otro método que puede querer sobreescribir cuando extienda
1728                 <classname>Zend_Form_Element</classname> es el método
1729                 <methodname>loadDefaultDecorators()</methodname> . Este método
1730             carga condicionalmente un grupo de decoradores predefinidos para su
1731             elemento; puede querer sustituir su propio decorador en su clase
1732             extendida: </para>
1733
1734         <programlisting language="php"><![CDATA[
1735 class My_Element_Text extends Zend_Form_Element
1736 {
1737     public function loadDefaultDecorators()
1738     {
1739         $this->addDecorator('ViewHelper')
1740              ->addDecorator('DisplayError')
1741              ->addDecorator('Label')
1742              ->addDecorator('HtmlTag',
1743                             array('tag' => 'div', 'class' => 'element'));
1744     }
1745 }
1746 ]]></programlisting>
1747
1748         <para> Hay muchas maneras de personalizar elementos; asegúrese de leer
1749             la documentación de la <acronym>API</acronym> de
1750                 <classname>Zend_Form_Element</classname> para conocer todos los
1751             métodos disponibles. </para>
1752     </sect2>
1753 </sect1>