1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- EN-Revision: 21829 -->
4 <sect1 id="zend.form.quickstart">
5 <title>Szybki start z Zend_Form</title>
8 Ten przewodnik opisuje podstawy tworzenia, weryfikacji oraz
9 renderowania formularzy za pomocą komponentu <classname>Zend_Form</classname>.
12 <sect2 id="zend.form.quickstart.create">
13 <title>Tworzenie obiektu formularza</title>
16 Tworzenie obiektu formularza jest bardzo proste: należy, po prostu, utworzyć
17 egzemplarz klasy <classname>Zend_Form</classname>:
20 <programlisting language="php"><![CDATA[
21 $form = new Zend_Form;
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>.
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>:
37 <programlisting language="php"><![CDATA[
38 $form->setAction('/resource/process')
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.
51 Można ustawić dodatkowe atrybuty dla znacznika
52 <emphasis><form></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>":
57 <programlisting language="php"><![CDATA[
58 $form->setAttrib('id', 'login');
63 <sect2 id="zend.form.quickstart.elements">
64 <title>Dodawanie elementów do formularza</title>
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:
79 checkbox (pole wyboru lub wiele pól za pomocą multiCheckbox)
99 reset (przycisk resetujący)
103 select (lista zwykła oraz lista wielokrotnego wyboru)
107 submit (przycisk wysyłający)
115 textarea (wieloliniowe pole tekstowe)
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.
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');
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.
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ć
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');
169 Dla drugiego sposobu, można przekazać w trzecim parametrze metody
170 tablicę z argumentami konstruktora wybranego walidatora.
173 <programlisting language="php"><![CDATA[
175 $username->addValidator('regex', false, array('/^[a-z]/i'));
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>.)
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:
191 <programlisting language="php"><![CDATA[
192 // Ustawienie elementu jako wymaganego:
193 $username->setRequired(true);
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ść.
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
209 <programlisting language="php"><![CDATA[
210 $username->addFilter('StringtoLower');
215 Finalnie konfiguracja elementu może wyglądać tak:
218 <programlisting language="php"><![CDATA[
219 $username->addValidator('alnum')
220 ->addValidator('regex', false, array('/^[a-z]/'))
222 ->addFilter('StringToLower');
224 // lub bardziej zwięźle:
225 $username->addValidators(array('alnum',
226 array('regex', false, '/^[a-z]/i')
229 ->addFilters(array('StringToLower'));
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:
242 <programlisting language="php"><![CDATA[
243 $form->addElement('text', 'username', array(
244 'validators' => array(
246 array('regex', false, '/^[a-z]/i')
249 'filters' => array('StringToLower'),
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.
264 <sect2 id="zend.form.quickstart.render">
265 <title>Renderowanie formularza</title>
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ą
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():
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:
292 <programlisting language="php"><![CDATA[
293 <? echo $this->form ?>
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
307 <programlisting language="php"><![CDATA[
308 $element->addDecorators(array(
311 array('HtmlTag', array('tag' => 'dd')),
312 array('Label', array('tag' => 'dt')),
318 (Gdzie <HELPERNAME> jest nazwą klasy pomocniczej widoku, która
319 ma być użyta. Może ona różnić się dla różnych elementów.)
323 Układ dekoratorów przedstawiony powyżej generuje następujący kod:
326 <programlisting language="html"><![CDATA[
327 <dt><label for="username" class="required">Username</dt>
329 <input type="text" name="username" value="123-abc" />
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>
338 (Jednak kod jest inaczej sformatowany.)
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.
348 Formularz przechodzi poprzez wszystkie elementy i umieszcza je
349 wewnątrz znacznika <acronym>HTML</acronym> <emphasis><form></emphasis>.
350 Akcja i metoda wysyłania formularza podane podczas jego konfigurowania
351 zostaną dołączone do znacznika<emphasis><form></emphasis>, tak samo jak
352 inne atrybuty ustawione za pomocą metody <methodname>setAttribs()</methodname>.
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:
362 <programlisting language="php"><![CDATA[
363 $element->setOrder(10);
367 Innym sposobem jest przekazanie kolejności jako opcji podczas tworzenia elementu:
370 <programlisting language="php"><![CDATA[
371 $form->addElement('text', 'username', array('order' => 10));
375 <sect2 id="zend.form.quickstart.validate">
376 <title>Sprawdzanie poprawności formularza</title>
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>.
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):
392 <programlisting language="php"><![CDATA[
393 if ($form->isValid($_POST)) {
396 // dane nie są poprawne
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:
408 <programlisting language="php"><![CDATA[
409 if ($form->isValidPartial($_POST)) {
410 // dane we wszystkich elementach pomyślnie przyszły weryfikację
412 // jeden lub więcej elementów nie przeszło poprawnie weryfikacji
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.
425 Zakładając że elementy zostały zweryfikowane i są poprawne, można
426 pobrać przefiltrowane wartości:
429 <programlisting language="php"><![CDATA[
430 $values = $form->getValues();
435 Jeśli potrzeba niefiltrowanych wartości, należy użyć:
438 <programlisting language="php"><![CDATA[
439 $unfiltered = $form->getUnfilteredValues();
444 <sect2 id="zend.form.quickstart.errorstatus">
445 <title>Pobieranie informacji o błędach</title>
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:
453 <programlisting language="php"><![CDATA[
454 if (!$form->isValid($_POST)) {
457 // przekazanie go do obiektu widoku i renderowanie widoku
458 $this->view->form = $form;
459 return $this->render('form');
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.
476 <sect2 id="zend.form.quickstart.puttingtogether">
477 <title>Złożenie w całość</title>
480 Teraz można przystąpić do budowy prostego formularza logowania.
481 Potrzebne będą elementy:
485 <listitem><para>nazwa użytkownika</para></listitem>
486 <listitem><para>hasło</para></listitem>
487 <listitem><para>przycisk wysyłający</para></listitem>
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.
500 Aby zbudować formularz można skorzystać z metod konfiguracyjnych obiektu
501 <classname>Zend_Form</classname>:
504 <programlisting language="php"><![CDATA[
505 $form = new Zend_Form();
506 $form->setAction('/user/login')
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))
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))
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'));
530 Następnie należy utworzyć kontroler obsługujący formularz:
533 <programlisting language="php"><![CDATA[
534 class UserController extends Zend_Controller_Action
536 public function getForm()
538 // tworzenie formularza jak wyżej
542 public function indexAction()
544 // renderowanie skryptu user/form.phtml
545 $this->view->form = $this->getForm();
546 $this->render('form');
549 public function loginAction()
551 if (!$this->getRequest()->isPost()) {
552 return $this->_forward('index');
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');
561 $values = $form->getValues();
562 // Weryfikacja udana, można próbować uwierzytelnić
568 Utworzenie skryptu widoku wyświetlającego formularz:
571 <programlisting language="php"><![CDATA[
572 <h2>Zaloguj się:</h2>
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>.
583 <sect2 id="zend.form.quickstart.config">
584 <title>Użycie obiektu Zend_Config</title>
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'):
599 <programlisting language="ini"><![CDATA[
601 ; ogólna konfiguracja formularza
602 user.login.action = "/user/login"
603 user.login.method = "post"
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"
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"
627 Powyższe można przekazać do konstruktora obiektu formularza:
630 <programlisting language="php"><![CDATA[
631 $config = new Zend_Config_Ini($configFile, 'development');
632 $form = new Zend_Form($config->user->login);
636 w ten sposób cały formularz został zdefiniowany.
640 <sect2 id="zend.form.quickstart.conclusion">
641 <title>Podsumowanie</title>
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.