Formulářové prvky

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

addText(string|int $name, $label=null): TextInput

Přidá jednořádkové textové políčko (třída TextInput). Automaticky ořezává levo- a pravostranné mezery nebo případné odřádkování.

$form->addText('zip', 'PSČ:')
	->setRequired()
	->addRule($form::PATTERN, 'PSČ musí mít 5 číslic', '([0-9]\s*){5}');

Prvku lze nastavit tzv. empty-value, což je něco jako výchozí hodnota, ale pokud ji uživatel nepřepíše, vrátí prvek prázdný řetězec.

$form->addText('phone', 'Telefon:')
	->setEmptyValue('+42');

addPassword(string|int $name, $label=null): TextInput

Přidá políčko pro zadání hesla (třída TextInput). Automaticky ořezává levo- a pravostranné mezery nebo případné odřádkování. Při znovu-zobrazení formuláře bude políčko prázdné.

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

addTextArea(string|int $name, $label=null): TextArea

Přidá pole pro zadání víceřádkového textu (třída TextArea). Na rozdíl od jednořádkového vstupního políčka k žádnému ořezávání mezer nedochází.

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

addEmail(string|int $name, $label=null): TextInput

Přidá políčko pro zadání e-mailové adresy s kontrolou její platnosti (třída TextInput).

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

addInteger(string|int $name, $label=null): TextInput

Přidá políčko pro zadání celočíselného čísla.

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

addUpload(string|int $name, $label=null): UploadControl

Přidá políčko pro upload souboru (třída UploadControl).

$form->addUpload('avatar', 'Avatar:')
	->setRequired(false) // nepovinný
	->addRule($form::IMAGE, 'Avatar musí být JPEG, PNG nebo GIF.')
	->addRule($form::MAX_FILE_SIZE, 'Maximální velikost souboru je 64 kB.', 64 * 1024 /* v bytech */);

addMultiUpload(string|int $name, $label=null): UploadControl

Přidá políčko, které uživateli umožní nahrát více souborů najednou.

$form->addMultiUpload('files', 'Soubory');

addHidden(string|int $name, string $default=null): HiddenField

Přidá skryté pole (třída HiddenField).

$form->addHidden('userid');

addCheckbox(string|int $name, $caption=null): Checkbox

Přidá zaškrtávací políčko (třída Checkbox). Políčko vrací hodnotu buď true nebo false, podle toho, zda je zaškrtnuté či nikoliv.

$form->addCheckbox('agree', 'Souhlasím s podmínkami')
	->setRequired('Je potřeba souhlasit s podmínkami');
$form->addCheckbox('resize', 'Zmenšit obrázek')
	->setDefaultValue(true);

addRadioList(string|int $name, $label=null, array $items=null): RadioList

Přidá přepínací tlačítka (třída RadioList). Pole nabízených hodnot předáme jako třetí parametr.

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

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

addCheckboxList(string|int $name, $label=null, array $items=null): CheckboxList

Přidá seznam zaškrtávacích políček pro výběr více prvků (třída CheckboxList). Pole nabízených hodnot opět předáme jako třetí parametr. Stejně jako v případě selectboxů nebo radiolistů kontroluje, zda odeslané hodnoty jsou z těch, které nabízíme.

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

addSelect(string|int $name, $label=null, array $items=null): SelectBox

Přidá select box (třída SelectBox). 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(). Pole nabízených hodnot předáme jako třetí parametr. Pole může být i dvourozměrné:

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

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

Prvek vrací klíč vybrané položky. Stejně tak se jako výchozí hodnota uvádí klíč:

$form->addSelect('country', 'Země:')
	->setDefaultValue('sk');

Prvky je rovněž možné přidat pomocí metody setItems(). Pokud chceme místo klíčů položek získat přímo jejich hodnoty, můžeme toho docílit druhým argumentem:

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

Jednotlivé prvky mohou být krom řetězců i objekty Nette\Utils\Html::(‚option‘), kterým pak lze nastavovat další HTML atributy. Nicméně atributy selected a disabled tímto způsobem nenastavujte, o ty se stará formulář sám. Tohle platí i pro addMultiSelect().

addMultiSelect(string|int $name, $label=null, array $items=null): MultiSelectBox

Přidá select box pro výběr více položek (třída MultiSelectBox).

$form->addMultiSelect('options', 'Možnosti:', $options);

addSubmit(string|int $name, $caption=null): SubmitButton

Přidá odesílací tlačítko (třída SubmitButton).

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

Je v pořádku přidat více než jedno odesílací tlačítko.

$form->addSubmit('submit', 'Register');
$form->addSubmit('cancel', 'Cancel');

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

if ($form['submit']->isSubmittedBy()) {
  // ...
}

Pokud nechcete validovat formulář při stisknutí tlačítka (například u tlačítek Zrušit nebo Náhled), můžete ji vypnout pomocí setValidationScope([]).

addButton(string|int $name, $caption)Button

Přidá tlačítko (třída Button), které nemá odesílací funkci. Lze ho tedy využít na nějakou jinou funkci, např. zavolání js funkce při kliknutí.

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

addImage(string|int $name, $alt=null): ImageButton

Přidá odesílací tlačítko v podobě obrázku (třída ImageButton).

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

addContainer(string|int $name): Container

Přidá pod-formulář (třída 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().

$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:');

Deaktivace prvků

Pokud chceme některý prvek deaktivovat, můžeme využít metodu $control->setDisabled()

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

Do tohoto prvku nepůjde zapisovat a jeho hodnota nebude obsažena v datech vracených funkcí $form->getValues().

Pokud chceme prvek použít jen pro čtení, tj. aby se nastavená hodnota prvku zobrazila, ale prvek byl neaktivní, je potřeba nejdřív prvek deaktivovat a poté mu nastavit hodnotu. Je to z toho důvodu, že metoda setDisabled() hodnotu prvku vynuluje.

$form->addText('readonly', 'Readonly:')->setDisabled()->setValue('readonly value');

Pokud potřebujeme prvek pouze vyjmout z těchto dat, použijeme funkci $control->setOmitted(). To se hodí pro různá hesla pro kontrolu, antispamové prvky atd.

$form->addText('antispam', 'Antispam:')->setOmitted();

Další 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:

$form = new Form;
$form['date'] = new DateInput('Datum:');

Pomocí extension method můžete doplnit formulář o novou metodu:

Nette\Forms\Container::extensionMethod('addZip', function (Form $form, $name, $label = null) {
	return $form->addText($name, $label)
		->setRequired(false)
		->addRule($form::PATTERN, 'Alespoň 5 čísel', '[0-9]{5}');
});

$form = new Form;
$form->addZip('zip', 'ZIP code:');

Prvky se odstraní pomocí unset:

unset($form['zip']);

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ě:

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

A po odeslání hodnotu zjistíme:

$values = $form->getHttpData($form::DATA_TEXT, 'sel[]');
$values = $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ž se pokusíte 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ářů.


Související články na blogu