Elementy formularza

Przegląd standardowych elementów formularza.

addText (string|int $name, $label=null, $cols, ?int $maxLength=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().

Można zmienić wizualny charakter pola tekstowego na typy takie jak search, tel, lub url przy użyciu setHtmlType(), jak pokazano w specyfikacji. Należy pamiętać, że zmiana typu jest tylko wizualna i nie wykonuje funkcji walidacji. W przypadku typu url należy dodać określoną regułę adresu URL.

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

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('year', 'Year:')
	->addRule($form::Range, 'Rok musi być z zakresu %d do %d.', [1900, 2023 |1900, 2023]);

Element jest renderowany jako <input type="numeric">. Za pomocą metody setHtmlType() można zmienić typ na range, aby wyświetlić jako suwak, lub na text, jeśli wolisz standardowe pole tekstowe bez specjalnego zachowania numeric.

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

Adds a field for entering a decimal number (TextInput class). Returns either float or null, if the user does not specify anything.

$form->addFloat('level', 'Level:')
	->setDefaultValue(0)
->addRule($form::Range, 'The level must be in the range %d to %d.', [0, 100 |0, 100]);

Nette i przeglądarka Chrome akceptują zarówno przecinek, jak i kropkę jako separatory dziesiętne. Aby udostępnić tę funkcjonalność w przeglądarce Firefox, zaleca się ustawienie atrybutu lang albo dla określonego elementu, albo dla całej strony, na przykład, <html lang="cs">.

addEmail (string|int $name, $label=null, int $maxLength=255): 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, $cols, ?int $maxLength=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).

Jeśli przesyłasz formularz za pomocą metody GET, możesz wybrać bardziej kompaktową metodę przesyłania danych, która oszczędza rozmiar ciągu zapytania. Jest to aktywowane poprzez ustawienie atrybutu HTML formularza:

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

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, ?int $size=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, ?int $size=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.

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

Dodaje pole, które pozwala użytkownikowi łatwo wprowadzić datę składającą się z roku, miesiąca i dnia (klasa DateTimeControl).

Dla wartości domyślnej akceptuje obiekty implementujące DateTimeInterface, ciąg znaków z czasem lub liczbę reprezentującą znacznik czasu UNIX. To samo dotyczy argumentów reguł Min, Max lub Range, które definiują minimalną i maksymalną dozwoloną datę.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Domyślnie zwraca ona obiekt DateTimeImmutable. Za pomocą metody setFormat() można określić format tekstowy lub znacznik czasu:

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

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

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

Dla wartości domyślnej akceptuje obiekty implementujące DateTimeInterface, ciąg znaków z czasem lub liczbę reprezentującą znacznik czasu UNIX. Używane są tylko informacje o czasie z tych danych wejściowych; data jest ignorowana. To samo dotyczy argumentów reguł Min, Max lub Range, które definiują minimalny i maksymalny dozwolony czas. Jeśli ustawiona wartość minimalna jest wyższa niż maksymalna, tworzony jest zakres czasu obejmujący północ.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

Domyślnie zwraca obiekt DateTimeImmutable (z datą 1 stycznia, rok 1). Za pomocą metody setFormat() można określić format tekstowy:

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

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

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

$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Domyślnie zwraca ona obiekt DateTimeImmutable. Za pomocą metody setFormat() można określić format tekstowy lub znacznik czasu:

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

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

Dodaje pole wyboru koloru (klasa ColorPicker). Kolor jest ciągiem znaków w formacie #rrggbb. Jeśli użytkownik nie dokona wyboru, domyślnym zwracanym kolorem jest czarny #000000.

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

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().

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

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

Wejścia można wyłączyć za pomocą setDisabled(). Wyłączone wejście nie może być edytowane przez użytkownika.

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

Wyłączone wejścia nie są wysyłane do serwera przez przeglądarkę, więc nie znajdziesz ich w danych zwracanych przez funkcję $form->getValues(). Jeśli jednak ustawisz setOmitted(false), Nette uwzględni ich domyślną wartość w tych danych.

Gdy wywoływana jest funkcja setDisabled(), wartość wejściowa jest usuwana ze względów bezpieczeństwa. W przypadku ustawiania wartości domyślnej należy to zrobić po jej dezaktywacji:

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

Alternatywą dla wyłączonych danych wejściowych są pola z atrybutem HTML readonly, które są wysyłane do serwera przez przeglądarkę. Chociaż pole jest tylko czytelne, ważne jest, aby zdać sobie sprawę, że jego wartość może zostać zmodyfikowana lub sfałszowana przez atakującego.

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.