Elementy formularza

Przegląd standardowych elementów formularza.

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

Dodaje jednolinijkowe pole tekstowe (klasa TextInput). Jeśli użytkownik nie wypełni pola, zwraca pusty ciąg '', lub setNullable() może być użyty do określenia, że zwraca null.

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

Automatycznie waliduje UTF-8, obcina lewe i prawe spacje oraz usuwa przerwy w linii, które mógłby wysłać atakujący.

Maksymalna długość może być ograniczona za pomocą setMaxLength(). Modyfikacja wartości wprowadzonej przez użytkownika umożliwia addFilter().

Używając setHtmlType(), charakter elementu wejściowego można zmienić na search, tel, url, range, date, datetime-local, month, time, week, color. Zalecamy użycie addInteger i addEmail zamiast typów number i email, które mają walidację po stronie serwera.

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

Element może być ustawiony na empty-value, co jest jak wartość domyślna, ale jeśli użytkownik nie zmieni go, element zwróci pusty ciąg lub null.

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

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

Dodaje tablicę do wprowadzania tekstu wieloliniowego (klasa TextArea). Jeśli użytkownik nie wypełni pola, zwraca pusty ciąg '', lub setNullable() może być użyty do określenia, że zwraca null.

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

Automatycznie sprawdza UTF-8 i normalizuje separatory linii do \n. W przeciwieństwie do pola wejściowego z jednym wierszem, nie występuje przycinanie spacji.

Maksymalna długość może być ograniczona przy użyciu setMaxLength(). Funkcja addFilter() pozwala na modyfikację wartości wprowadzonej przez użytkownika. Wartość pusta może być ustawiona przy użyciu setEmptyValue().

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

Dodaje pole do wprowadzania liczby całkowitej (klasa TextInput). Zwraca liczbę całkowitą lub null, jeśli użytkownik nic nie wprowadzi.

$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

Dodaje pole do wpisania adresu e-mail (klasa TextInput). Jeśli użytkownik nie wypełni pola, zwraca pusty ciąg '', lub można określić setNullable(), aby zwrócić null.

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

Sprawdza, czy podana wartość jest prawidłowym adresem e-mail. Nie sprawdza, czy domena faktycznie istnieje, sprawdzana jest tylko składnia. Automatycznie waliduje UTF-8, obcina lewe i prawe spacje.

Maksymalna długość może być ograniczona przy użyciu setMaxLength(). AddFilter() może być użyty do modyfikacji wartości wprowadzonej przez użytkownika. Pusta wartość może być ustawiona przy użyciu setEmptyValue().

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

Dodaje pole do wpisania hasła (klasa TextInput).

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

Gdy formularz zostanie ponownie wyświetlony, pole będzie puste. Automatycznie waliduje UTF-8, obcina lewe i prawe spacje oraz usuwa przerwy w linii, które mogłyby zostać wysłane przez atakującego.

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

Dodaje pole wyboru (klasa Checkbox). Zwraca wartość albo true albo false, w zależności od tego czy jest zaznaczona.

$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

Dodaje pola wyboru do zaznaczania wielu elementów (klasa CheckboxList). Zwraca tablicę kluczy dla wybranych elementów. Metoda getSelectedItems() zwraca wartości zamiast kluczy.

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

Przekaż tablicę oferowanych elementów jako trzeci parametr lub metodą setItems().

Korzystanie z setDisabled(['r', 'g']) metoda do dezaktywacji poszczególnych elementów.

Element ten automatycznie sprawdza, czy nie doszło do oszustwa oraz czy wybrane pozycje są rzeczywiście jednymi z oferowanych i nie zostały dezaktywowane. Metoda getRawValue() może być użyta do odzyskania elementów wysłanych bez tego ważnego sprawdzenia.

Podczas ustawiania domyślnych wybranych elementów sprawdza również, czy są one jednym z oferowanych elementów, w przeciwnym razie rzuca wyjątek. To sprawdzanie można wyłączyć za pomocą checkDefaultValue(false).

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

Dodaje przyciski radiowe (klasa RadioList). Zwraca klucz wybranego elementu lub null, jeśli użytkownik nic nie wybrał. Metoda getSelectedItem() zwraca wartość zamiast klucza.

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

Przekaż tablicę oferowanych elementów jako trzeci parametr lub metody setItems().

Korzystanie z setDisabled(['m', 'f']) metoda do dezaktywacji poszczególnych elementów.

Element automatycznie sprawdza, czy nie doszło do podebrania oraz czy wybrana pozycja jest rzeczywiście jedną z oferowanych pozycji i nie została dezaktywowana. Metoda getRawValue() może być użyta do odzyskania przesłanego elementu bez tego ważnego sprawdzenia.

