Naposledy změněno 16. 11. 2008 Edituj Historie Poslední změny

Nette\Forms

Třídy Nette\Forms usnadňují vytváření a zpracování webových formulářů ve vašich aplikacích.

Co všechno umějí?

přehledně popsat formulář a jednotlivé prvky
definovat validační pravidla, podmínky a filtry
vytvářet vlastní validační pravidla
validovat odeslaná data na straně serveru i klienta (tedy v JavaScriptu)
lze zajistit vlastní obsluhu na straně JavaScriptu
skrývání částí formuláře podle vlastních podmínek
seskupovat prvky do skupin
několik režimů vykreslování formulářů
podpora multijazyčnosti

Začínáme

Nejprve si ukážeme, jak vytvořit jednoduchý formulář, nastavit mu validační pravidla a jak jej vykreslit.

Vytvoření formuláře

Začneme vytvořením formuláře:

$form = new Form;

Tímto se vytvořil formulář, který se metodou HTTP POST odešle na stejnou stránku, na jaké se nachází. Samozřejmě metodu i cílové URL lze změnit:

$form->setAction('/submit.php', FALSE);

Druhý parametr říká, zda se má použít metoda HTTP POST. Hodnota FALSE tedy znamená, že formulář se odešle metodou HTTP GET na adresu /submit.php.

Jak nastavit HTML elementu <form> další atributy? Metoda getElementPrototype() vrací element v podobě Nette\Web\Html objektu, se kterým se dá snadno pracovat:

$form->getElementPrototype()->id = 'login-form';

Prvky formuláře

Existují dva způsoby, jak přidávat nové ovládací prvky do formuláře. Jednak můžeme využít toho, že formulář je potomkem třídy Nette\ComponentContainer, takže instance prvků lze přidávat metodou addComponent(), nebo lze použí ještě snažší cestu v podobě předpřipravených továrníček addText(), addPassword() atd. Příklad:

$form = new Form();
$form->addText('name', 'Your name:');
$form->addText('age', 'Your age:', 5);
$form->addCheckbox('send', 'Ship to address:');
$form->addSelect('country', 'Country:', $countries);

Validační pravidla

Metody addRule() a addCondition() … :

$form = new Form();
$form->addText('name', 'Your name:')
    ->addRule(Form::FILLED, 'Enter your name');

$form->addText('age', 'Your age:', 5)
    ->addRule(Form::FILLED, 'Enter your age')
    ->addRule(Form::NUMERIC, 'Age must be numeric')
    ->addRule(Form::RANGE, 'Age must be in range from %d to %d', array(10, 100));

$form->addCheckbox('send', 'Shipping address:')
    ->addCondition(Form::EQUAL, TRUE)
        ->toggle('sendBox'); // toggle HTML element 'sendBox'

$form->addText('email', 'Email:', 35)
    ->setEmptyValue('@')
    ->addCondition(Form::FILLED) // conditional rule: if is email filled, ...
        ->addRule(Form::EMAIL, 'E-mail is not valid'); // ... then check email

$form->addText('city', 'City:', 35)
    ->addConditionOn($form['send'], Form::EQUAL, TRUE) // if $form['send'] is checked
        ->addRule(Form::FILLED, 'Enter your shipping address'); // $form['city'] must be filled

$form->addSelect('country', 'Country:', $countries)->skipFirst(); // skip first option
// must be declared, if you want use skipFirst
$form['country']->addRule(Form::FILLED, 'Select your country');

Metody addRule() a addCondition() jako název validační operace akceptují callback nebo jméno statické funkce, díky čemuž je možné používat vlastní validační pravidla.

$form = new Form();
$form->addText('name', 'Text:', 10)
    ->addRule('MyClass::myValidator', 'Value %d is not allowed!', 11)

Veškerá JavaScriptová podpora byla vyseparována do samostatné třídy. Díky tomu je možné vytvořit vlastní JavaScriptový validátor nebo obsluhu událostí, lze snadno propojit vygenerovaný formulář s nějakým JavaScriptovým frameworkem a podobně.

Každý HTML prvek formuláře lze před vykreslením libovolně upravit. Přístup k němu zajišťují metody getControlPrototype() a getLabelPrototype(), které vrací objekt typu Nette\Web\Html.

$form->addText('name', 'Text:', 10);
$form['name']->getControlPrototype()->style = "background: blue";

Ve webových aplikacích s Presenterem používejte zděděnou třídu Nette\Application\AppForm.

Seskupování prvků

Seskupování elementů je snadné – stačí vytvořit skupinu a přidat do ní libovolné elementy:

$form->addGroup('Personal data')
    ->add($form['name'], $form['age'], $form['gender'], $form['email']);

Vlastně je to ještě jednodušší. Po vytvoření nové skupiny se tato stává aktivní a každý nově přidaný prvek je zároveň přidán i do ní. Takže formulář lze stavět tímto způsobem:

$form = new Form;
$form->addGroup('Personal data');
$form->addText('name', 'Your name:');
$form->addText('age', 'Your age:');
$form->addText('email', 'E-Mail:')->emptyValue = '@';

$form->addGroup('Shipping address');
$form->addCheckbox('send', 'Ship to address');
$form->addText('street', 'Street:', 35);
$form->addText('city', 'City:', 35);
$form->addSelect('country', 'Country:', $countries);

Skupina, kterou reprezentuje třída FormGroup, představuje množinu prvků IFormControl bez specifického sémantického významu. Význam jí tedy dodá až například renderovací rutina, která prvky vykreslí seskupené do elementů fieldset a podobně.

Vykreslení formuláře

Formulář definuje metodu render() a lze jej vykreslit i konstrukcí echo $form.

echo $form;

Je možné si definovat vlastní vykreslovací handler $form->setRenderer($ownRenderer), což je objekt s rozhraním IFormRenderer. Výchozím vykreslovačem je ConventionalRenderer, který není nutné explicitně nastavovat.

Po odeslání a zpracování formuláře je vhodné stránku následně přesměrovat. Zabrání se tak nechtěnému opětovnému odeslání formuláře při přístupu na stánku z historie prohlížeče.

Viz také:

« Nette\Environment Nette\IO\SafeStream »