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

   1 <sect1 id="zend.form.elements">
   2     <title>Tworzenie elementów formularza za pomocą klasy Zend_Form_Element</title>
   3
   4     <para>
   5         Formularz składa się z elementów, które zazwyczaj odpowiadają elementom
   6         formularzy HTML. Klasa Zend_Form_Element obsługuje pojedyncze elementy
   7         formularza w takich zakresach:
   8     </para>
   9
  10     <itemizedlist>
  11         <listitem>
  12             <para>
  13                 weryfikacja (czy wysłane dane są poprawne?)
  14             </para>
  15
  16             <itemizedlist>
  17                 <listitem><para>przechowywanie kodów i komunikatów o błędach jakie
  18                 wystąpiły podczas weryfikacji</para></listitem>
  19             </itemizedlist>
  20         </listitem>
  21
  22         <listitem><para>
  23             filtrowanie (w jaki sposób element jest przygotowany do weryfikacji i wyświetlenia?)
  24         </para></listitem>
  25
  26         <listitem><para>
  27             renderowanie (jak element jest wyświetlany?)
  28         </para></listitem>
  29
  30         <listitem><para>
  31             dane meta i atrybuty (jakie dodatkowe informacje opisują element?)
  32         </para></listitem>
  33     </itemizedlist>
  34
  35     <para>
  36         Klasa bazowa <code>Zend_Form_Element</code> jest domyślnie skonfigurowana
  37         dla wielu przypadków użycia, jednak najlepiej jest rozszerzyć tę klasę
  38         aby utworzyć najczęściej używane elementy. Dodatkowo Zend Framework
  39         zawiera pewną ilość standardowych elementów XHTML; możesz o nich przeczytać <link
  40             linkend="zend.form.standardElements">w rozdziale Standardowe Elementy</link>.
  41     </para>
  42
  43     <sect2 id="zend.form.elements.loaders">
  44         <title>Ładowanie wtyczek</title>
  45
  46         <para>
  47             Klasa <code>Zend_Form_Element</code> używa klasy <link
  48                 linkend="zend.loader.pluginloader">Zend_Loader_PluginLoader</link>
  49             aby umożliwić programistom określenie ścieżek, w których znajdują
  50             się alternatywne weryfikatory, filtry i dekoratory. Każda z tych wtyczek
  51             ma przypisaną własną klasę ładującą je, a do ich modyfikacji
  52             używany jest zestaw metod dostępowych.
  53         </para>
  54
  55         <para>
  56             W metodach obsługujących ładowanie wtyczek używane są następujące
  57             typy: 'validate', 'filter' oraz 'decorator'. Wielkość liter w nazwach
  58             typów nie jest istotna.
  59         </para>
  60
  61         <para>
  62             Metody używane do obsługi ładowania wtyczek to:
  63         </para>
  64
  65         <itemizedlist>
  66             <listitem><para>
  67                 <code>setPluginLoader($loader, $type)</code>:
  68                 <code>$loader</code> jest obiektem klasy ładującej wtyczki, a
  69                 <code>$type</code> jest jednym z typów określonych wyżej. Metoda
  70                 ustawia obiekt ładujący wtyczki dla danego typu.
  71             </para></listitem>
  72
  73             <listitem><para>
  74                 <code>getPluginLoader($type)</code>: zwraca klasę ładującą wtyczkę
  75                 powiązaną z typem <code>$type</code>.
  76             </para></listitem>
  77
  78             <listitem><para>
  79                 <code>addPrefixPath($prefix, $path, $type = null)</code>: adds
  80                 a prefix/path association to the loader specified by
  81                 <code>$type</code>. If <code>$type</code> is null, it will
  82                 attempt to add the path to all loaders, by appending the prefix
  83                 with each of "_Validate", "_Filter", and "_Decorator"; and
  84                 appending the path with "Validate/", "Filter/", and
  85                 "Decorator/". If you have all your extra form element classes
  86                 under a common hierarchy, this is a convenience method for
  87                 setting the base prefix for them.
  88             </para></listitem>
  89
  90             <listitem><para>
  91                 <code>addPrefixPaths(array $spec)</code>: allows you to add
  92                 many paths at once to one or more plugin loaders. It expects
  93                 each array item to be an array with the keys 'path', 'prefix',
  94                 and 'type'.
  95             </para></listitem>
  96         </itemizedlist>
  97
  98         <para>
  99             Własne weryfikatory, filtry i dekoratory są łatwym sposobem na
 100             użycie pewnej własnej funkcjonalności w wielu formularzach.
 101         </para>
 102
 103         <example id="zend.form.elements.loaders.customLabel">
 104             <title>Własna etykieta</title>
 105
 106             <para>
 107                 One common use case for plugins is to provide replacements for
 108                 standard classes. For instance, if you want to provide a
 109                 different implementation of the 'Label' decorator -- for
 110                 instance, to always append a colon -- you could create your own
 111                 'Label' decorator with your own class prefix, and then add it to
 112                 your prefix path.
 113             </para>
 114
 115             <para>
 116                 Spróbujmy stworzyć własny dekorator dla etykiety. Damy jego klasie
 117                 przedrostek "My_Decorator", a sama klasa będzie znajdować się
 118                 w pliku "My/Decorator/Label.php".
 119             </para>
 120
 121             <programlisting role="php"><![CDATA[
 122 class My_Decorator_Label extends Zend_Form_Decorator_Abstract
 123 {
 124     protected $_placement = 'PREPEND';
 125
 126     public function render($content)
 127     {
 128         if (null === ($element = $this->getElement())) {
 129             return $content;
 130         }
 131         if (!method_exists($element, 'getLabel')) {
 132             return $content;
 133         }
 134
 135         $label = $element->getLabel() . ':';
 136
 137         if (null === ($view = $element->getView())) {
 138             return $this->renderLabel($content, $label);
 139         }
 140
 141         $label = $view->formLabel($element->getName(), $label);
 142
 143         return $this->renderLabel($content, $label);
 144     }
 145
 146     public function renderLabel($content, $label)
 147     {
 148         $placement = $this->getPlacement();
 149         $separator = $this->getSeparator();
 150
 151         switch ($placement) {
 152             case 'APPEND':
 153                 return $content . $separator . $label;
 154             case 'PREPEND':
 155             default:
 156                 return $label . $separator . $content;
 157         }
 158     }
 159 }
 160 ]]>
 161             </programlisting>
 162
 163             <para>
 164                 Now we can tell the element to use this plugin path when looking
 165                 for decorators:
 166             </para>
 167
 168             <programlisting role="php"><![CDATA[
 169 $element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
 170 ]]>
 171             </programlisting>
 172
 173             <para>
 174                 Alternately, we can do that at the form level to ensure all
 175                 decorators use this path:
 176             </para>
 177
 178             <programlisting role="php"><![CDATA[
 179 $form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
 180 ]]>
 181             </programlisting>
 182
 183             <para>
 184                 With this path added, when you add a decorator, the
 185                 'My/Decorator/' path will be searched first to see if the
 186                 decorator exists there. As a result, 'My_Decorator_Label' will
 187                 now be used when the 'Label' decorator is requested.
 188             </para>
 189         </example>
 190     </sect2>
 191
 192     <sect2 id="zend.form.elements.filters">
 193         <title>Filtry</title>
 194
 195         <para>
 196             It's often useful and/or necessary to perform some normalization on
 197             input prior to validation – for instance, you may want to strip out
 198             all HTML, but run your validations on what remains to ensure the
 199             submission is valid. Or you may want to trim empty space surrounding
 200             input so that a StringLength validator will not return a false
 201             positive. These operations may be performed using
 202             <code>Zend_Filter</code>, and <code>Zend_Form_Element</code> has
 203             support for filter chains, allowing you to specify multiple,
 204             sequential filters to utilize.  Filtering happens both during
 205             validation and when you retrieve the element value via
 206             <code>getValue()</code>:
 207         </para>
 208
 209         <programlisting role="php"><![CDATA[
 210 $filtered = $element->getValue();
 211 ]]>
 212         </programlisting>
 213
 214         <para>
 215             Filtry mogą być dodane na dwa sposoby:
 216         </para>
 217
 218         <itemizedlist>
 219             <listitem><para>
 220                 przekazanie konkretnego egzemplarza obiektu filtra
 221             </para></listitem>
 222
 223             <listitem><para>
 224                 przekazanie nazwy filtra – krótkiej lub pełnej nazwy
 225             </para></listitem>
 226         </itemizedlist>
 227
 228         <para>
 229             Zobaczmy kilka przykładów:
 230         </para>
 231
 232         <programlisting role="php"><![CDATA[
 233 // Konkretny egzemplarz obiektu filtra:
 234 $element->addFilter(new Zend_Filter_Alnum());
 235
 236 // Pełna nazwa filtra:
 237 $element->addFilter('Zend_Filter_Alnum');
 238
 239 // Krótka nazwa filtra:
 240 $element->addFilter('Alnum');
 241 $element->addFilter('alnum');
 242 ]]>
 243         </programlisting>
 244
 245         <para>
 246             Krótkie nazwy są zazwyczaj nazwą klasy filtra pozbawioną
 247             przedrostka. W domyślnym przypadku, będzie to oznaczało
 248             że pomijamy przedrostek 'Zend_Filter_'. Nie jest też konieczne
 249             aby pierwsza litera była wielka.
 250         </para>
 251
 252         <note>
 253             <title>Użycie własnych klas filtrów</title>
 254
 255             <para>
 256                 Jeśli posiadasz własny zestaw klas filtrów, możesz przekazać
 257                 klasie <code>Zend_Form_Element</code> informacje o tym za pomocą
 258                 metody <code>addPrefixPath()</code>. Na przykład jeśli posiadasz
 259                 filtry z przedostkiem 'My_Filter' możesz przekazać do klasy
 260                 <code>Zend_Form_Element</code> informację w taki sposób:
 261             </para>
 262
 263             <programlisting role="php"><![CDATA[
 264 $element->addPrefixPath('My_Filter', 'My/Filter/', 'filter');
 265 ]]>
 266             </programlisting>
 267
 268             <para>
 269                 (Zauważ że trzeci argument oznacza typ wtyczek dla którego
 270                 określamy przedrostek)
 271             </para>
 272         </note>
 273
 274         <para>
 275             Jęśli w potrzebujesz niefiltrowaną wartość użyj metody
 276             <code>getUnfilteredValue()</code>:
 277         </para>
 278
 279         <programlisting role="php"><![CDATA[
 280 $unfiltered = $element->getUnfilteredValue();
 281 ]]>
 282         </programlisting>
 283
 284         <para>
 285             Aby uzyskać więcej informacji o filtrach zobacz <link
 286                 linkend="zend.filter.introduction">dokumentację klasy Zend_Filter</link>.
 287         </para>
 288
 289         <para>
 290             Metody powiązane z filtrami to:
 291         </para>
 292
 293         <itemizedlist>
 294             <listitem><para>
 295                 <code>addFilter($nameOfFilter, array $options = null)</code>
 296             </para></listitem>
 297
 298             <listitem><para>
 299                 <code>addFilters(array $filters)</code>
 300             </para></listitem>
 301
 302             <listitem><para>
 303                 <code>setFilters(array $filters)</code> (nadpisuje wszystkie filtry)
 304             </para></listitem>
 305
 306             <listitem><para>
 307                 <code>getFilter($name)</code> (pobiera obiekt filtra)
 308             </para></listitem>
 309
 310             <listitem><para>
 311                 <code>getFilters()</code> (pobiera wszystkie filtry)
 312             </para></listitem>
 313
 314             <listitem><para>
 315                 <code>removeFilter($name)</code> (usuwa filtr)
 316             </para></listitem>
 317
 318             <listitem><para>
 319                 <code>clearFilters()</code> (usuwa wszystkie filtry)
 320             </para></listitem>
 321         </itemizedlist>
 322     </sect2>
 323
 324     <sect2 id="zend.form.elements.validators">
 325         <title>Weryfikatory</title>
 326
 327         <para>
 328             If you subscribe to the security mantra of "filter input, escape
 329             output," you'll want to validate ("filter input") your form input.
 330             In <code>Zend_Form</code>, each element includes its own validator
 331             chain, consisting of <code>Zend_Validate_*</code> validators.
 332         </para>
 333
 334         <para>
 335             Weryfikatory mogą być dodane na dwa sposoby:
 336         </para>
 337
 338         <itemizedlist>
 339             <listitem><para>
 340                 przekazanie konkretnego egzemplarza obiektu weryfikatora
 341             </para></listitem>
 342
 343             <listitem><para>
 344                 przekazanie nazwy weryfikatora – krótkiej lub pełnej nazwy
 345             </para></listitem>
 346         </itemizedlist>
 347
 348         <para>
 349             Zobaczmy kilka przykładów:
 350         </para>
 351
 352         <programlisting role="php"><![CDATA[
 353 // Konkretny egzemplarz obiektu weryfikatora:
 354 $element->addValidator(new Zend_Validate_Alnum());
 355
 356 // Pełna nazwa klasy:
 357 $element->addValidator('Zend_Validate_Alnum');
 358
 359 // Krótka nazwa weryfikatora:
 360 $element->addValidator('Alnum');
 361 $element->addValidator('alnum');
 362 ]]>
 363         </programlisting>
 364
 365         <para>
 366             Krótkie nazwy są zazwyczaj nazwą klasy weryfikatora pozbawioną
 367             przedrostka. W domyślnym przypadku, będzie to oznaczało
 368             że pomijamy przedrostek 'Zend_Validate_'. Nie jest też konieczne
 369             aby pierwsza litera była wielka.
 370         </para>
 371
 372         <note>
 373             <title>Użycie własnych klas weryfikatorów</title>
 374
 375             <para>
 376                 Jeśli posiadasz własny zestaw klas weryfikatorów, możesz przekazać
 377                 klasie <code>Zend_Form_Element</code> informacje o tym za pomocą
 378                 metody <code>addPrefixPath()</code>. Na przykład jeśli posiadasz
 379                 weryfikatory z przedostkiem 'My_Validator' możesz przekazać do klasy
 380                 <code>Zend_Form_Element</code> informację w taki sposób:
 381             </para>
 382
 383             <programlisting role="php"><![CDATA[
 384 $element->addPrefixPath('My_Validator', 'My/Validator/', 'validate');
 385 ]]>
 386             </programlisting>
 387
 388             <para>
 389                 (Zauważ że trzeci argument oznacza typ wtyczek dla którego
 390                 określamy przedrostek)
 391             </para>
 392         </note>
 393
 394         <para>
 395             If failing a particular validation should prevent later validators
 396             from firing, pass boolean <code>true</code> as the second parameter:
 397         </para>
 398
 399         <programlisting role="php"><![CDATA[
 400 $element->addValidator('alnum', true);
 401 ]]>
 402         </programlisting>
 403
 404         <para>
 405             If you are using a string name to add a validator, and the
 406             validator class accepts arguments to the constructor, you may pass
 407             these to the third parameter of <code>addValidator()</code> as an
 408             array:
 409         </para>
 410
 411         <programlisting role="php"><![CDATA[
 412 $element->addValidator('StringLength', false, array(6, 20));
 413 ]]>
 414         </programlisting>
 415
 416         <para>
 417             Arguments passed in this way should be in the order in which they
 418             are defined in the constructor. The above example will instantiate
 419             the <code>Zend_Validate_StringLenth</code> class with its
 420             <code>$min</code> and <code>$max</code> parameters:
 421         </para>
 422
 423         <programlisting role="php"><![CDATA[
 424 $validator = new Zend_Validate_StringLength(6, 20);
 425 ]]>
 426         </programlisting>
 427
 428         <note>
 429             <title>Określanie własnych komunikatów o błędach</title>
 430
 431             <para>
 432                 Some developers may wish to provide custom error messages for a
 433                 validator. <code>Zend_Form_Element::addValidator()</code>'s
 434                 <code>$options</code> argument allows you to do so by providing
 435                 the key 'messages' and setting it to an array of key/value pairs
 436                 for setting the message templates. You will need to know the
 437                 error codes of the various validation error types for the
 438                 particular validator.
 439             </para>
 440
 441             <para>
 442                 A better option is to use a <code>Zend_Translate_Adapter</code>
 443                 with your form. Error codes are automatically passed to the
 444                 adapter by the default Errors decorator; you can then specify
 445                 your own error message strings by setting up translations for
 446                 the various error codes of your validators.
 447             </para>
 448         </note>
 449
 450         <para>
 451             Możesz także ustawić wiele weryfikatorów na raz, używając metody
 452             <code>addValidators()</code>. Podstawowym sposobem użycia jest
 453             przekazanie tablicy tablic, gdzie każda z tablic posiada od 1 do 3
 454             wartości, zgodnych z wywołaniem metody <code>addValidator()</code>:
 455         </para>
 456
 457         <programlisting role="php"><![CDATA[
 458 $element->addValidators(array(
 459     array('NotEmpty', true),
 460     array('alnum'),
 461     array('stringLength', false, array(6, 20)),
 462 ));
 463 ]]>
 464         </programlisting>
 465
 466         <para>
 467             If you want to be more verbose or explicit, you can use the array
 468             keys 'validator', 'breakChainOnFailure', and 'options':
 469         </para>
 470
 471         <programlisting role="php"><![CDATA[
 472 $element->addValidators(array(
 473     array(
 474         'validator'           => 'NotEmpty',
 475         'breakChainOnFailure' => true),
 476     array('validator' => 'alnum'),
 477     array(
 478         'validator' => 'stringLength',
 479         'options'   => array(6, 20)),
 480 ));
 481 ]]>
 482         </programlisting>
 483
 484         <para>
 485             Ten przykład pokazuje w jaki sposób możesz skonfigurować
 486             weryfikatory w pliku konfiguracyjnym:
 487         </para>
 488
 489         <programlisting role="ini"><![CDATA[
 490 element.validators.notempty.validator = "NotEmpty"
 491 element.validators.notempty.breakChainOnFailure = true
 492 element.validators.alnum.validator = "Alnum"
 493 element.validators.strlen.validator = "StringLength"
 494 element.validators.strlen.options.min = 6
 495 element.validators.strlen.options.max = 20
 496 ]]>
 497         </programlisting>
 498
 499         <para>
 500             Notice that every item has a key, whether or not it needs one; this
 501             is a limitation of using configuration files -- but it also helps
 502             make explicit what the arguments are for. Just remember that any
 503             validator options must be specified in order.
 504         </para>
 505
 506         <para>
 507             Aby sprawdzić poprawność elementu przekaż wartość do metody:
 508             <code>isValid()</code>:
 509         </para>
 510
 511         <programlisting role="php"><![CDATA[
 512 if ($element->isValid($value)) {
 513     // prawidłowy
 514 } else {
 515     // nieprawidłowy
 516 }
 517 ]]>
 518         </programlisting>
 519
 520         <note>
 521             <title>Weryfikowane są przefiltrowane wartości</title>
 522
 523             <para>
 524                 <code>Zend_Form_Element::isValid()</code> filtruje wartości
 525                 za pomocą ustawionych filtrów zanim zostanie przeprowadzona
 526                 weryfikacja. Zobacz <link
 527                     linkend="zend.form.elements.filters">rozdział Filtry</link>
 528                 aby uzyskać więcej informacji.
 529             </para>
 530         </note>
 531
 532         <note>
 533             <title>Weryfikacja w kontekście</title>
 534
 535             <para>
 536                 <code>Zend_Form_Element::isValid()</code> supports an
 537                 additional argument, <code>$context</code>.
 538                 <code>Zend_Form::isValid()</code> passes the entire array of
 539                 data being processed to <code>$context</code> when validating a
 540                 form, and <code>Zend_Form_Element::isValid()</code>, in turn,
 541                 passes it to each validator.  This means you can write
 542                 validators that are aware of data passed to other form
 543                 elements. As an example, consider a standard registration form
 544                 that has fields for both password and a password confirmation;
 545                 one validation would be that the two fields match. Such a
 546                 validator might look like the following:
 547             </para>
 548
 549             <programlisting role="php"><![CDATA[
 550 class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract
 551 {
 552     const NOT_MATCH = 'notMatch';
 553
 554     protected $_messageTemplates = array(
 555         self::NOT_MATCH => 'Password confirmation does not match'
 556     );
 557
 558     public function isValid($value, $context = null)
 559     {
 560         $value = (string) $value;
 561         $this->_setValue($value);
 562
 563         if (is_array($context)) {
 564             if (isset($context['password_confirm'])
 565                 && ($value == $context['password_confirm']))
 566             {
 567                 return true;
 568             }
 569         } elseif (is_string($context) && ($value == $context)) {
 570             return true;
 571         }
 572
 573         $this->_error(self::NOT_MATCH);
 574         return false;
 575     }
 576 }
 577 ]]>
 578             </programlisting>
 579         </note>
 580
 581         <para>
 582             Validators are processed in order. Each validator is processed,
 583             unless a validator created with a true
 584             <code>breakChainOnFailure</code> value fails its validation. Be
 585             sure to specify your validators in a reasonable order.
 586         </para>
 587
 588         <para>
 589             Po nieudanej weryfikacji możesz pobrać kody i komunikaty błędów:
 590         </para>
 591
 592         <programlisting role="php"><![CDATA[
 593 $errors   = $element->getErrors();
 594 $messages = $element->getMessages();
 595 ]]>
 596         </programlisting>
 597
 598         <para>
 599             (Uwaga: komunikaty o błędach są zwracane jako asocjacyjna
 600             tablica w postaci par kod / komunikat.)
 601         </para>
 602
 603         <para>
 604             In addition to validators, you can specify that an element is
 605             required, using <code>setRequired(true)</code>. By default, this
 606             flag is false, meaning that your validator chain will be skipped if
 607             no value is passed to <code>isValid()</code>. You can modify this
 608             behavior in a number of ways:
 609         </para>
 610
 611         <itemizedlist>
 612             <listitem>
 613                 <para>
 614                     By default, when an element is required, a flag,
 615                     'allowEmpty', is also true. This means that if a value
 616                     evaluating to empty is passed to <code>isValid()</code>, the
 617                     validators will be skipped. You can toggle this flag using
 618                     the accessor <code>setAllowEmpty($flag)</code>; when the
 619                     flag is false, then if a value is passed, the validators
 620                     will still run.
 621                 </para>
 622             </listitem>
 623
 624             <listitem>
 625                 <para>
 626                     By default, if an element is required, but does not contain
 627                     a 'NotEmpty' validator, <code>isValid()</code> will add one
 628                     to the top of the stack, with the
 629                     <code>breakChainOnFailure</code> flag set. This makes the
 630                     required flag have semantic meaning: if no value is passed,
 631                     we immediately invalidate the submission and notify the
 632                     user, and prevent other validators from running on what we
 633                     already know is invalid data.
 634                 </para>
 635
 636                 <para>
 637                     If you do not want this behavior, you can turn it off by
 638                     passing a false value to
 639                     <code>setAutoInsertNotEmptyValidator($flag)</code>; this
 640                     will prevent <code>isValid()</code> from placing the
 641                     'NotEmpty' validator in the validator chain.
 642                 </para>
 643             </listitem>
 644         </itemizedlist>
 645
 646         <para>
 647             Aby uzyskać więcej informacji o weryfikatorach, zobacz <link
 648                 linkend="zend.validate.introduction">dokumentację klasy Zend_Validate</link>.
 649         </para>
 650
 651         <note>
 652             <title>Użycie klasy Zend_Form_Elements jako weryfikatora</title>
 653
 654             <para>
 655                 Klasa <code>Zend_Form_Element</code> implementuje interfejs
 656                 <code>Zend_Validate_Interface</code>, co oznacza, że element może
 657                 być także użyty jako weryfikator, w zastosowaniu nie związanym
 658                 z formularzami.
 659             </para>
 660         </note>
 661
 662         <para>
 663             Metody powiązane z weryfikatorami to:
 664         </para>
 665
 666         <itemizedlist>
 667             <listitem><para>
 668                     <code>setRequired($flag)</code> and
 669                     <code>isRequired()</code> allow you to set and retrieve the
 670                     status of the 'required' flag. When set to boolean <code>true</code>, this
 671                     flag requires that the element be in the data processed by
 672                     <code>Zend_Form</code>.
 673             </para></listitem>
 674
 675             <listitem><para>
 676                     <code>setAllowEmpty($flag)</code> and
 677                     <code>getAllowEmpty()</code> allow you to modify the
 678                     behaviour of optional elements (i.e., elements where the
 679                     required flag is false). When the 'allow empty' flag is
 680                     true, empty values will not be passed to the validator
 681                     chain.
 682             </para></listitem>
 683
 684             <listitem><para>
 685                     <code>setAutoInsertNotEmptyValidator($flag)</code> allows
 686                     you to specify whether or not a 'NotEmpty' validator will be
 687                     prepended to the validator chain when the element is
 688                     required. By default, this flag is true.
 689             </para></listitem>
 690
 691             <listitem><para>
 692                 <code>addValidator($nameOrValidator, $breakChainOnFailure = false, array $options = null)</code>
 693             </para></listitem>
 694
 695             <listitem><para>
 696                 <code>addValidators(array $validators)</code>
 697             </para></listitem>
 698
 699             <listitem><para>
 700                 <code>setValidators(array $validators)</code> (nadpisuje wszystkie weryfikatory)
 701             </para></listitem>
 702
 703             <listitem><para>
 704                 <code>getValidator($name)</code> (pobiera obiekt weryfikatora)
 705             </para></listitem>
 706
 707             <listitem><para>
 708                 <code>getValidators()</code> (pobiera wszystkie obiekty weryfikatorów)
 709             </para></listitem>
 710
 711             <listitem><para>
 712                 <code>removeValidator($name)</code> (usuwa obiekt weryfikatora)
 713             </para></listitem>
 714
 715             <listitem><para>
 716                 <code>clearValidators()</code> (usuwa wszystkie obiekty weryfikatorów)
 717             </para></listitem>
 718         </itemizedlist>
 719
 720         <sect3 id="zend.form.elements.validators.errors">
 721             <title>Custom Error Messages</title>
 722
 723             <para>
 724                 At times, you may want to specify one or more specific error
 725                 messages to use instead of the error messages generated by the
 726                 validators attached to your element. Additionally, at times you
 727                 may want to mark the element invalid yourself. As of 1.6.0, this
 728                 functionality is possible via the following methods.
 729             </para>
 730
 731             <itemizedlist>
 732                 <listitem><para>
 733                     <code>addErrorMessage($message)</code>: add an error message
 734                     to display on form validation errors. You may call this more
 735                     than once, and new messages are appended to the stack.
 736                 </para></listitem>
 737
 738                 <listitem><para>
 739                     <code>addErrorMessages(array $messages)</code>: add multiple
 740                     error messages to display on form validation errors.
 741                 </para></listitem>
 742
 743                 <listitem><para>
 744                     <code>setErrorMessages(array $messages)</code>: add multiple
 745                     error messages to display on form validation errors,
 746                     overwriting all previously set error messages.
 747                 </para></listitem>
 748
 749                 <listitem><para>
 750                     <code>getErrorMessages()</code>: retrieve the list of
 751                     custom error messages that have been defined.
 752                 </para></listitem>
 753
 754                 <listitem><para>
 755                     <code>clearErrorMessages()</code>: remove all custom error
 756                     messages that have been defined.
 757                 </para></listitem>
 758
 759                 <listitem><para>
 760                     <code>markAsError()</code>: mark the element as having
 761                     failed validation.
 762                 </para></listitem>
 763
 764                 <listitem><para>
 765                     <code>hasErrors()</code>: determine whether the element has
 766                     either failed validation or been marked as invalid.
 767                 </para></listitem>
 768
 769                 <listitem><para>
 770                     <code>addError($message)</code>: add a message to the custom
 771                     error messages stack and flag the element as invalid.
 772                 </para></listitem>
 773
 774                 <listitem><para>
 775                     <code>addErrors(array $messages)</code>: add several
 776                     messages to the custom error messages stack and flag the
 777                     element as invalid.
 778                 </para></listitem>
 779
 780                 <listitem><para>
 781                     <code>setErrors(array $messages)</code>: overwrite the
 782                     custom error messages stack with the provided messages and
 783                     flag the element as invalid.
 784                 </para></listitem>
 785             </itemizedlist>
 786
 787             <para>
 788                 All errors set in this fashion may be translated. Additionally,
 789                 you may insert the placeholder "%value%" to represent the
 790                 element value; this current element value will be substituted
 791                 when the error messages are retrieved.
 792             </para>
 793         </sect3>
 794     </sect2>
 795
 796     <sect2 id="zend.form.elements.decorators">
 797         <title>Dekoratory</title>
 798
 799         <para>
 800             One particular pain point for many web developers is the creation
 801             of the XHTML forms themselves. For each element, the developer
 802             needs to create markup for the element itself, typically a label,
 803             and, if they're being nice to their users, markup for displaying
 804             validation error messages. The more elements on the page, the less
 805             trivial this task becomes.
 806         </para>
 807
 808         <para>
 809             <code>Zend_Form_Element</code> tries to solve this issue through
 810             the use of "decorators". Decorators are simply classes that have
 811             access to the element and a method for rendering content. For more
 812             information on how decorators work, please see the section on <link
 813                 linkend="zend.form.decorators">Zend_Form_Decorator</link>.
 814         </para>
 815
 816         <para>
 817             Domyśle dekoratory używane przez klasę <code>Zend_Form_Element</code> to:
 818         </para>
 819
 820         <itemizedlist>
 821             <listitem><para>
 822                 <emphasis>ViewHelper</emphasis>: określą klasę pomocniczą widoku,
 823                 która ma być użyta do renderowania określonego elementu. Atrybut
 824                 'helper' może być użyty aby określić która klasa pomocnicza ma być
 825                 użyta. Domyślnie klasa <code>Zend_Form_Element</code> określa
 826                 domyślną klasę pomocniczą jako 'formText', jednak klasy
 827                 rozszerzające określają inne klasy pomocnicze.
 828             </para></listitem>
 829
 830             <listitem><para>
 831                 <emphasis>Errors</emphasis>: dołączą komunikaty błędów do elementu
 832                 używając klasy <code>Zend_View_Helper_FormErrors</code>. Jeśli błędów
 833                 nie ma nic nie zostaje dołączone.
 834             </para></listitem>
 835
 836             <listitem><para>
 837                 <emphasis>HtmlTag</emphasis>: otacza element i błędy znacznikiem
 838                 HTML &lt;dd&gt;.
 839             </para></listitem>
 840
 841             <listitem><para>
 842                 <emphasis>Label</emphasis>: prepends a label to the element
 843                 using <code>Zend_View_Helper_FormLabel</code>, and wraps it in a &lt;dt&gt;
 844                 tag. If no label is provided, just the definition term tag is
 845                 rendered.
 846             </para></listitem>
 847         </itemizedlist>
 848
 849         <note>
 850             <title>Domyślne dekoratory nie muszą być ładowane</title>
 851
 852             <para>
 853                 Domyślny zestaw dekoratorów jest ładowany podczas inicjowania
 854                 obiektu. Możesz to zablokować określając opcję
 855                 'disableLoadDefaultDecorators' konstruktora:
 856             </para>
 857
 858             <programlisting role="php"><![CDATA[
 859 $element = new Zend_Form_Element('foo',
 860                                  array('disableLoadDefaultDecorators' =>
 861                                       true)
 862                                  );
 863 ]]>
 864             </programlisting>
 865
 866             <para>
 867                 Ta opcja może być użyta równolegle wraz z dowolnymi innymi
 868                 opcjami jakie przekażesz, zarówno w postaci tablicy opcji jak
 869                 i  obiektu <code>Zend_Config</code>.
 870             </para>
 871         </note>
 872
 873         <para>
 874             Z tego względu, że kolejność w jakiej rejestrowane są dekoratory ma
 875             znaczenie -- dekoratory są uruchamiane w takiej kolejności w jakiej
 876             zostały zarejestrowane -- musisz się upewnić, że rejestrujesz
 877             je w odpowiedniej kolejności lub użyć opcji pozwalającej na
 878             zarejestrowanie dekoratora w konkretnej pozycji. Poniżej jako
 879             przykład został zamieszczony przykładowy kod, który rejestruje
 880             domyślne dekoratory:
 881         </para>
 882
 883         <programlisting role="php"><![CDATA[
 884 $this->addDecorators(array(
 885     array('ViewHelper'),
 886     array('Errors'),
 887     array('HtmlTag', array('tag' => 'dd')),
 888     array('Label', array('tag' => 'dt')),
 889 ));
 890 ]]>
 891         </programlisting>
 892
 893         <para>
 894             The initial content is created by the 'ViewHelper' decorator, which
 895             creates the form element itself. Next, the 'Errors' decorator
 896             fetches error messages from the element, and, if any are present,
 897             passes them to the 'FormErrors' view helper to render.  The next
 898             decorator, 'HtmlTag', wraps the element and errors in an HTML
 899             &lt;dd&gt; tag.  Finally, the last decorator, 'label', retrieves
 900             the element's label and passes it to the 'FormLabel' view helper,
 901             wrapping it in an HTML &lt;dt&gt; tag; the value is prepended to
 902             the content by default. The resulting output looks basically like
 903             this:
 904         </para>
 905
 906         <programlisting role="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 </dd>
 914 ]]>
 915         </programlisting>
 916
 917         <para>
 918             Aby uzyskać więcej informacji o dekoratorach, zobacz <link
 919                 linkend="zend.form.decorators">dokumentację klasy Zend_Form_Decorator</link>.
 920         </para>
 921
 922         <note>
 923             <title>Użycie wielu dekoratorów tego samego typu</title>
 924
 925             <para>
 926                 Internally, <code>Zend_Form_Element</code> uses a decorator's
 927                 class as the lookup mechanism when retrieving decorators. As a
 928                 result, you cannot register multiple decorators of the same
 929                 type; subsequent decorators will simply overwrite those that
 930                 existed before.
 931             </para>
 932
 933             <para>
 934                 To get around this, you can use <emphasis>aliases</emphasis>.
 935                 Instead of passing a decorator or decorator name as the first
 936                 argument to <code>addDecorator()</code>, pass an array with a
 937                 single element, with the alias pointing to the decorator object
 938                 or name:
 939             </para>
 940
 941             <programlisting role="php"><![CDATA[
 942 // Alias dla 'FooBar':
 943 $element->addDecorator(array('FooBar' => 'HtmlTag'),
 944                        array('tag' => 'div'));
 945
 946 // Pobieramy dekorator:
 947 $decorator = $element->getDecorator('FooBar');
 948 ]]>
 949             </programlisting>
 950
 951             <para>
 952                 Do metod <code>addDecorators()</code> oraz
 953                 <code>setDecorators()</code> musisz przekazać opcję
 954                 'decorator' znajdującą się w tablicy reprezentującej dekorator.
 955             </para>
 956
 957             <programlisting role="php"><![CDATA[
 958 // Dodanie dwóch dekoratorów 'HtmlTag', ustawiając nazwę jednego z nich na 'FooBar':
 959 $element->addDecorators(
 960     array('HtmlTag', array('tag' => 'div')),
 961     array(
 962         'decorator' => array('FooBar' => 'HtmlTag'),
 963         'options' => array('tag' => 'dd')
 964     ),
 965 );
 966
 967 // I pobranie ich póżniej:
 968 $htmlTag = $element->getDecorator('HtmlTag');
 969 $fooBar  = $element->getDecorator('FooBar');
 970 ]]>
 971             </programlisting>
 972         </note>
 973
 974         <para>
 975             Metody powiązane z dekoratorami to:
 976         </para>
 977
 978         <itemizedlist>
 979             <listitem><para>
 980                 <code>addDecorator($nameOrDecorator, array $options = null)</code>
 981             </para></listitem>
 982
 983             <listitem><para>
 984                 <code>addDecorators(array $decorators)</code>
 985             </para></listitem>
 986
 987             <listitem><para>
 988                 <code>setDecorators(array $decorators)</code> (nadpisuje wszystkie dekoratory)
 989             </para></listitem>
 990
 991             <listitem><para>
 992                 <code>getDecorator($name)</code> (pobiera obiekt dekoratora)
 993             </para></listitem>
 994
 995             <listitem><para>
 996                 <code>getDecorators()</code> (pobiera wszystkie dekoratory)
 997             </para></listitem>
 998
 999             <listitem><para>