Po ustawieniu domyślnego wybranego elementu sprawdza również, czy jest to jeden z oferowanych elementów, w przeciwnym razie rzuca wyjątek. To sprawdzanie można wyłączyć za pomocą checkDefaultValue(false).

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

Dodaje pole wyboru (klasa SelectBox). Zwraca klucz wybranego elementu lub null, jeśli użytkownik nic nie wybrał. Metoda getSelectedItem() zwraca wartość zamiast klucza.

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

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

Przekaż tablicę oferowanych elementów jako trzeci parametr lub przez metodę setItems() Elementy mogą być tablicami dwuwymiarowymi:

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

W przypadku select boxów pierwszy element ma często specjalne znaczenie, służy jako call to action. Do dodania takiego elementu służy metoda setPrompt().

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

Korzystanie z setDisabled(['CZ', 'SK']) metoda do dezaktywacji poszczególnych elementów.

Pozycja automatycznie sprawdza, czy nie doszło do oszustwa oraz czy wybrany przedmiot jest rzeczywiście jednym z oferowanych przedmiotów i nie został dezaktywowany. Metoda getRawValue() może być użyta do odzyskania przesłanego elementu bez tego ważnego sprawdzenia.

Gdy ustawiony jest domyślny wybrany element, sprawdza również, czy jest to jeden z oferowanych elementów, w przeciwnym razie rzuca wyjątek. To sprawdzanie można wyłączyć za pomocą checkDefaultValue(false).

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

Dodaje select box do wyboru wielu elementów (klasa MultiSelectBox). Zwraca tablicę kluczy dla wybranych elementów. Metoda getSelectedItems() zwraca wartości zamiast kluczy.

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

Przekaż tablicę oferowanych elementów jako trzeci parametr lub przez metodę setItems() Elementy mogą być tablicami dwuwymiarowymi.

Korzystanie z setDisabled(['CZ', 'SK']) aby dezaktywować poszczególne elementy.

Element ten automatycznie sprawdza, czy nie doszło do oszustwa oraz czy wybrane pozycje są rzeczywiście jednymi z oferowanych i nie zostały dezaktywowane. Metoda getRawValue() może być użyta do odzyskania przesłanych elementów bez tego ważnego sprawdzenia.

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

Dodaje pole wyboru dla przesyłania plików (klasa UploadControl). Zwraca obiekt FileUpload nawet jeśli użytkownik nie przesłał żadnego pliku, co można wykryć za pomocą metody FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar musí být JPEG, PNG, GIF or WebP.')
	->addRule($form::MaxFileSize, 'Maximální velikost je 1 MB.', 1024 * 1024);

Jeśli plik nie zostanie załadowany poprawnie, formularz nie zostanie pomyślnie przesłany i zostanie wyświetlony błąd. Tzn. Jeśli przesłanie jest udane, nie ma potrzeby sprawdzania metody FileUpload::isOk().

Nigdy nie ufaj oryginalnej nazwie pliku zwróconej przez metodę FileUpload::getName(), klient mógł przesłać złośliwą nazwę pliku z zamiarem uszkodzenia lub zhakowania twojej aplikacji.

Reguły MimeType i Image wykrywają żądany typ na podstawie sygnatury pliku i nie sprawdzają jego integralności. Możesz określić, czy obraz nie jest uszkodzony, na przykład próbując go odzyskać.

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

Dodaje pole wyboru do przesyłania wielu plików jednocześnie (klasa UploadControl). Zwraca tablicę obiektów FileUpload. Metoda FileUpload::hasFile() dla każdego z nich zwróci true.

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

Jeśli jakikolwiek plik nie zostanie załadowany poprawnie, formularz nie zostanie pomyślnie przesłany i zostanie wyświetlony błąd. Tzn. Jeśli złożenie jest udane, nie ma potrzeby sprawdzania metody FileUpload::isOk().

Nigdy nie ufaj oryginalnym nazwom plików zwracanym przez metodę FileUpload::getName(), klient mógł przesłać złośliwą nazwę pliku z zamiarem uszkodzenia lub zhakowania twojej aplikacji.

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

Dodaje ukryte pole (klasa HiddenField).

$form->addHidden('userid');

Używając setNullable(), można go ustawić, aby zwracał null zamiast pustego łańcucha. Modyfikuje wartość przesłaną przez addFilter().

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

Dodaje przycisk wysyłania (klasa SubmitButton).

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

Możliwe jest również posiadanie wielu przycisków submit w formularzu:

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

Aby dowiedzieć się, który z nich został kliknięty, użyj:

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

Jeśli nie chcesz walidować całego formularza po kliknięciu przycisku (na przykład dla przycisków Cancel lub Preview), użyj funkcji setValidationScope().

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

Dodaje przycisk (klasa Button), który nie posiada funkcji wysyłania. Może więc zostać wykorzystany do jakiejś innej funkcji, np. wywołania funkcji JavaScript po kliknięciu.

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

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

