[MANUAL] English:
[zend.git] / documentation / manual / pl / module_specs / Zend_Form-QuickStart.xml
blobdfc9cad08cc398c4ddd7cf5d8abfe71cc22fef1d
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- EN-Revision: 21614 -->
3 <!-- Reviewed: no -->
4 <sect1 id="zend.form.quickstart">
5     <title>Szybki start z Zend_Form</title>
7     <para>
8         Ten przewodnik opisuje podstawy tworzenia, weryfikacji oraz
9         renderowania formularzy za pomocą komponentu <classname>Zend_Form</classname>.
10     </para>
12     <sect2 id="zend.form.quickstart.create">
13         <title>Tworzenie obiektu formularza</title>
15         <para>
16             Tworzenie obiektu formularza jest bardzo proste: należy, po prostu, utworzyć
17             egzemplarz klasy <classname>Zend_Form</classname>:
18         </para>
20         <programlisting language="php"><![CDATA[
21 $form = new Zend_Form;
22 ]]>
23         </programlisting>
25         <para>
26             W zaawansowanych przypadkach można rozszerzyć klasę
27             <classname>Zend_Form</classname>, ale dla prostych formularzy wystarczy utworzenie
28             i skonfigurowanie formularza za pomocą obiektu <classname>Zend_Form</classname>.
29         </para>
31         <para>
32             Dla określenia akcji oraz metody wywołania formularza, można
33             użyć metod dostępowych <methodname>setAction()</methodname> oraz
34             <methodname>setMethod()</methodname>:
35         </para>
37         <programlisting language="php"><![CDATA[
38 $form->setAction('/resource/process')
39      ->setMethod('post');
40 ]]>
41         </programlisting>
43         <para>
44             Powyższy kod ustawia akcję formularza na adres <acronym>URL</acronym>
45             "<filename>/resource/process</filename>" oraz metodę wykonania formularza na
46             <acronym>HTTP</acronym> <acronym>POST</acronym>.
47             Będzie to wzięte pod uwagę podczas renderowania formularza.
48         </para>
50         <para>
51             Można ustawić dodatkowe atrybuty dla znacznika
52             <emphasis>&lt;form&gt;</emphasis> używając metod <methodname>setAttrib()</methodname>
53             lub <methodname>setAttribs()</methodname>. Przykładowo aby ustawić identyfikator,
54             należy ustawić atrybut "<property>id</property>":
55         </para>
57         <programlisting language="php"><![CDATA[
58 $form->setAttrib('id', 'login');
59 ]]>
60         </programlisting>
61     </sect2>
63     <sect2 id="zend.form.quickstart.elements">
64         <title>Dodawanie elementów do formularza</title>
66         <para>
67             Formularz jest bezużyteczny jeśli nie posiada elementów.
68             Komponent <classname>Zend_Form</classname> posiada kilkanaście domyślnych
69             elementów które mogą być renderowane do postaci <acronym>XHTML</acronym> za pomocą
70             klas pomocniczych <classname>Zend_View</classname>. Te elementy to:
71         </para>
73         <itemizedlist>
74             <listitem><para>
75                 button (przycisk)
76             </para></listitem>
78             <listitem><para>
79                 checkbox (pole wyboru lub wiele pól za pomocą multiCheckbox)
80             </para></listitem>
82             <listitem><para>
83                 hidden (pole ukryte)
84             </para></listitem>
86             <listitem><para>
87                 image (obrazek)
88             </para></listitem>
90             <listitem><para>
91                 password (hasło)
92             </para></listitem>
94             <listitem><para>
95                 radio (pole opcji)
96             </para></listitem>
98             <listitem><para>
99                 reset (przycisk resetujący)
100             </para></listitem>
102             <listitem><para>
103                 select (lista zwykła oraz lista wielokrotnego wyboru)
104             </para></listitem>
106             <listitem><para>
107                 submit (przycisk wysyłający)
108             </para></listitem>
110             <listitem><para>
111                 text (pole tekstowe)
112             </para></listitem>
114             <listitem><para>
115                 textarea (wieloliniowe pole tekstowe)
116             </para></listitem>
117         </itemizedlist>
119         <para>
120             Istnieją dwie możliwości dodania elementów do formularza: utworzenie
121             egzemplarza konkretnego elementu i przekazanie go do obiektu formularza lub
122             po prostu przekazanie typu elementu i pozwolenie obiektowi
123             <classname>Zend_Form</classname> na automatyczne utworzenie egzemplarzy
124             obiektów określonego typu.
125         </para>
127         <para>
128             Kilka przykładów:
129         </para>
131         <programlisting language="php"><![CDATA[
132 // Utworzenie egzemplarza elementu i przekazanie go do obiektu formularza:
133 $form->addElement(new Zend_Form_Element_Text('username'));
135 // Przekazanie typu elementu do obiektu:
136 $form->addElement('text', 'username');
138         </programlisting>
140         <para>
141             Domyślnie, elementy te nie posiadają filtrów ani walidatorów.
142             Oznacza to że należy samodzielnie skonfigurować dla nich
143             walidatory i opcjonalnie filtry. Można to zrobić (a) przed
144             przekazaniem elementu do formularza, (b) za pomocą opcji
145             konfiguracyjnych przekazanych podczas tworzenia elementu poprzez
146             obiekt <classname>Zend_Form</classname> lub (c) pobierając istniejący element
147             z obiektu formularza i konfigurując go.
148         </para>
150         <para>
151             Najpierw należy przyjrzeć się tworzeniu walidatorów dla konkretnego
152             egzemplarza elementu. Można przekazać obiekt
153             <classname>Zend_Validate_*</classname> lub nazwę walidatora który ma zostać
154             użyty:
155         </para>
157         <programlisting language="php"><![CDATA[
158 $username = new Zend_Form_Element_Text('username');
160 // Przekazanie obiektu Zend_Validate_*:
161 $username->addValidator(new Zend_Validate_Alnum());
163 // Przekazanie nazwy walidatora:
164 $username->addValidator('alnum');
166         </programlisting>
168         <para>
169             Dla drugiego sposobu, można przekazać w trzecim parametrze metody
170             tablicę z argumentami konstruktora wybranego walidatora. 
171         </para>
173         <programlisting language="php"><![CDATA[
174 // Przekazanie wzoru
175 $username->addValidator('regex', false, array('/^[a-z]/i'));
177         </programlisting>
179         <para>
180             (Drugi parametr jest używany aby określić czy niepowodzenie w
181             weryfikacji ma przerwać następne weryfikacje czy nie; domyślnie
182             ma wartość <constant>FALSE</constant>.)
183         </para>
185         <para>
186             Można także określić element jako wymagany. Aby to osiągnąć należy
187             użyć metody dostępowej lub przekazać opcję podczas tworzenia
188             elementu. Oto pierwszy sposób:
189         </para>
191         <programlisting language="php"><![CDATA[
192 // Ustawienie elementu jako wymaganego:
193 $username->setRequired(true);
195         </programlisting>
197         <para>
198             Gdy element jest wymagany, dodawany jest walidator 'NotEmpty' na
199             sam początek łańcucha walidatorów, dzięki czemu można być pewnym,
200             że element będzie posiadał wartość.
201         </para>
203         <para>
204             Filtry są rejestrowane w taki sam sposób jak walidatory. Aby
205             pokazać jak działają, można dodać filtr zamieniający znaki na małe
206             litery:
207         </para>
209         <programlisting language="php"><![CDATA[
210 $username->addFilter('StringtoLower');
212         </programlisting>
214         <para>
215             Finalnie konfiguracja elementu może wyglądać tak:
216         </para>
218         <programlisting language="php"><![CDATA[
219 $username->addValidator('alnum')
220          ->addValidator('regex', false, array('/^[a-z]/'))
221          ->setRequired(true)
222          ->addFilter('StringToLower');
224 // lub bardziej zwięźle:
225 $username->addValidators(array('alnum',
226         array('regex', false, '/^[a-z]/i')
227     ))
228     ->setRequired(true)
229     ->addFilters(array('StringToLower'));
231         </programlisting>
233         <para>
234             Tworzenie obiektu dla każdego z elementów formularza może być
235             nieco kłopotliwe. Można spróbować użyć sposobu (b) przedstawionego
236             wyżej. Podczas tworzenia nowego elementu metodą
237             <methodname>Zend_Form::addElement()</methodname> jako fabryki, można
238             opcjonalnie przekazać również opcje konfiguracyjne. Obejmuje to także
239             konfigurację filtrów i walidatorów. Aby to zrobić można użyć kodu:
240         </para>
242         <programlisting language="php"><![CDATA[
243 $form->addElement('text', 'username', array(
244     'validators' => array(
245         'alnum',
246         array('regex', false, '/^[a-z]/i')
247     ),
248     'required' => true,
249     'filters'  => array('StringToLower'),
252         </programlisting>
254         <note>
255             <para>
256                 Jeśli w kilku miejscach konfigurowane są elementy za pomocą tych samych
257                 opcji, można rozważyć stworzenie własnej klasy rozszerzającej
258                 klasę <classname>Zend_Form_Element</classname> i następnie użycie tej klasy do
259                 tworzenia własnych elementów. Może to oszczędzić nieco pracy.
260             </para>
261         </note>
262     </sect2>
264     <sect2 id="zend.form.quickstart.render">
265         <title>Renderowanie formularza</title>
267         <para>
268             Renderowanie formularza jest proste. Większość elementów używa do
269             tego klas pomocniczych <classname>Zend_View</classname>, więc potrzebny będzie
270             do tego także obiekt widoku. Istnieją dwie możliwości: użycie metody
271             formularza render() lub po prostu wyświetlenie formularza za pomocą
272             konstrukcji echo.
273         </para>
275         <programlisting language="php"><![CDATA[
276 // Jawnie wywołanie metody render() i przekazanie opcjonalnego obiektu widoku:
277 echo $form->render($view);
279 // Zakładając że obiekt widoku został wcześniej ustawiony za pomocą setView():
280 echo $form;
282         </programlisting>
284         <para>
285             Domyślnie obiekty <classname>Zend_Form</classname> oraz
286             <classname>Zend_Form_Element</classname> używają obiektu widoku zainicjowanego
287             w obiekcie <classname>ViewRenderer</classname>, co oznacza, że nie trzeba go
288             ręcznie ustawiać dla wzorca MVC Zend Framework. Renderowanie
289             formularza w skrypcie widoku jest wtedy bardzo proste:
290         </para>
292         <programlisting language="php"><![CDATA[
293 <? echo $this->form ?>
295         </programlisting>
297         <para>
298             <classname>Zend_Form</classname> używa "dekoratorów" do przeprowadzania
299             renderowania. Te dekoratory mogą zastępować zawartość, dodawać
300             treść na początku lub na końcu, a także mieć pełny wgląd w
301             element przekazany do nich. Można użyć kilku dekoratorów aby
302             uzyskać wymagany efekt. Domyślnie <classname>Zend_Form_Element</classname>
303             używa czterech dekoratorów aby wygenerować kod wyjściowy. Wygląda
304             to w taki sposób:
305         </para>
307         <programlisting language="php"><![CDATA[
308 $element->addDecorators(array(
309     'ViewHelper',
310     'Errors',
311     array('HtmlTag', array('tag' => 'dd')),
312     array('Label', array('tag' => 'dt')),
315         </programlisting>
317         <para>
318             (Gdzie &lt;HELPERNAME&gt; jest nazwą klasy pomocniczej widoku, która
319             ma być użyta. Może ona różnić się dla różnych elementów.)
320         </para>
322         <para>
323             Układ dekoratorów przedstawiony powyżej generuje następujący kod:
324         </para>
326         <programlisting language="html"><![CDATA[
327 <dt><label for="username" class="required">Username</dt>
328 <dd>
329     <input type="text" name="username" value="123-abc" />
330     <ul class="errors">
331         <li>'123-abc' has not only alphabetic and digit characters</li>
332         <li>'123-abc' does not match against pattern '/^[a-z]/i'</li>
333     </ul>
334 </dd>
335 ]]></programlisting>
337         <para>
338             (Jednak kod jest inaczej sformatowany.)
339         </para>
341         <para>
342             Można zmienić dekoratory używane przez element jeśli pożądany jest
343             inny kod wyjściowy. Należy zapoznać się z rozdziałem poświęconym dekoratorom
344             aby uzyskać więcej informacji.
345         </para>
347         <para>
348             Formularz przechodzi poprzez wszystkie elementy i umieszcza je
349             wewnątrz znacznika <acronym>HTML</acronym> <emphasis>&lt;form&gt;</emphasis>.
350             Akcja i metoda wysyłania formularza podane podczas jego konfigurowania
351             zostaną dołączone do znacznika<emphasis>&lt;form&gt;</emphasis>, tak samo jak
352             inne atrybuty ustawione za pomocą metody <methodname>setAttribs()</methodname>.
353         </para>
355         <para>
356             Formularz przechodzi przez elementy w takiej kolejności w jakiej
357             były one zarejestrowane lub jeśli określony element zawiera odpowiedni
358             atrybut, zostanie on użyty w celu ustalenia kolejności. Można
359             ustawiać kolejność elementów używając metody:
360         </para>
362         <programlisting language="php"><![CDATA[
363 $element->setOrder(10);
364 ]]></programlisting>
366         <para>
367             Innym sposobem jest przekazanie kolejności jako opcji podczas tworzenia elementu:
368         </para>
370         <programlisting language="php"><![CDATA[
371 $form->addElement('text', 'username', array('order' => 10));
372 ]]></programlisting>
373     </sect2>
375     <sect2 id="zend.form.quickstart.validate">
376         <title>Sprawdzanie poprawności formularza</title>
378         <para>
379             Po tym jak formularz zostanie wysłany, należy sprawdzić czy pomyślnie
380             przeszedł walidację. Każdy element jest sprawdzany w oparciu o
381             podane dane. Jeśli nie ma klucza odpowiadającego nazwie elementu, a
382             element jest oznaczony jako wymagany, weryfikacja zostanie
383             przeprowadzona w oparciu o pustą wartość <constant>NULL</constant>.
384         </para>
386         <para>
387             Skąd pochodzą dane? Możesz użyć tablic <varname>$_POST</varname>,
388             <varname>$_GET</varname> lub dowolnych innych źródeł danych
389             (np. żądań do web serwisów):
390         </para>
392         <programlisting language="php"><![CDATA[
393 if ($form->isValid($_POST)) {
394     // dane są poprawne
395 } else {
396     // dane nie są poprawne
398 ]]></programlisting>
400         <para>
401             Przy korzystaniu z żądań AJAX, może zajść potrzeba przeprowadzenia
402             weryfikacji pojedynczego elementu lub grupy elementów.
403             Metoda <methodname>isValidPartial()</methodname> częściowo sprawdza formularz.
404             W przeciwieństwie do metody <methodname>isValid()</methodname>, nie przeprowadza
405             ona weryfikacji pól dla elementów których wartości nie zostały podane:
406         </para>
408         <programlisting language="php"><![CDATA[
409 if ($form->isValidPartial($_POST)) {
410     // dane we wszystkich elementach pomyślnie przyszły weryfikację
411 } else {
412     // jeden lub więcej elementów nie przeszło poprawnie weryfikacji
415         </programlisting>
417         <para>
418             Do częściowej weryfikacji formularza można także użyć metody
419             <methodname>processAjax()</methodname>.  W przeciwieństwie do metody
420             <methodname>isValidPartial()</methodname>, zwraca ona łańcuch znaków w formacie
421             JSON zawierający informacje o błędach.
422         </para>
424         <para>
425             Zakładając że elementy zostały zweryfikowane i są poprawne, można
426             pobrać przefiltrowane wartości:
427         </para>
429         <programlisting language="php"><![CDATA[
430 $values = $form->getValues();
432         </programlisting>
434         <para>
435             Jeśli potrzeba niefiltrowanych wartości, należy użyć:
436         </para>
438         <programlisting language="php"><![CDATA[
439 $unfiltered = $form->getUnfilteredValues();
441         </programlisting>
442     </sect2>
444     <sect2 id="zend.form.quickstart.errorstatus">
445         <title>Pobieranie informacji o błędach</title>
447         <para>
448             Formularz nie przeszedł weryfikacji? W większości przypadków
449             można po prostu powtórnie wyświetlić formularz, a błędy zostaną
450             pokazane używając dekoratorów:
451         </para>
453         <programlisting language="php"><![CDATA[
454 if (!$form->isValid($_POST)) {
455     echo $form;
457     // przekazanie go do obiektu widoku i renderowanie widoku
458     $this->view->form = $form;
459     return $this->render('form');
462         </programlisting>
464         <para>
465             Dostępne są dwie metody do sprawdzania błędów. Metoda
466             <methodname>getErrors()</methodname> zwraca tablicę asocjacyjną zawierającą
467             informacje o błędach w postaci nazwa elementu / kody (gdzie kody są
468             tablicami kodów błędów). Metoda <methodname>getMessages()</methodname> zwraca
469             tablicę asocjacyjną zawierającą informacje o błędach w postaci nazwa
470             elementu / komunikaty (gdzie komunikaty są asocjacyjną tablicą w
471             postaci kod / komunikat). Jeśli dany element nie zawiera błędów, nie
472             będzie zawarty w tablicy.
473         </para>
474     </sect2>
476     <sect2 id="zend.form.quickstart.puttingtogether">
477         <title>Złożenie w całość</title>
479         <para>
480             Teraz można przystąpić do budowy prostego formularza logowania.
481             Potrzebne będą elementy:
482         </para>
484         <itemizedlist>
485             <listitem><para>nazwa użytkownika</para></listitem>
486             <listitem><para>hasło</para></listitem>
487             <listitem><para>przycisk wysyłający</para></listitem>
488         </itemizedlist>
490         <para>
491             Na potrzeby przykładu można załóżyć że poprawna nazwa użytkownika powinna
492             składać się jedynie ze znaków alfanumerycznych, powinna zaczynać
493             się od litery, jej długość powinna zawierać się między 6 a 12
494             znakami. Litery powinny zostać zamienione na małe. Hasło musi
495             składać się minimalnie z 6 znaków. Wartość przycisku wysyłającego
496             formularz można zignorować, więc nie musi podlegać walidacji.
497         </para>
499         <para>
500             Aby zbudować formularz można skorzystać z metod konfiguracyjnych obiektu
501             <classname>Zend_Form</classname>:
502         </para>
504         <programlisting language="php"><![CDATA[
505 $form = new Zend_Form();
506 $form->setAction('/user/login')
507      ->setMethod('post');
509 // Utworzenie i skonfigurowanie elementu zawierającego nazwę użytkownika:
510 $username = $form->createElement('text', 'username');
511 $username->addValidator('alnum')
512          ->addValidator('regex', false, array('/^[a-z]+/'))
513          ->addValidator('stringLength', false, array(6, 20))
514          ->setRequired(true)
515          ->addFilter('StringToLower');
517 // Utworzenie i skonfigurowanie elementu zawierającego hasło:
518 $password = $form->createElement('password', 'password');
519 $password->addValidator('StringLength', false, array(6))
520          ->setRequired(true);
522 // Dodanie elementów do formularza:
523 $form->addElement($username)
524      ->addElement($password)
525      // użycie metody addElement() jako fabryki tworzącej przycisk 'Zaloguj':
526      ->addElement('submit', 'login', array('label' => 'Zaloguj'));
527 ]]></programlisting>
529         <para>
530             Następnie należy utworzyć kontroler obsługujący formularz:
531         </para>
533         <programlisting language="php"><![CDATA[
534 class UserController extends Zend_Controller_Action
536     public function getForm()
537     {
538         // tworzenie formularza jak wyżej
539         return $form;
540     }
542     public function indexAction()
543     {
544         // renderowanie skryptu user/form.phtml
545         $this->view->form = $this->getForm();
546         $this->render('form');
547     }
549     public function loginAction()
550     {
551         if (!$this->getRequest()->isPost()) {
552             return $this->_forward('index');
553         }
554         $form = $this->getForm();
555         if (!$form->isValid($_POST)) {
556             // Weryfikacja nieudana, ponowne wyświetlenie formularza
557             $this->view->form = $form;
558             return $this->render('form');
559         }
561         $values = $form->getValues();
562         // Weryfikacja udana, można próbować uwierzytelnić
563     }
565 ]]></programlisting>
567         <para>
568             Utworzenie skryptu widoku wyświetlającego formularz:
569         </para>
571 <programlisting language="php"><![CDATA[
572 <h2>Zaloguj się:</h2>
573 <?= $this->form ?>
574 ]]></programlisting>
576         <para>
577             Jak nietrudno zauważyć, w kod kontrolera może wymagać trochę dodatkowej
578             pracy: jeśli wysłane dane będą poprawne, należy przeprowadzić
579             uwierzytelnienie używając np. klasy <classname>Zend_Auth</classname>.
580         </para>
581     </sect2>
583     <sect2 id="zend.form.quickstart.config">
584         <title>Użycie obiektu Zend_Config</title>
586         <para>
587             Wszystkie klasy <classname>Zend_Form</classname> można skonfigurować za pomocą
588             komponentu <classname>Zend_Config</classname>. Można przekazać obiekt klasy
589             <classname>Zend_Config</classname> do konstruktora lub przekazać go za pomocą
590             metody <methodname>setConfig()</methodname>.
591             Oto jak można utworzyć powyższy formularz używając pliku INI.
592             Najpierw, biorąc pod uwagę zalecenia, należy umieścić konfigurację
593             w sekcjach odnoszących się do typu
594             wdrożenia aplikacji i skupić się na sekcji 'development'.
595             Następnie należy utwórzyć sekcję dla danego kontrolera ('user'), oraz klucz
596             dla formularza ('login'):
597         </para>
599         <programlisting language="ini"><![CDATA[
600 [development]
601 ; ogólna konfiguracja formularza
602 user.login.action = "/user/login"
603 user.login.method = "post"
605 ; nazwa użytkownika
606 user.login.elements.username.type = "text"
607 user.login.elements.username.options.validators.alnum.validator = "alnum"
608 user.login.elements.username.options.validators.regex.validator = "regex"
609 user.login.elements.username.options.validators.regex.options.pattern = "/^[a-z]/i"
610 user.login.elements.username.options.validators.strlen.validator = "StringLength"
611 user.login.elements.username.options.validators.strlen.options.min = "6"
612 user.login.elements.username.options.validators.strlen.options.max = "20"
613 user.login.elements.username.options.required = true
614 user.login.elements.username.options.filters.lower.filter = "StringToLower"
616 ; hasło
617 user.login.elements.password.type = "password"
618 user.login.elements.password.options.validators.strlen.validator = "StringLength"
619 user.login.elements.password.options.validators.strlen.options.min = "6"
620 user.login.elements.password.options.required = true
622 ; przycisk wysyłający
623 user.login.elements.submit.type = "submit"
624 ]]></programlisting>
626         <para>
627             Powyższe można przekazać do konstruktora obiektu formularza:
628         </para>
630         <programlisting language="php"><![CDATA[
631 $config = new Zend_Config_Ini($configFile, 'development');
632 $form   = new Zend_Form($config->user->login);
633 ]]></programlisting>
635         <para>
636             w ten sposób cały formularz został zdefiniowany.
637         </para>
638     </sect2>
640     <sect2 id="zend.form.quickstart.conclusion">
641         <title>Podsumowanie</title>
643         <para>
644             Dzięki temu przewodnikowi czytelnik powinien być na dobrej drodze do wykorzystania mocy
645             i elastyczności komponentu <classname>Zend_Form</classname>. Aby uzyskać
646             bardziej szczegółowe informacje należy zapoznać się z dalszymi częściami dokumentacji.
647         </para>
648     </sect2>
649 </sect1>
650 <!--
651 vim:se ts=4 sw=4 et: