Elementy formularza

Przegląd standardowych elementów formularza.

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

Dodaje jednoliniowe pole tekstowe (klasa TextInput). Jeśli użytkownik nie wypełni pola, zwraca pusty string '', lub za pomocą setNullable() można określić, aby zwracał null.

$form->addText('name', 'Imię:')
	->setRequired()
	->setNullable();

Automatycznie waliduje UTF-8, przycina lewo- i prawostronne spacje oraz usuwa znaki nowej linii, które mógłby wysłać atakujący.

Maksymalną długość można ograniczyć za pomocą setMaxLength(). Zmianę wartości wprowadzonej przez użytkownika umożliwia addFilter().

Za pomocą setHtmlType() można zmienić wizualny charakter pola tekstowego na typy takie jak search, tel lub url zobacz specyfikację. Pamiętaj, że zmiana typu jest tylko wizualna i nie zastępuje funkcji walidacji. Dla typu url wskazane jest dodanie specyficznej reguły walidacji URL.

Dla innych typów wejść, takich jak number, range, email, date, datetime-local, time i color, użyj specjalizowanych metod jak addInteger, addFloat, addEmail addDate, addTime, addDateTime i addColor, które zapewniają walidację po stronie serwera. Typy month i week na razie nie są w pełni obsługiwane we wszystkich przeglądarkach.

Elementowi można ustawić tzw. pustą wartość (empty-value), co jest czymś w rodzaju wartości domyślnej, ale jeśli użytkownik jej nie zmieni, element zwróci pusty string lub null.

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

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

Dodaje pole do wprowadzania tekstu wieloliniowego (klasa TextArea). Jeśli użytkownik nie wypełni pola, zwraca pusty string '', lub za pomocą setNullable() można określić, aby zwracał null.

$form->addTextArea('note', 'Notatka:')
	->addRule($form::MaxLength, 'Notatka jest zbyt długa', 10000);

Automatycznie waliduje UTF-8 i normalizuje separatory linii do \n. W przeciwieństwie do jednoliniowego pola wejściowego nie dochodzi do przycinania spacji.

Maksymalną długość można ograniczyć za pomocą setMaxLength(). Zmianę wartości wprowadzonej przez użytkownika umożliwia addFilter(). Można ustawić tzw. pustą wartość za pomocą setEmptyValue().

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

Dodaje pole do wprowadzania liczby całkowitej (klasa TextInput). Zwraca albo integer, albo null, jeśli użytkownik nic nie wpisze.

$form->addInteger('year', 'Rok:')
	->addRule($form::Range, 'Rok musi być w zakresie od %d do %d.', [1900, 2023]);

Element renderuje się jako <input type="number">. Użyciem metody setHtmlType() można zmienić typ na range do wyświetlania w postaci suwaka, lub na text, jeśli preferujesz standardowe pole tekstowe bez specjalnego zachowania typu number.

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

Dodaje pole do wprowadzania liczby dziesiętnej (klasa TextInput). Zwraca albo float, albo null, jeśli użytkownik nic nie wpisze.

$form->addFloat('level', 'Poziom:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Poziom musi być w zakresie od %d do %d.', [0, 100]);

Nette i przeglądarka Chrome akceptują jako separator miejsc dziesiętnych zarówno przecinek, jak i kropkę. Aby ta funkcjonalność była dostępna również w Firefoksie, zaleca się ustawienie atrybutu lang albo dla danego elementu, albo dla całej strony, na przykład <html lang="pl">.

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

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

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

Sprawdza, czy wartość jest prawidłowym adresem e-mail. Nie sprawdza się, czy domena faktycznie istnieje, sprawdza się tylko składnię. Automatycznie waliduje UTF-8, przycina lewo- i prawostronne spacje.

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

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

$form->addPassword('password', 'Hasło:')
	->setRequired()
	->addRule($form::MinLength, 'Hasło musi mieć co najmniej %d znaków', 8)
	->addRule($form::Pattern, 'Musi zawierać cyfrę', '.*[0-9].*');

Przy ponownym wyświetleniu formularza pole będzie puste. Automatycznie waliduje UTF-8, przycina lewo- i prawostronne spacje oraz usuwa znaki nowej linii, które mógłby wysłać atakujący.

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 zaznaczone.

$form->addCheckbox('agree', 'Zgadzam się z warunkami')
	->setRequired('Konieczna jest zgoda na warunki');

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

Dodaje pola wyboru do wyboru wielu pozycji (klasa CheckboxList). Zwraca tablicę kluczy wybranych pozycji. Metoda getSelectedItems() zwraca wartości zamiast kluczy.

$form->addCheckboxList('colors', 'Kolory:', [
	'r' => 'czerwony',
	'g' => 'zielony',
	'b' => 'niebieski',
]);

Tablicę oferowanych pozycji przekazujemy jako trzeci parametr lub metodą setItems().

Za pomocą setDisabled(['r', 'g']) można dezaktywować poszczególne pozycje.

Element automatycznie kontroluje, czy nie doszło do fałszerstwa i czy wybrane pozycje są rzeczywiście jednymi z oferowanych i nie zostały dezaktywowane. Metodą getRawValue() można uzyskać wysłane pozycje bez tej ważnej kontroli.

Przy ustawianiu domyślnych wybranych pozycji również kontroluje, czy są to jedne z oferowanych, w przeciwnym razie rzuca wyjątek. Tę kontrolę można wyłączyć za pomocą checkDefaultValue(false).

Jeśli wysyłasz formularz metodą GET, możesz wybrać bardziej kompaktowy sposób przesyłania danych, który oszczędza rozmiar query stringu. Aktywuje się go ustawieniem atrybutu HTML formularza:

$form->setHtmlAttribute('data-nette-compact');

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

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

$sex = [
	'm' => 'mężczyzna',
	'f' => 'kobieta',
];
$form->addRadioList('gender', 'Płeć:', $sex);

Tablicę oferowanych pozycji przekazujemy jako trzeci parametr lub metodą setItems().

Za pomocą setDisabled(['m', 'f']) można dezaktywować poszczególne pozycje.

Element automatycznie kontroluje, czy nie doszło do fałszerstwa i czy wybrana pozycja jest rzeczywiście jedną z oferowanych i nie została dezaktywowana. Metodą getRawValue() można uzyskać wysłaną pozycję bez tej ważnej kontroli.

Przy ustawianiu domyślnej wybranej pozycji również kontroluje, czy jest to jedna z oferowanych, w przeciwnym razie rzuca wyjątek. Tę kontrolę można wyłączyć za pomocą checkDefaultValue(false).

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

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

$countries = [
	'CZ' => 'Republika Czeska',
	'PL' => 'Polska',
	'GB' => 'Wielka Brytania',
];

$form->addSelect('country', 'Kraj:', $countries)
	->setDefaultValue('PL');

Tablicę oferowanych pozycji przekazujemy jako trzeci parametr lub metodą setItems(). Pozycje mogą być również tablicą dwuwymiarową:

$countries = [
	'Europa' => [
		'CZ' => 'Republika Czeska',
		'PL' => 'Polska',
		'GB' => 'Wielka Brytania',
	],
	'CA' => 'Kanada',
	'US' => 'USA',
	'?'  => 'inna',
];

W polach wyboru często pierwsza pozycja ma specjalne znaczenie, służy jako wezwanie do działania (prompt). Do dodania takiej pozycji służy metoda setPrompt().

$form->addSelect('country', 'Kraj:', $countries)
	->setPrompt('Wybierz kraj');

Za pomocą setDisabled(['CZ', 'SK']) można dezaktywować poszczególne pozycje.

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

Dodaje pole wyboru do wyboru wielu pozycji (klasa MultiSelectBox). Zwraca tablicę kluczy wybranych pozycji. Metoda getSelectedItems() zwraca wartości zamiast kluczy.

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

Tablicę oferowanych pozycji przekazujemy jako trzeci parametr lub metodą setItems(). Pozycje mogą być również tablicą dwuwymiarową.

Za pomocą setDisabled(['CZ', 'SK']) można dezaktywować poszczególne pozycje.

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

Dodaje pole do przesyłania pliku (klasa UploadControl). Zwraca obiekt FileUpload i to nawet w przypadku, gdy użytkownik nie wysłał żadnego pliku, co można sprawdzić metodą FileUpload::hasFile().

$form->addUpload('avatar', 'Awatar:')
	->addRule($form::Image, 'Awatar musi być JPEG, PNG, GIF, WebP lub AVIF.')
	->addRule($form::MaxFileSize, 'Maksymalny rozmiar to 1 MB.', 1024 * 1024);

Jeśli plik nie zostanie poprawnie przesłany, formularz nie jest pomyślnie wysłany i wyświetli się błąd. Tj. przy pomyślnym wysłaniu nie ma potrzeby weryfikować metody FileUpload::isOk().

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

Reguły MimeType i Image wykrywają wymagany typ na podstawie sygnatury pliku i nie weryfikują jego integralności. Czy obrazek nie jest uszkodzony można sprawdzić na przykład próbą jego wczytania.

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

Dodaje pole do przesyłania wielu plików naraz (klasa UploadControl). Zwraca tablicę obiektów FileUpload. Metoda FileUpload::hasFile() u każdego z nich będzie zwracać true.

$form->addMultiUpload('files', 'Pliki:')
	->addRule($form::MaxLength, 'Maksymalnie można przesłać %d plików', 10);

Jeśli któryś plik nie zostanie poprawnie przesłany, formularz nie jest pomyślnie wysłany i wyświetli się błąd. Tj. przy pomyślnym wysłaniu nie ma potrzeby weryfikować metody FileUpload::isOk().

Nigdy nie ufaj oryginalnym nazwom plików zwróconym przez metodę FileUpload::getName(), klient mógł wysłać szkodliwą nazwę pliku z zamiarem uszkodzenia lub zhakowania Twojej aplikacji.

addDate (string|int $name, $label=null): DateTimeControl

Dodaje pole, które umożliwia użytkownikowi łatwe wprowadzenie daty składającej się z roku, miesiąca i dnia (klasa DateTimeControl).

Jako wartość domyślną akceptuje albo obiekty implementujące interfejs DateTimeInterface, string z czasem, albo liczbę reprezentującą timestamp UNIX. To samo dotyczy argumentów reguł Min, Max lub Range, które definiują minimalną i maksymalną dozwoloną datę.

$form->addDate('date', 'Data:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'Data musi być co najmniej miesiąc stara.', new DateTime('-1 month'));

Standardowo zwraca obiekt DateTimeImmutable, metodą setFormat() możesz specyfikować format tekstowy lub timestamp:

$form->addDate('date', 'Data:')
	->setFormat('Y-m-d');

addTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Dodaje pole, które umożliwia użytkownikowi łatwe wprowadzenie czasu składającego się z godzin, minut i opcjonalnie sekund (klasa DateTimeControl).

Jako wartość domyślną akceptuje albo obiekty implementujące interfejs DateTimeInterface, string z czasem, albo liczbę reprezentującą timestamp UNIX. Z tych wejść wykorzystywana jest tylko informacja o czasie, data jest ignorowana. To samo dotyczy argumentów reguł Min, Max lub Range, które definiują minimalny i maksymalny dozwolony czas. Jeśli ustawiona minimalna wartość jest wyższa niż maksymalna, tworzy się zakres czasowy przekraczający północ.

$form->addTime('time', 'Czas:', withSeconds: true)
	->addRule($form::Range, 'Czas musi być w zakresie od %d do %d.', ['12:30', '13:30']);

Standardowo zwraca obiekt DateTimeImmutable (z datą 1. stycznia roku 1), metodą setFormat() możesz specyfikować format tekstowy:

$form->addTime('time', 'Czas:')
	->setFormat('H:i');

addDateTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Dodaje pole, które umożliwia użytkownikowi łatwe wprowadzenie daty i czasu składających się z roku, miesiąca, dnia, godzin, minut i opcjonalnie sekund (klasa DateTimeControl).

$form->addDateTime('datetime', 'Data i czas:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'Data musi być co najmniej miesiąc stara.', new DateTime('-1 month'));

Standardowo zwraca obiekt DateTimeImmutable, metodą setFormat() możesz specyfikować format tekstowy lub timestamp:

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor (string|int $name, $label=null): ColorPicker

Dodaje pole do wyboru koloru (klasa ColorPicker). Kolor jest stringiem w formacie #rrggbb. Jeśli użytkownik nie dokona wyboru, zwrócony zostanie czarny kolor #000000.

$form->addColor('color', 'Kolor:')
	->setDefaultValue('#3C8ED7');

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

Dodaje ukryte pole (klasa HiddenField).

$form->addHidden('userid');

Za pomocą setNullable() można ustawić, aby zwracał null zamiast pustego stringa. Zmianę wysłanej wartości umożliwia addFilter().

Chociaż element jest ukryty, ważne jest, aby pamiętać, że wartość może być nadal modyfikowana lub sfałszowana przez atakującego. Zawsze dokładnie sprawdzaj i waliduj wszystkie otrzymane wartości po stronie serwera, aby zapobiec ryzykom bezpieczeństwa związanym z manipulacją danymi.

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

Dodaje przycisk wysyłania (klasa SubmitButton).

$form->addSubmit('submit', 'Wyślij');

W formularzu można mieć również więcej przycisków wysyłania:

$form->addSubmit('register', 'Zarejestruj');
$form->addSubmit('cancel', 'Anuluj');

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 naciśnięciu przycisku (na przykład przy przyciskach Anuluj lub Podgląd), użyj setValidationScope().

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

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

$form->addButton('raise', 'Podnieś pensję')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

Dodaje przycisk wysyłania w postaci obrazka (klasa ImageButton).

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

Przy użyciu wielu przycisków wysyłania można dowiedzieć się, który został kliknięty, za pomocą $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Dodaje podformularz (klasa Container), czyli kontener, do którego można dodawać kolejne elementy w ten sam sposób, jak dodajemy je do formularza. Działają również metody setDefaults() lub getValues().

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Twoje imię:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Twoje imię:');
$sub2->addEmail('email', 'Email:');

Wysłane dane zwraca następnie jako strukturę wielowymiarową:

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

Przegląd ustawień

U wszystkich elementów możemy wywoływać następujące metody (kompletny przegląd w dokumentacji API):

`setDefaultValue($value)`	ustawia wartość domyślną
`getValue()`	pobiera aktualną wartość
`setOmitted()`	pominięcie-wartości
`setDisabled()`	dezaktywacja-elementów

Renderowanie:

`setCaption($caption)`	zmienia etykietę elementu
`setTranslator($translator)`	ustawia tłumacza
`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 dla renderowania

Walidacja:

`setRequired()`	element wymagany
`addRule()`	ustawienie reguły walidacyjnej
`addCondition()`, `addConditionOn()`	ustawia warunek walidacyjny
`addError($message)`	przekazanie komunikatu błędu

U elementów addText(), addPassword(), addTextArea(), addEmail(), addInteger(), addFloat() można wywoływać następujące metody:

`setNullable()`	ustawia, czy getValue() zwróci `null` zamiast pustego stringa
`setEmptyValue($value)`	ustawia specjalną wartość, która jest uważana za pusty string
`setMaxLength($length)`	ustawia maksymalną liczbę dozwolonych znaków
`addFilter($filter)`	modyfikacja wejścia

Pominięcie wartości

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

$form->addPassword('passwordVerify', 'Hasło do kontroli:')
	->setRequired('Proszę podać hasło jeszcze raz do kontroli')
	->addRule($form::Equal, 'Hasła się nie zgadzają', $form['password'])
	->setOmitted();

Dezaktywacja elementów

Elementy można dezaktywować za pomocą setDisabled(). Takiego elementu użytkownik nie może edytować.

$form->addText('username', 'Nazwa użytkownika:')
	->setDisabled();

Wyłączone elementy przeglądarka w ogóle nie wysyła na serwer, więc nie znajdziesz ich w danych zwróconych przez funkcję $form->getValues(). Jeśli jednak ustawisz setOmitted(false), Nette do tych danych dołączy ich wartość domyślną.

Przy wywołaniu setDisabled() ze względów bezpieczeństwa usuwana jest wartość elementu. Jeśli ustawiasz wartość domyślną, należy to zrobić dopiero po jego dezaktywacji:

$form->addText('username', 'Nazwa użytkownika:')
	->setDisabled()
	->setDefaultValue($userName);

Alternatywą dla wyłączonych elementów są elementy z atrybutem HTML readonly, które przeglądarka wysyła na serwer. Chociaż element jest tylko do odczytu, ważne jest, aby pamiętać, że jego wartość może być nadal modyfikowana lub sfałszowana przez atakującego.

Własne elementy

Oprócz szerokiej gamy wbudowanych elementów formularza możesz dodawać do formularza własne elementy w ten sposób:

$form->addComponent(new DateInput('Data:'), 'date');
// alternatywna składnia: $form['date'] = new DateInput('Data:');

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

Istnieje sposób, jak zdefiniować nowe metody formularza służące do dodawania własnych elementów (np. $form->addZip()). Są to tzw. metody rozszerzające (extension methods). Wadą jest to, że dla nich nie będzie działać podpowiadanie w edytorach.

use Nette\Forms\Container;

// dodajemy metodę 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, 'Co najmniej 5 cyfr', '[0-9]{5}');
});

// użycie
$form->addZip('zip', 'Kod pocztowy:');

Elementy niskopoziomowe

Można również używać elementów, które zapiszemy tylko w szablonie i nie dodamy ich do formularza za pomocą którejś z metod $form->addXyz(). Kiedy na przykład wypisujemy rekordy z bazy danych i z góry nie wiemy, ile ich będzie i jakie będą miały ID, a chcemy przy każdym wierszu wyświetlić checkbox lub radio button, wystarczy zakodować go w szablonie:

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

A po wysłaniu wartość odczytamy:

$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 jednoliniowych wejść jak text, password, email itp. i DataText dla wszystkich pozostałych), a drugi parametr sel[] odpowiada atrybutowi HTML name. Typ elementu możemy łączyć z wartością DataKeys, która zachowa klucze elementów. Jest to szczególnie przydatne dla select, radioList i checkboxList.

Istotne jest, że getHttpData() zwraca oczyszczoną wartość, w tym przypadku będzie to zawsze tablica prawidłowych stringów UTF-8, niezależnie od tego, co próbowałby podsunąć serwerowi atakujący. Jest to odpowiednik bezpośredniej pracy z $_POST lub $_GET, ale z tą istotną różnicą, że zawsze zwraca czyste dane, tak jak jesteś przyzwyczajony w standardowych elementach formularzy Nette.