Formulářové prvky
*****************

.[perex]
Přehled standardních formulářových prvků.


addText(string|int $name, $label=null): TextInput .[method]
===========================================================

Přidá jednořádkové textové políčko (třída [TextInput |api:Nette\Forms\Controls\TextInput]). Pokud uživatel pole nevyplní, vrací prázdný řetězec `''`, nebo pomocí `setNullable()` lze určit, aby vracel `null`.

```php
$form->addText('name', 'Jméno:')
	->setRequired()
	->setNullable();
```

Automaticky validuje UTF-8, ořezává levo- a pravostranné mezery a odstraňuje odřádkování, které by mohl odeslat útočník.

Maximální délku lze omezit pomocí `setMaxLength()`. Pozměnit uživatelem vloženou hodnotu umožňuje [addFilter()|validation#Úprava vstupu].

Pomocí `setHtmlType()` lze změnit [charakter|https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types] vstupního prvku na `search`, `tel`, `url`, `range`, `date`, `datetime-local`, `month`, `time`, `week`, `color`. Místo typů `number` a `email` doporučujeme použít [#addInteger] a [#addEmail], které disponují validací na straně serveru.

```php
$form->addText('color', 'Vyberte barvu:')
	->setHtmlType('color')
	->addRule($form::PATTERN, 'invalid value', '[0-9a-f]{6}');
```

Prvku lze nastavit tzv. empty-value, což je něco jako výchozí hodnota, ale pokud ji uživatel nezmění, vrátí prvek prázdný řetězec či `null`.

```php
$form->addText('phone', 'Telefon:')
	->setHtmlType('tel')
	->setEmptyValue('+420');
```


addTextArea(string|int $name, $label=null): TextArea .[method]
==============================================================

Přidá pole pro zadání víceřádkového textu (třída [TextArea |api:Nette\Forms\Controls\TextArea]). Pokud uživatel pole nevyplní, vrací prázdný řetězec `''`, nebo pomocí `setNullable()` lze určit, aby vracel `null`.

```php
$form->addTextArea('note', 'Poznámka:')
	->addRule($form::MAX_LENGTH, 'Poznámka je příliš dlouhá', 10000);
```

Automaticky validuje UTF-8 a normalizuje oddělovače řádků na `\n`. Na rozdíl od jednořádkového vstupního políčka k žádnému ořezávání mezer nedochází.

Maximální délku lze omezit pomocí `setMaxLength()`. Pozměnit uživatelem vloženou hodnotu umožňuje [addFilter()|validation#Úprava vstupu]. Lze nastavit tzv. empty-value pomocí `setEmptyValue()`.


addInteger(string|int $name, $label=null): TextInput .[method]
==============================================================

Přidá políčko pro zadání celočíselného čísla (třída [TextInput |api:Nette\Forms\Controls\TextInput]). Vrací buď integer, nebo `null`, pokud uživatel nic nezadá.

```php
$form->addInteger('level', 'Úroveň:')
	->setDefaultValue(0)
	->addRule($form::RANGE, 'Úroveň musí být v rozsahu mezi %d a %d.', [0, 100]);
```


addEmail(string|int $name, $label=null): TextInput .[method]
============================================================

Přidá políčko pro zadání e-mailové adresy (třída [TextInput |api:Nette\Forms\Controls\TextInput]). Pokud uživatel pole nevyplní, vrací prázdný řetězec `''`, nebo pomocí `setNullable()` lze určit, aby vracel `null`.

```php
$form->addEmail('email', 'E-mail:');
```

Ověří, zda je hodnota platná e-mailová adresa. Neověřuje se, zda doména skutečně existuje, ověřuje se pouze syntaxe. Automaticky validuje UTF-8, ořezává levo- a pravostranné mezery.

Maximální délku lze omezit pomocí `setMaxLength()`. Pozměnit uživatelem vloženou hodnotu umožňuje [addFilter()|validation#Úprava vstupu]. Lze nastavit tzv. empty-value pomocí `setEmptyValue()`.


addPassword(string|int $name, $label=null): TextInput .[method]
===============================================================

Přidá políčko pro zadání hesla (třída [TextInput |api:Nette\Forms\Controls\TextInput]).

```php
$form->addPassword('password', 'Heslo:')
	->setRequired()
	->addRule($form::MIN_LENGTH, 'Heslo musí mít alespoň %d znaků', 8)
	->addRule($form::PATTERN, 'Musí obsahovat číslici', '.*[0-9].*');
```

Při znovuzobrazení formuláře bude políčko prázdné. Automaticky validuje UTF-8, ořezává levo- a pravostranné mezery a odstraňuje odřádkování, které by mohl odeslat útočník.


addCheckbox(string|int $name, $caption=null): Checkbox .[method]
================================================================

Přidá zaškrtávací políčko (třída [Checkbox |api:Nette\Forms\Controls\Checkbox]). Vrací hodnotu buď `true` nebo `false`, podle toho, zda je zaškrtnuté.

```php
$form->addCheckbox('agree', 'Souhlasím s podmínkami')
	->setRequired('Je potřeba souhlasit s podmínkami');
```


addCheckboxList(string|int $name, $label=null, ?array $items=null): CheckboxList .[method]
==========================================================================================

Přidá zaškrtávací políčka pro výběr více položek (třída [CheckboxList |api:Nette\Forms\Controls\CheckboxList]). Vrací pole klíčů vybraných položek. Metoda `getSelectedItems()` vrací hodnoty místo klíčů.

```php
$form->addCheckboxList('colors', 'Barvy:', [
	'r' => 'červená',
	'g' => 'zelená',
	'b' => 'modrá',
]);
```

Pole nabízených položek předáme jako třetí parametr nebo metodou `setItems()`.

Pomocí `setDisabled(['r', 'g'])` lze deaktivovat jednotlivé položky.

Prvek automaticky kontroluje, že nedošlo k podvržení a že vybrané položky jsou skutečně jedněmi z nabízených a nebyly deaktivovaná. Metodou `getRawValue()` lze získat odeslané položky bez této důležité kontroly.

Při nastavení výchozích vybraných položek také kontroluje, že jde o jedny z nabízených, jinak vyhodí výjimku. Tuto kontrolu lze vypnout pomocí `checkDefaultValue(false)`.


addRadioList(string|int $name, $label=null, ?array $items=null): RadioList .[method]
====================================================================================

Přidá přepínací tlačítka (třída [RadioList |api:Nette\Forms\Controls\RadioList]). Vrací klíč vybrané položky, nebo `null`, pokud uživatel nic nevybral. Metoda `getSelectedItem()` vrací hodnotu místo klíče.

```php
$sex = [
	'm' => 'muž',
	'f' => 'žena',
];
$form->addRadioList('gender', 'Pohlaví:', $sex);
```

Pole nabízených položek předáme jako třetí parametr nebo metodou `setItems()`.

Pomocí `setDisabled(['m', 'f'])` lze deaktivovat jednotlivé položky.

Prvek automaticky kontroluje, že nedošlo k podvržení a že vybraná položka je skutečně jednou z nabízených a nebyla deaktivovaná. Metodou `getRawValue()` lze získat odeslanou položku bez této důležité kontroly.

Při nastavení výchozí vybrané položky také kontroluje, že jde o jednou z nabízených, jinak vyhodí výjimku. Tuto kontrolu lze vypnout pomocí `checkDefaultValue(false)`.


addSelect(string|int $name, $label=null, ?array $items=null): SelectBox .[method]
=================================================================================

Přidá select box (třída [SelectBox |api:Nette\Forms\Controls\SelectBox]). Vrací klíč vybrané položky, nebo `null`, pokud uživatel nic nevybral. Metoda `getSelectedItem()` vrací hodnotu místo klíče.

```php
$countries = [
	'CZ' => 'Česká Republika',
	'SK' => 'Slovensko',
	'GB' => 'Velká Británie',
];

$form->addSelect('country', 'Země:', $countries)
	->setDefaultValue('SK');
```

Pole nabízených položek předáme jako třetí parametr nebo metodou `setItems()`. Položky mohou být i dvourozměrné pole:

```php
$countries = [
	'Europe' => [
		'CZ' => 'Česká Republika',
		'SK' => 'Slovensko',
		'GB' => 'Velká Británie',
	],
	'CA' => 'Kanada',
	'US' => 'USA',
	'?'  => 'jiná',
];
```

U select boxů má často první položka speciální význam, slouží jako výzva k akci. K přidání takové položky slouží metoda `setPrompt()`.

```php
$form->addSelect('country', 'Země:', $countries)
	->setPrompt('Zvolte zemi');
```

Pomocí `setDisabled(['CZ', 'SK'])` lze deaktivovat jednotlivé položky.

Prvek automaticky kontroluje, že nedošlo k podvržení a že vybraná položka je skutečně jednou z nabízených a nebyla deaktivovaná. Metodou `getRawValue()` lze získat odeslanou položku bez této důležité kontroly.

Při nastavení výchozí vybrané položky také kontroluje, že jde o jednou z nabízených, jinak vyhodí výjimku. Tuto kontrolu lze vypnout pomocí `checkDefaultValue(false)`.


addMultiSelect(string|int $name, $label=null, ?array $items=null): MultiSelectBox .[method]
===========================================================================================

Přidá select box pro výběr více položek (třída [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Vrací pole klíčů vybraných položek. Metoda `getSelectedItems()` vrací hodnoty místo klíčů.

```php
$form->addMultiSelect('countries', 'Země:', $countries);
```

Pole nabízených položek předáme jako třetí parametr nebo metodou `setItems()`. Položky mohou být i dvourozměrné pole.

Pomocí `setDisabled(['CZ', 'SK'])` lze deaktivovat jednotlivé položky.

Prvek automaticky kontroluje, že nedošlo k podvržení a že vybrané položky jsou skutečně jedněmi z nabízených a nebyly deaktivovaná. Metodou `getRawValue()` lze získat odeslané položky bez této důležité kontroly.

Při nastavení výchozích vybraných položek také kontroluje, že jde o jedny z nabízených, jinak vyhodí výjimku. Tuto kontrolu lze vypnout pomocí `checkDefaultValue(false)`.


addUpload(string|int $name, $label=null): UploadControl .[method]
=================================================================

Přidá políčko pro upload souboru (třída [UploadControl |api:Nette\Forms\Controls\UploadControl]). Vrací objekt [FileUpload|http:request#FileUpload] a to i v případě, že uživatel žádný soubor neodeslal, což lze zjistit metodou `FileUpload::hasFile()`.

```php
$form->addUpload('avatar', 'Avatar:')
	->setRequired(false) // nepovinný
	->addRule($form::IMAGE, 'Avatar musí být JPEG, PNG or GIF.')
	->addRule($form::MAX_FILE_SIZE, 'Maximální velikost je 1 MB.', 1024 * 1024);
```

Pokud se soubor nepodaří korektně nahrát, formulář není úspěšně odeslaný a zobrazí se chyba. Tj. při úspěšném odeslání není potřeba ověřovat metodu `FileUpload::isOk()`.

Nikdy nevěřte originálnímu názvu souboru vráceného metodou `FileUpload::getName()`, klient mohl odeslat škodlivý název souboru s úmyslem poškodit nebo hacknout vaši aplikaci.

Pravidla `MIME_TYPE` a `IMAGE` detekují požadovaný typ na základě signatury souboru a neověřují jeho integritu. Zda není obrázek poškozený lze zjistit například pokusem o jeho [načtení|http:request#toImage].


addMultiUpload(string|int $name, $label=null): UploadControl .[method]
======================================================================

Přidá políčko pro upload více souboru najednou (třída [UploadControl |api:Nette\Forms\Controls\UploadControl]). Vrací pole objektů [FileUpload|http:request#FileUpload]. Metoda `FileUpload::hasFile()` u každého z nich bude vracet `true`.

```php
$form->addMultiUpload('files', 'Soubory:')
	->addRule($form::MAX_LENGTH, 'Maximálně lze nahrát %d souborů', 10);
```

Pokud se některý soubor nepodaří korektně nahrát, formulář není úspěšně odeslaný a zobrazí se chyba. Tj. při úspěšném odeslání není potřeba ověřovat metodu `FileUpload::isOk()`.

Nikdy nevěřte originálním názvům souborů vráceným metodou `FileUpload::getName()`, klient mohl odeslat škodlivý název souboru s úmyslem poškodit nebo hacknout vaši aplikaci.

Pravidla `MIME_TYPE` a `IMAGE` detekují požadovaný typ na základě signatury souboru a neověřují jeho integritu. Zda není obrázek poškozený lze zjistit například pokusem o jeho [načtení|http:request#toImage].


addHidden(string|int $name, ?string $default=null): HiddenField .[method]
=========================================================================

Přidá skryté pole (třída [HiddenField |api:Nette\Forms\Controls\HiddenField]).

```php
$form->addHidden('userid');
```

Pomocí `setNullable()` lze nastavit, aby vracel `null` místo prázdného řetězce. Pozměnit odeslanou hodnotu umožňuje [addFilter()|validation#Úprava vstupu].


addSubmit(string|int $name, $caption=null): SubmitButton .[method]
==================================================================

Přidá odesílací tlačítko (třída [SubmitButton |api:Nette\Forms\Controls\SubmitButton]).

```php
$form->addSubmit('submit', 'Odeslat');
```

Ve formuláři je možné mít i více odesílacích tlačítek:

```php
$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');
```

Ke zjištění, na které z nich bylo kliknuto, použijte:

```php
if ($form['register']->isSubmittedBy()) {
  // ...
}
```

Pokud nechcete validovat celý formulář při stisknutí tlačítka (například u tlačítek *Zrušit* nebo *Náhled*), použijte [setValidationScope()|validation#Vypnutí validace].


addButton(string|int $name, $caption): Button .[method]
=======================================================

Přidá tlačítko (třída [Button |api:Nette\Forms\Controls\Button]), které nemá odesílací funkci. Lze ho tedy využít na nějakou jinou funkci, např. zavolání JavaScriptové funkce při kliknutí.

```php
$form->addButton('raise', 'Zvýšit plat')
	->setHtmlAttribute('onclick', 'raiseSalary()');
```


addImage(string|int $name, ?string $src=null, ?string $alt=null): ImageButton .[method]
=======================================================================================

Přidá odesílací tlačítko v podobě obrázku (třída [ImageButton |api:Nette\Forms\Controls\ImageButton]).

```php
$form->addImage('submit', '/path/to/image');
```

Při použití více odeslacích tlačítek lze zjistit, na které bylo kliknuto, pomocí `$form['submit']->isSubmittedBy()`.


addContainer(string|int $name): Container .[method]
===================================================

Přidá podformulář (třída [Container|api:Nette\Forms\Container]), nebo-li kontejner, do kterého lze přidávat další prvky stejným způsobem, jako je přidáváme do formuláře. Fungují i metody `setDefaults()` nebo `getValues()`.

```php
$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Your name:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Your name:');
$sub2->addEmail('email', 'Email:');
```

Odeslaná data pak vrací jako vícerozměrnou strukturu:

```php
[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]
```


Další nastavení
===============

Všem formulářovým prvkům lze nastavit výchozí hodnotu pomocí `setDefaultValue()` a získat aktuální hodnotu pomocí `getValue()`.

Popisku lze měnit pomocí `setCaption(string|object $caption)`.

Můžete měnit přímo [jednotlivé atributy |rendering#HTML atributy] HTML elementu pomocí `setHtmlAttribute()`. Pro atributy `id` a `name` jsou k dispozici navíc metody `setHtmlId($id)`, `getHtmlId()` a `getHtmlName()`.

Jednotlivým formulářovým prvkům je možné nastavit překladač pomocí `setTranslator()`.

Prvkům lze přiřadit také uživatelské data pomocí `setOption($key, $value)` a číst je pomocí `getOption($key)`. Můžete tak například prvkům předat informace, které využijete při vykreslování.

Dále lze nastavovat [validační pravidla |validation] pomocí metod `addRule()`, `addCondition()` a dalších.


Vynechané hodnoty
-----------------

Pokud nás uživatelem vyplněná hodnota nezajímá, můžeme ji pomocí `setOmitted()` vynechat z výsledku metody `$form->getValues()` nebo z dat předávaných do handlerů. To se hodí pro různá hesla pro kontrolu, antispamové prvky atd.

```php
$form->addPassword('passwordVerify', 'Heslo pro kontrolu:')
	->setRequired('Zadejte prosím heslo ještě jednou pro kontrolu')
	->addRule($form::EQUAL, 'Hesla se neshodují', $form['password'])
	->setOmitted();
```


Deaktivace prvků
----------------

Prvky lze deaktivovat pomocí `setDisabled()`. Takový prvek nemůže uživatel editovat.

```php
$form->addText('username', 'Uživatelské jméno:')
	->setDisabled();
```

Upozorňujeme, že disablované prvky prohlížeč vůbec neodesílá na server, tedy je ani nenajdete v datech vrácených funkcí `$form->getValues()`.

Pokud prvku nastavujete výchozí hodnotu, je tak nutné učinit až po jeho deaktivaci:

```php
$form->addText('username', 'Uživatelské jméno:')
	->setDisabled()
	->setDefaultValue($userName);
```


Vlastní prvky
=============

Vedle široké škály vestavěných formulářových prvků můžete do formuláře přidávat vlastní prvky tímto způsobem:

```php
$form->addComponent(new DateInput('Datum:'), 'date');
// alternativní syntax: $form['date'] = new DateInput('Datum:');
```

Existuje způsob, jak definovat nové metody formuláře sloužící k přidávání vlastních prvků (např. `$form->addZip()`). Jde o tzv. extension methods. Nevýhoda je, že pro ně nebude fungovat napovídání v editorech.

```php
use Nette\Forms\Container;

// přidáme metodu addZip(string $name, string $label = null)
Container::extensionMethod('addZip', function (Container $form, $name, $label = null) {
	return $form->addText($name, $label)
		->setRequired(false)
		->addRule($form::PATTERN, 'Alespoň 5 čísel', '[0-9]{5}');
});

// použití
$form->addZip('zip', 'ZIP code:');
```


Low-level prvky
===============

Lze používat i prvky, které zapíšeme pouze v šabloně a nepřidáme je do formuláře některou z metod `$form->addXyz()`. Když například vypisujeme záznamy z databáze a dopředu nevíme, kolik jich bude a jaké budou mít ID, a chceme u každého řádku zobrazit checkbox nebo radio button, stačí jej nakódovat v šabloně:

```latte
{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}
```

A po odeslání hodnotu zjistíme:

```php
$data = $form->getHttpData($form::DATA_TEXT, 'sel[]');
$data = $form->getHttpData($form::DATA_TEXT | $form::DATA_KEYS, 'sel[]');
```

kde první parametr je typ elementu (`DATA_FILE` pro `type=file`, `DATA_LINE` pro jednořádkové vstupy jako `text`, `password`, `email` apod. a `DATA_TEXT` pro všechny ostatní) a druhý parametr `sel[]` odpovídá HTML atributu name. Typ elementu můžeme kombinovat s hodnotou `DATA_KEYS`, která zachová klíče prvků. To se hodí zejména pro `select`, `radioList` a `checkboxList`.

Podstatné je, že `getHttpData()` vrací sanitizovanou hodnotu, v tomto případě to bude vždy pole validních UTF-8 řetězců, ať už by se pokusil útočník serveru podstrčit cokoliv. Jde o obdobu přímé práce s `$_POST` nebo `$_GET` avšak s tím podstatným rozdílem, že vždy vrací čistá data, tak, jak jste zvyklí u standardních prvků Nette formulářů.



/--comment
Prvky je rovněž možné přidat pomocí metody [setItems() |api:Nette\Forms\Controls\SelectBox::setItems()]. Pokud chceme místo klíčů položek získat přímo jejich hodnoty, můžeme toho docílit druhým argumentem:

```php
$form->addSelect('country', 'Země:')
	->setItems($countries, false);
```

```php
// pro vypsání možností do 1 řádku
$form->addRadioList('gender', 'Pohlaví:', $sex)
	->getSeparatorPrototype()->setName(null);
```
\--