Dodaje przycisk submit w postaci obrazka (klasa ImageButton).

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

W przypadku korzystania z wielu przycisków wysyłania, możliwe jest sprawdzenie, który z nich został kliknięty przez $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Dodaje podformularz (klasa Container), czyli kontener, do którego można dodawać inne elementy w taki sam sposób, jak dodaje się je do formularza. Sprawdzają się również metody setDefaults() lub 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:');

Następnie zwraca przekazane dane jako strukturę wielowymiarową:

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

Przegląd ustawień

Dla wszystkich elementów możemy wywołać następujące metody (pełny przegląd znajduje się w dokumentacji API):

`setDefaultValue($value)`	ustawia wartość domyślną
`getValue()`	uzyskać aktualną wartość
`setOmitted()`	pomiń wartość
`setDisabled()`	dezaktywować elementy

Rendering:

`setCaption($caption)`	zmienia etykietę elementu
`setTranslator($translator)`	ustawia kompilator
`setHtmlAttribute($name, $value)`	ustawia atrybut HTML elementu
`setHtmlId($id)`	ustawia atrybut HTML `id`
`setHtmlType($type)`	ustawia atrybut HTML `type`
`setHtmlName($name)`	ustawia atrybut HTML `name`
`setOption($key, $value)`	Ustawienia renderingu

Walidacja:

`setRequired()`	Element obowiązkowy
`addRule()`	Ustawienia reguł walidacji
`addCondition()`, `addConditionOn()`	Ustawić warunek walidacji
`addError($message)`	Przekazanie komunikatu o błędzie

Poniższe metody można wywołać dla elementów addText(), addPassword(), addTextArea(), addEmail(), addInteger():

`setNullable()`	określa, czy funkcja getValue() zwróci `null` zamiast pustego łańcucha
`setEmptyValue($value)`	ustawia specjalną wartość, która jest traktowana jako pusty łańcuch
`setMaxLength($length)`	określa maksymalną liczbę dozwolonych znaków
`addFilter($filter)`	edit input

Pomijanie wartości

Jeśli nie interesuje nas wartość wypełniona przez użytkownika, możemy użyć setOmitted(), aby pominąć ją w wyniku metody $form->getValues() lub w danych przekazywanych do handlerów. Jest to przydatne dla różnych sprawdzarek haseł, elementów antyspamowych itp.

$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();

Dezaktywacja elementów

Elementy mogą być dezaktywowane za pomocą setDisabled(). Użytkownik nie może edytować takich elementów.

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

Należy pamiętać, że elementy wyłączone nie są w ogóle wysyłane przez przeglądarkę do serwera, więc nie znajdziemy ich w danych zwracanych przez funkcję $form->getValues().

Jeśli ustawisz wartość domyślną dla elementu, musisz to zrobić dopiero po jego dezaktywacji:

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

Elementy niestandardowe

Oprócz szerokiej gamy wbudowanych elementów formularza, możesz dodać do swojego formularza elementy niestandardowe w następujący sposób:

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

Formularz jest potomkiem klasy Container, a elementy są potomkami Component.

Istnieje sposób definiowania nowych metod formularza do dodawania niestandardowych elementów (np. $form->addZip()). Są one nazywane metodami rozszerzenia. Wadą jest to, że podpowiedzi edytora nie będą dla nich działać.

use Nette\Forms\Container;

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

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

Elementy niskiego poziomu

Można również wykorzystać elementy, które zapisujemy tylko w szablonie i nie dodajemy ich do formularza, korzystając z jednej z metod $form->addXyz(). Przykładowo, jeśli wypisujemy rekordy z bazy danych i nie wiemy z góry, ile ich będzie i jakie będą miały ID, a chcemy wyświetlić checkbox lub radio button dla każdego wiersza, wystarczy, że zakodujemy to w szablonie:

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

A po złożeniu wartości dowiemy się:

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

gdzie pierwszy parametr to typ elementu (DataFile dla type=file, DataLine dla wpisów jednowierszowych jak text, password, email itd. oraz DataText dla wszystkich pozostałych), a drugi parametr sel[] odpowiada nazwie atrybutu HTML. Typ elementu można połączyć z wartością DataKeys, która zachowuje klucze elementów. Jest to szczególnie przydatne dla select, radioList i checkboxList.

Co ważne, getHttpData() zwraca sanitowaną wartość, w takim przypadku zawsze będzie to tablica prawidłowych łańcuchów UTF-8, bez względu na to, co atakujący może próbować zasunąć serwer. Jest to podobne do pracy bezpośrednio z $_POST lub $_GET, ale z ważną różnicą, że zawsze zwraca czyste dane, tak jak jesteś przyzwyczajony do standardowych elementów formularza Nette.