Formulářové prvky

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

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

Přidá jednořádkové textové políčko (třída TextInput). Automaticky ořezává levo- a pravostranné mezery nebo případné odřádkování. Kromě standardních validačních pravidel lze použít navíc i tato:

Form::MIN_LENGTH minimální délka textu int $minLength
Form::MAX_LENGTH maximální délka textu int $maxLength
Form::LENGTH délka v daném rozsahu nebo právě tato délka [int $min, int $max] nebo int $length
Form::EMAIL je hodnota platná e-mailová adresa?  
Form::URL je hodnota absolutní URL?  
Form::PATTERN testuje oproti regulárnímu výrazu celou hodnotu, tj. jako by byl obalen znaky ^ a $ string $pattern
Form::PATTERN_ICASE jako Form::PATTERN, ale nezávislé na velikosti písmen; od nette/forms v2.4.9 string $pattern
Form::INTEGER je hodnota celočíselná?  
Form::NUMERIC alias pro Form::INTEGER  
Form::FLOAT je hodnota číslo?  
Form::MIN minimální hodnota číselného prvku int|float $minimum
Form::MAX maximální hodnota číselného prvku int|float $maximum
Form::RANGE je hodnota v daném rozsahu? [int $min, int $max]
$form->addText('zip', 'PSČ:')
    ->setRequired()
    ->addRule(Form::PATTERN, 'PSČ musí mít 5 číslic', '([0-9]\s*){5}');

Validační pravidla Form::INTEGER, NUMERIC a FLOAT rovnou převádí hodnotu na integer resp. float. A dále pravidlo Form::URL, které akceptuje i řetězec ve tvaru např. nette.org, jej automaticky doplní na plnohodnotné https://nette.org.

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

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é. Lze použít stejná validační pravidla jako pro addText.

$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): static

Přidá pole pro zadání víceřádkového textu (třída TextArea). Lze použít stejná validační pravidla jako pro addText. 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:')
    ->setRequired(false) // nepovinná
    ->addRule(Form::MAX_LENGTH, 'Poznámka je příliš dlouhá', 10000);

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

Přidá políčko pro zadání e-mailové adresy s kontrolou její platnosti (třída TextInput). Lze použít stejná validační pravidla jako pro addText.

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

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

Přidá políčko pro zadání celočíselného čísla. Lze použít stejná validační pravidla jako pro addText.

$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): static

Přidá políčko pro upload souboru (třída UploadControl). Kromě standardních validačních pravidel lze použít navíc i tato:

Form::MAX_FILE_SIZE ověřuje maximální velikost souboru int $bytes
Form::MIME_TYPE ověření MIME type string $mimeType nebo $mimeTypes[]. Může obsahovat zástupné znaky, např. video/*
Form::IMAGE ověření, že jde o obrázek JPEG, PNG nebo GIF  
Form::PATTERN testuje jméno souboru oproti regulárnímu výrazu; od nette/forms v2.4.9 string $pattern
Form::PATTERN_ICASE jako Form::PATTERN, ale nezávislé na velikosti písmen; od nette/forms v2.4.9 string $pattern
$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): static

Přidá políčko, které uživateli umožní nahrát více souborů najednou. Validační pravidla jsou stejné, jako u addUpload() a přidává následující pravidla:

Form::MIN_LENGTH minimální počet souborů int $minCount
Form::MAX_LENGTH maximální počet souborů int $maxCount
Form::LENGTH počet souborů v daném rozsahu nebo právě tento počet [int $minCount, int $maxCount] nebo int $count
$form->addMultiUpload('files', 'Soubory');

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

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

$form->addHidden('userid');

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

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

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

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): static

Přidá seznam zaškrtávacích políček pro výběr více prvků. 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 = new Form;
$form->addCheckboxList('colors', 'Barvy:', [
    'r' => 'červená',
    'g' => 'zelená',
    'b' => 'modrá',
]);

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

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

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): static

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): static

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): static

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): static

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

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

addContainer(string|int $name): static

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