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

Za pomocą setHtmlType() można zmienić znak elementu wejściowego na search, tel, url, range, month, week, lub color. Dla innych typów, takich jak number, email, date, datetime-local i time, istnieją oddzielne metody addInteger, addFloat, addEmail, addDate, addTimeaddDateTime, które są dostarczane z 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('year', 'Year:')
	->addRule($form::Range, 'Rok musi być z zakresu %d do %d.', [1900, 2023 |1900, 2023]);

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 Chrome akceptują zarówno przecinek, jak i kropkę jako separator dziesiętny. Aby Firefox również akceptował przecinek, należy ustawić odpowiedni język w atrybucie HTML lang, bezpośrednio w tym elemencie lub w dowolnym elemencie nadrzędnym, na przykład <html lang="cs">.

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.

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

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.

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

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

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

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

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

Po wywołaniu funkcji setDisabled(), wartość pola zostanie usunięta. Jeśli ustawiasz wartość domyślną, musisz to zrobić po jej 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.

wersja: 4.0