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