1000                 <code>removeDecorator($name)</code> (usuwa dekorator)
1001             </para></listitem>
1002
1003             <listitem><para>
1004                 <code>clearDecorators()</code> (usuwa wszystkie dekoratory)
1005             </para></listitem>
1006         </itemizedlist>
1007     </sect2>
1008
1009     <sect2 id="zend.form.elements.metadata">
1010         <title>Dane meta i atrybuty</title>
1011
1012         <para>
1013             <code>Zend_Form_Element</code> obsługuje wiele atrybutów i danych
1014             meta dla elementów. Te atrybuty to:
1015         </para>
1016
1017         <itemizedlist>
1018             <listitem><para>
1019                 <emphasis>name</emphasis>: nazwa elementu. Używa metod dostępowych
1020                 <code>setName()</code> oraz <code>getName()</code>.
1021             </para></listitem>
1022
1023             <listitem><para>
1024                 <emphasis>label</emphasis>: etykieta elementu. Używa metod dostępowych
1025                 <code>setLabel()</code> oraz <code>getLabel()</code>.
1026             </para></listitem>
1027
1028             <listitem><para>
1029                 <emphasis>order</emphasis>: pozycja w której element ma być wstawiony
1030                 w formularzu. Używa metod dostępowych <code>setOrder()</code> oraz
1031                 <code>getOrder()</code>.
1032             </para></listitem>
1033
1034             <listitem><para>
1035                 <emphasis>value</emphasis>: obecna wartość elementu. Używa metod
1036                 dostępowych <code>setValue()</code> oraz <code>getValue()</code>.
1037             </para></listitem>
1038
1039             <listitem><para>
1040                 <emphasis>description</emphasis>: opis elementu; zazwyczaj używane
1041                 do utworzenia
1042                 often used to provide tooltip or javascript contextual hinting
1043                 describing the purpose of the element. Używa metod dostępowych
1044                 <code>setDescription()</code> oraz <code>getDescription()</code>.
1045             </para></listitem>
1046
1047             <listitem><para>
1048                 <emphasis>required</emphasis>: flag indicating whether or not
1049                 the element is required when performing form validation. Uses
1050                 the <code>setRequired()</code> and <code>getRequired()</code>
1051                 accessors. This flag is false by default.
1052             </para></listitem>
1053
1054             <listitem><para>
1055                 <emphasis>allowEmpty</emphasis>: flag indicating whether or not
1056                 a non-required (optional) element should attempt to validate
1057                 empty values. When true, and the required flag is false, empty
1058                 values are not passed to the validator chain, and presumed true.
1059                 Uses the <code>setAllowEmpty()</code> and <code>getAllowEmpty()</code>
1060                 accessors. This flag is true by default.
1061             </para></listitem>
1062
1063             <listitem><para>
1064                 <emphasis>autoInsertNotEmptyValidator</emphasis>: flag
1065                 indicating whether or not to insert a 'NotEmpty' validator when
1066                 the element is required. By default, this flag is true. Set the
1067                 flag with <code>setAutoInsertNotEmptyValidator($flag)</code> and
1068                 determine the value with
1069                 <code>autoInsertNotEmptyValidator()</code>.
1070             </para></listitem>
1071         </itemizedlist>
1072
1073         <para>
1074             Elementy formularzy mogą wymagać dodatkowych danych meta. Przykładowo
1075             dla elementów formularzy XHTML możesz chcieć określić takie atrybuty
1076             jak 'class' czy 'id'. Do obsługi tego istnieje kilka metod dostępowych:
1077         </para>
1078
1079         <itemizedlist>
1080             <listitem><para>
1081                 <emphasis>setAttrib($name, $value)</emphasis>: dodaje atrybut
1082             </para></listitem>
1083
1084             <listitem><para>
1085                 <emphasis>setAttribs(array $attribs)</emphasis>: tak jak metoda
1086                 addAttribs(), ale nadpisuje atrybuty
1087             </para></listitem>
1088
1089             <listitem><para>
1090                 <emphasis>getAttrib($name)</emphasis>: pobiera wartość jednego atrybutu
1091             </para></listitem>
1092
1093             <listitem><para>
1094                 <emphasis>getAttribs()</emphasis>: pobiera wszystkie atrybuty w
1095                 postaci par klucz/wartość
1096             </para></listitem>
1097
1098         </itemizedlist>
1099
1100         <para>
1101             Most of the time, however, you can simply access them as object
1102             properties, as <code>Zend_Form_Element</code> utilizes overloading
1103             to facilitate access to them:
1104         </para>
1105
1106         <programlisting role="php"><![CDATA[
1107 // Odpowiednik metody $element->setAttrib('class', 'text'):
1108 $element->class = 'text;
1109 ]]>
1110         </programlisting>
1111
1112         <para>
1113             By default, all attributes are passed to the view helper used by
1114             the element during rendering, and rendered as HTML attributes of
1115             the element tag.
1116         </para>
1117     </sect2>
1118
1119     <sect2 id="zend.form.elements.standard">
1120         <title>Standardowe elementy</title>
1121
1122         <para>
1123             Komponent <code>Zend_Form</code> posiada duży zestaw standardowych
1124             elementów; przeczytaj rozdział
1125             <link linkend="zend.form.standardElements">Standardowe Elementy</link>
1126             aby poznać więcej szczegółów.
1127         </para>
1128     </sect2>
1129
1130     <sect2 id="zend.form.elements.methods">
1131         <title>Metody klasy Zend_Form_Element</title>
1132
1133         <para>
1134             Klasa <code>Zend_Form_Element</code> posiada bardzo dużo metod. Poniżej
1135             zamieszczono podsumowanie ich sygnatur, pogrupowanych na podstawie typu:
1136         </para>
1137
1138         <itemizedlist>
1139             <listitem><para>Konfiguracja:</para>
1140                 <itemizedlist>
1141                     <listitem><para><code>setOptions(array $options)</code></para></listitem>
1142                     <listitem><para><code>setConfig(Zend_Config $config)</code></para></listitem>
1143                 </itemizedlist>
1144             </listitem>
1145
1146             <listitem><para>I18N:</para>
1147                 <itemizedlist>
1148                     <listitem><para><code>setTranslator(Zend_Translate_Adapter $translator = null)</code></para></listitem>
1149                     <listitem><para><code>getTranslator()</code></para></listitem>
1150                     <listitem><para><code>setDisableTranslator($flag)</code></para></listitem>
1151                     <listitem><para><code>translatorIsDisabled()</code></para></listitem>
1152                 </itemizedlist>
1153             </listitem>
1154
1155             <listitem><para>Właściwości:</para>
1156                 <itemizedlist>
1157                     <listitem><para><code>setName($name)</code></para></listitem>
1158                     <listitem><para><code>getName()</code></para></listitem>
1159                     <listitem><para><code>setValue($value)</code></para></listitem>
1160                     <listitem><para><code>getValue()</code></para></listitem>
1161                     <listitem><para><code>getUnfilteredValue()</code></para></listitem>
1162                     <listitem><para><code>setLabel($label)</code></para></listitem>
1163                     <listitem><para><code>getLabel()</code></para></listitem>
1164                     <listitem><para><code>setDescription($description)</code></para></listitem>
1165                     <listitem><para><code>getDescription()</code></para></listitem>
1166                     <listitem><para><code>setOrder($order)</code></para></listitem>
1167                     <listitem><para><code>getOrder()</code></para></listitem>
1168                     <listitem><para><code>setRequired($flag)</code></para></listitem>
1169                     <listitem><para><code>getRequired()</code></para></listitem>
1170                     <listitem><para><code>setAllowEmpty($flag)</code></para></listitem>
1171                     <listitem><para><code>getAllowEmpty()</code></para></listitem>
1172                     <listitem><para><code>setAutoInsertNotEmptyValidator($flag)</code></para></listitem>
1173                     <listitem><para><code>autoInsertNotEmptyValidator()</code></para></listitem>
1174                     <listitem><para><code>setIgnore($flag)</code></para></listitem>
1175                     <listitem><para><code>getIgnore()</code></para></listitem>
1176                     <listitem><para><code>getType()</code></para></listitem>
1177                     <listitem><para><code>setAttrib($name, $value)</code></para></listitem>
1178                     <listitem><para><code>setAttribs(array $attribs)</code></para></listitem>
1179                     <listitem><para><code>getAttrib($name)</code></para></listitem>
1180                     <listitem><para><code>getAttribs()</code></para></listitem>
1181                 </itemizedlist>
1182             </listitem>
1183
1184             <listitem><para>Ładowanie wtyczek i ścieżki:</para>
1185                 <itemizedlist>
1186                     <listitem><para><code>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader, $type)</code></para></listitem>
1187                     <listitem><para><code>getPluginLoader($type)</code></para></listitem>
1188                     <listitem><para><code>addPrefixPath($prefix, $path, $type = null)</code></para></listitem>
1189                     <listitem><para><code>addPrefixPaths(array $spec)</code></para></listitem>
1190                 </itemizedlist>
1191             </listitem>
1192
1193             <listitem><para>Weryfikacja:</para>
1194                 <itemizedlist>
1195                     <listitem><para><code>addValidator($validator, $breakChainOnFailure = false, $options = array())</code></para></listitem>
1196                     <listitem><para><code>addValidators(array $validators)</code></para></listitem>
1197                     <listitem><para><code>setValidators(array $validators)</code></para></listitem>
1198                     <listitem><para><code>getValidator($name)</code></para></listitem>
1199                     <listitem><para><code>getValidators()</code></para></listitem>
1200                     <listitem><para><code>removeValidator($name)</code></para></listitem>
1201                     <listitem><para><code>clearValidators()</code></para></listitem>
1202                     <listitem><para><code>isValid($value, $context = null)</code></para></listitem>
1203                     <listitem><para><code>getErrors()</code></para></listitem>
1204                     <listitem><para><code>getMessages()</code></para></listitem>
1205                 </itemizedlist>
1206             </listitem>
1207
1208             <listitem><para>Filtrowanie:</para>
1209                 <itemizedlist>
1210                     <listitem><para><code>addFilter($filter, $options = array())</code></para></listitem>
1211                     <listitem><para><code>addFilters(array $filters)</code></para></listitem>
1212                     <listitem><para><code>setFilters(array $filters)</code></para></listitem>
1213                     <listitem><para><code>getFilter($name)</code></para></listitem>
1214                     <listitem><para><code>getFilters()</code></para></listitem>
1215                     <listitem><para><code>removeFilter($name)</code></para></listitem>
1216                     <listitem><para><code>clearFilters()</code></para></listitem>
1217                 </itemizedlist>
1218             </listitem>
1219
1220             <listitem><para>Renderowanie:</para>
1221                 <itemizedlist>
1222                     <listitem><para><code>setView(Zend_View_Interface $view = null)</code></para></listitem>
1223                     <listitem><para><code>getView()</code></para></listitem>
1224                     <listitem><para><code>addDecorator($decorator, $options = null)</code></para></listitem>
1225                     <listitem><para><code>addDecorators(array $decorators)</code></para></listitem>
1226                     <listitem><para><code>setDecorators(array $decorators)</code></para></listitem>
1227                     <listitem><para><code>getDecorator($name)</code></para></listitem>
1228                     <listitem><para><code>getDecorators()</code></para></listitem>
1229                     <listitem><para><code>removeDecorator($name)</code></para></listitem>
1230                     <listitem><para><code>clearDecorators()</code></para></listitem>
1231                     <listitem><para><code>render(Zend_View_Interface $view = null)</code></para></listitem>
1232                 </itemizedlist>
1233             </listitem>
1234         </itemizedlist>
1235     </sect2>
1236
1237     <sect2 id="zend.form.elements.config">
1238         <title>Konfiguracja</title>
1239
1240         <para>
1241             Konstruktor klasy <code>Zend_Form_Element</code>przyjmuje w
1242             parametrze tablicę opcji lub obiekt <code>Zend_Config</code>
1243             zawierający pcje. Klasa może być także skonfigurowana za pomocą
1244             metod <code>setOptions()</code> oraz <code>setConfig()</code>.
1245             Generalnie klucze nazwane są w taki sposób:
1246         </para>
1247
1248         <itemizedlist>
1249             <listitem><para>
1250                 If 'set' + key refers to a <code>Zend_Form_Element</code>
1251                 method, then the value provided will be passed to that method.
1252             </para></listitem>
1253
1254             <listitem><para>
1255                 Otherwise, the value will be used to set an attribute.
1256             </para></listitem>
1257         </itemizedlist>
1258
1259         <para>
1260             Oto wyjątki od tej zasady:
1261         </para>
1262
1263         <itemizedlist>
1264             <listitem><para>
1265                 <code>prefixPath</code> will be passed to
1266                 <code>addPrefixPaths()</code>
1267             </para></listitem>
1268
1269             <listitem>
1270                 <para>
1271                     The following setters cannot be set in this way:
1272                 </para>
1273
1274                 <itemizedlist>
1275                     <listitem><para>
1276                             <code>setAttrib</code> (though
1277                             <code>setAttribs</code> <emphasis>will</emphasis>
1278                             work)
1279                     </para></listitem>
1280
1281                     <listitem><para><code>setConfig</code></para></listitem>
1282
1283                     <listitem><para><code>setOptions</code></para></listitem>
1284
1285                     <listitem><para><code>setPluginLoader</code></para></listitem>
1286
1287                     <listitem><para><code>setTranslator</code></para></listitem>
1288
1289                     <listitem><para><code>setView</code></para></listitem>
1290                 </itemizedlist>
1291             </listitem>
1292         </itemizedlist>
1293
1294         <para>
1295             As an example, here is a config file that passes configuration for
1296             every type of configurable data:
1297         </para>
1298
1299         <programlisting role="ini"><![CDATA[
1300 [element]
1301 name = "foo"
1302 value = "foobar"
1303 label = "Foo:"
1304 order = 10
1305 required = true
1306 allowEmpty = false
1307 autoInsertNotEmptyValidator = true
1308 description = "Foo elements are for examples"
1309 ignore = false
1310 attribs.id = "foo"
1311 attribs.class = "element"
1312 ; ustawia atrybut 'onclick'
1313 onclick = "autoComplete(this, '/form/autocomplete/element')"
1314 prefixPaths.decorator.prefix = "My_Decorator"
1315 prefixPaths.decorator.path = "My/Decorator/"
1316 disableTranslator = 0
1317 validators.required.validator = "NotEmpty"
1318 validators.required.breakChainOnFailure = true
1319 validators.alpha.validator = "alpha"
1320 validators.regex.validator = "regex"
1321 validators.regex.options.pattern = "/^[A-F].*/$"
1322 filters.ucase.filter = "StringToUpper"
1323 decorators.element.decorator = "ViewHelper"
1324 decorators.element.options.helper = "FormText"
1325 decorators.label.decorator = "Label"
1326 ]]>
1327         </programlisting>
1328     </sect2>
1329
1330     <sect2 id="zend.form.elements.custom">
1331         <title>Własne elementy</title>
1332
1333         <para>
1334             Możesz tworzyć własne elementy po prostu rozszerzając klasę
1335             <code>Zend_Form_Element</code>. Powodami aby to zrobić mogą być:
1336         </para>
1337
1338         <itemizedlist>
1339             <listitem><para>
1340                 Elements that share common validators and/or filters
1341             </para></listitem>
1342
1343             <listitem><para>
1344                 Elements that have custom decorator functionality
1345             </para></listitem>
1346         </itemizedlist>
1347
1348         <para>
1349             There are two methods typically used to extend an element:
1350             <code>init()</code>, which can be used to add custom initialization
1351             logic to your element, and <code>loadDefaultDecorators()</code>,
1352             which can be used to set a list of default decorators used by your
1353             element.
1354         </para>
1355
1356         <para>
1357             As an example, let's say that all text elements in a form you are
1358             creating need to be filtered with <code>StringTrim</code>,
1359             validated with a common regular expression, and that you want to
1360             use a custom decorator you've created for displaying them,
1361             'My_Decorator_TextItem'; additionally, you have a number of standard
1362             attributes, including 'size', 'maxLength', and 'class' you wish to
1363             specify. You could define such an element as follows:
1364         </para>
1365
1366         <programlisting role="php"><![CDATA[
1367 class My_Element_Text extends Zend_Form_Element
1368 {
1369     public function init()
1370     {
1371         $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
1372              ->addFilters('StringTrim')
1373              ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
1374              ->addDecorator('TextItem')
1375              ->setAttrib('size', 30)
1376              ->setAttrib('maxLength', 45)
1377              ->setAttrib('class', 'text');
1378     }
1379 }
1380 ]]>
1381         </programlisting>
1382
1383         <para>
1384             You could then inform your form object about the prefix path for
1385             such elements, and start creating elements:
1386         </para>
1387
1388         <programlisting role="php"><![CDATA[<?php
1389 $form->addPrefixPath('My_Element', 'My/Element/', 'element')
1390      ->addElement('foo', 'text');
1391 ]]>
1392         </programlisting>
1393
1394         <para>
1395             The 'foo' element will now be of type <code>My_Element_Text</code>,
1396             and exhibit the behaviour you've outlined.
1397         </para>
1398
1399         <para>
1400             Another method you may want to override when extending
1401             <code>Zend_Form_Element</code> is the
1402             <code>loadDefaultDecorators()</code> method. This method
1403             conditionally loads a set of default decorators for your element;
1404             you may wish to substitute your own decorators in your extending
1405             class:
1406         </para>
1407
1408         <programlisting role="php"><![CDATA[
1409 class My_Element_Text extends Zend_Form_Element
1410 {
1411     public function loadDefaultDecorators()
1412     {
1413         $this->addDecorator('ViewHelper')
1414              ->addDecorator('DisplayError')
1415              ->addDecorator('Label')
1416              ->addDecorator('HtmlTag',
1417                             array('tag' => 'div', 'class' => 'element'));
1418     }
1419 }
1420 ]]>
1421         </programlisting>
1422
1423         <para>
1424             There are many ways to customize elements; be sure to read the API
1425             documentation of <code>Zend_Form_Element</code> to know all the
1426             methods available.
1427         </para>
1428     </sect2>
1429 </sect1>
1430 <!--
1431 vim:se ts=4 sw=4 tw=80 et:
1432 -->