Elementy formularza

*******************

.[perex]

Przegląd standardowych elementów formularza.

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

==================================================================================================

Dodaje jednoliniowe pole tekstowe (klasa [TextInput |api:Nette\Forms\Controls\TextInput]). Jeśli użytkownik nie wypełni pola, zwraca pusty string `''`, lub za pomocą `setNullable()` można określić, aby zwracał `null`.

```php

$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() |validation#Modyfikacja danych wejściowych].

Za pomocą `setHtmlType()` można zmienić wizualny charakter pola tekstowego na typy takie jak `search`, `tel` lub `url` zobacz [specyfikację|https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types]. 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 |validation#Wejścia tekstowe].

.[note]

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

```php

$form->addText('phone', 'Telefon:')

->setHtmlType('tel')

->setEmptyValue('+48');

```

addTextArea(string|int $name, $label=null): TextArea .[method]

==============================================================

Dodaje pole do wprowadzania tekstu wieloliniowego (klasa [TextArea |api:Nette\Forms\Controls\TextArea]). Jeśli użytkownik nie wypełni pola, zwraca pusty string `''`, lub za pomocą `setNullable()` można określić, aby zwracał `null`.

```php

$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() |validation#Modyfikacja danych wejściowych]. Można ustawić tzw. pustą wartość za pomocą `setEmptyValue()`.

addInteger(string|int $name, $label=null): TextInput .[method]

==============================================================

Dodaje pole do wprowadzania liczby całkowitej (klasa [TextInput |api:Nette\Forms\Controls\TextInput]). Zwraca albo integer, albo `null`, jeśli użytkownik nic nie wpisze.

```php

$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 .[method]{data-version:3.1.12}

=================================================================================

Dodaje pole do wprowadzania liczby dziesiętnej (klasa [TextInput |api:Nette\Forms\Controls\TextInput]). Zwraca albo float, albo `null`, jeśli użytkownik nic nie wpisze.

```php

$form->addFloat('level', 'Poziom:')

->setDefaultValue(0)

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

```

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

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 .[method]

================================================================================

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

```php

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

Maksymalną długość można ograniczyć za pomocą `setMaxLength()`. Zmianę wartości wprowadzonej przez użytkownika umożliwia [addFilter() |validation#Modyfikacja danych wejściowych]. Można ustawić tzw. pustą wartość za pomocą `setEmptyValue()`.

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

======================================================================================================

Dodaje pole do wprowadzania hasła (klasa [TextInput |api:Nette\Forms\Controls\TextInput]).

```php

$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 .[method]

================================================================

Dodaje pole wyboru (klasa [Checkbox |api:Nette\Forms\Controls\Checkbox]). Zwraca wartość albo `true`, albo `false`, w zależności od tego, czy jest zaznaczone.

```php

$form->addCheckbox('agree', 'Zgadzam się z warunkami')

->setRequired('Konieczna jest zgoda na warunki');

```

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

==========================================================================================

Dodaje pola wyboru do wyboru wielu pozycji (klasa [CheckboxList |api:Nette\Forms\Controls\CheckboxList]). Zwraca tablicę kluczy wybranych pozycji. Metoda `getSelectedItems()` zwraca wartości zamiast kluczy.

```php

$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:

```php

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

```

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

====================================================================================

Dodaje przyciski opcji (klasa [RadioList |api:Nette\Forms\Controls\RadioList]). Zwraca klucz wybranej pozycji, lub `null`, jeśli użytkownik nic nie wybrał. Metoda `getSelectedItem()` zwraca wartość zamiast klucza.

```php

$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 .[method]

==================================================================================================

Dodaje pole wyboru (klasa [SelectBox |api:Nette\Forms\Controls\SelectBox]). Zwraca klucz wybranej pozycji, lub `null`, jeśli użytkownik nic nie wybrał. Metoda `getSelectedItem()` zwraca wartość zamiast klucza.

```php

$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ą:

```php

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

```php

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

->setPrompt('Wybierz kraj');

```

Za pomocą `setDisabled(['CZ', 'SK'])` 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)`.

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

============================================================================================================

Dodaje pole wyboru do wyboru wielu pozycji (klasa [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Zwraca tablicę kluczy wybranych pozycji. Metoda `getSelectedItems()` zwraca wartości zamiast kluczy.

```php

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

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

addUpload(string|int $name, $label=null): UploadControl .[method]

=================================================================

Dodaje pole do przesyłania pliku (klasa [UploadControl |api:Nette\Forms\Controls\UploadControl]). Zwraca obiekt [FileUpload |http:request#FileUpload] i to nawet w przypadku, gdy użytkownik nie wysłał żadnego pliku, co można sprawdzić metodą `FileUpload::hasFile()`.

```php

$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 |http:request#toImage].

addMultiUpload(string|int $name, $label=null): UploadControl .[method]

======================================================================

Dodaje pole do przesyłania wielu plików naraz (klasa [UploadControl |api:Nette\Forms\Controls\UploadControl]). Zwraca tablicę obiektów [FileUpload |http:request#FileUpload]. Metoda `FileUpload::hasFile()` u każdego z nich będzie zwracać `true`.

```php

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

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 |http:request#toImage].

addDate(string|int $name, $label=null): DateTimeControl .[method]{data-version:3.1.14}

======================================================================================

Dodaje pole, które umożliwia użytkownikowi łatwe wprowadzenie daty składającej się z roku, miesiąca i dnia (klasa [DateTimeControl |api:Nette\Forms\Controls\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ę.

```php

$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|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] lub timestamp:

```php

$form->addDate('date', 'Data:')

->setFormat('Y-m-d');

```

addTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}

===============================================================================================================

Dodaje pole, które umożliwia użytkownikowi łatwe wprowadzenie czasu składającego się z godzin, minut i opcjonalnie sekund (klasa [DateTimeControl |api:Nette\Forms\Controls\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.

```php

$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|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters]:

```php

$form->addTime('time', 'Czas:')

->setFormat('H:i');

```

addDateTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}

===================================================================================================================

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 |api:Nette\Forms\Controls\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ę.

```php

$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|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] lub timestamp:

```php

$form->addDateTime('datetime')

->setFormat(DateTimeControl::FormatTimestamp);

```

addColor(string|int $name, $label=null): ColorPicker .[method]{data-version:3.1.14}

===================================================================================

Dodaje pole do wyboru koloru (klasa [ColorPicker |api:Nette\Forms\Controls\ColorPicker]). Kolor jest stringiem w formacie `#rrggbb`. Jeśli użytkownik nie dokona wyboru, zwrócony zostanie czarny kolor `#000000`.

```php

$form->addColor('color', 'Kolor:')

->setDefaultValue('#3C8ED7');

```

addHidden(string|int $name, ?string $default=null): HiddenField .[method]

=========================================================================

Dodaje ukryte pole (klasa [HiddenField |api:Nette\Forms\Controls\HiddenField]).

```php

$form->addHidden('userid');

```

Za pomocą `setNullable()` można ustawić, aby zwracał `null` zamiast pustego stringa. Zmianę wysłanej wartości umożliwia [addFilter() |validation#Modyfikacja danych wejściowych].

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 .[method]

==================================================================

Dodaje przycisk wysyłania (klasa [SubmitButton |api:Nette\Forms\Controls\SubmitButton]).

```php

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

```

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

```php

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

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

```

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

```php

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() |validation#Wyłączenie walidacji].

addButton(string|int $name, $caption): Button .[method]

=======================================================

Dodaje przycisk (klasa [Button |api:Nette\Forms\Controls\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.

```php

$form->addButton('raise', 'Podnieś pensję')

->setHtmlAttribute('onclick', 'raiseSalary()');

```

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

=============================================================================================

Dodaje przycisk wysyłania w postaci obrazka (klasa [ImageButton |api:Nette\Forms\Controls\ImageButton]).

```php

$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 .[method]

===================================================

Dodaje podformularz (klasa [Container|api:Nette\Forms\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()`.

```php

$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ą:

```php

[

'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|https://api.nette.org/forms/master/Nette/Forms/Controls.html]):

.[table-form-methods language-php]

| `setDefaultValue($value)` | ustawia wartość domyślną

| `getValue()` | pobiera aktualną wartość

| `setOmitted()` | [#pominięcie-wartości]

| `setDisabled()` | [#dezaktywacja-elementów]

Renderowanie:

.[table-form-methods language-php]

| `setCaption($caption)` | zmienia etykietę elementu

| `setTranslator($translator)` | ustawia [tłumacza |rendering#Tłumaczenie]

| `setHtmlAttribute($name, $value)` | ustawia [atrybut HTML |rendering#Atrybuty 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 |rendering#Opcje]

Walidacja:

.[table-form-methods language-php]

| `setRequired()` | [element wymagany |validation]

| `addRule()` | ustawienie [reguły walidacyjnej |validation#Reguły]

| `addCondition()`, `addConditionOn()` | ustawia [warunek walidacyjny |validation#Warunki]

| `addError($message)` | [przekazanie komunikatu błędu |validation#Błędy podczas przetwarzania]

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

.[table-form-methods language-php]

| `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 |validation#Modyfikacja danych wejściowych]

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.

```php

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

```php

$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:

```php

$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:

```php

$form->addComponent(new DateInput('Data:'), 'date');

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

```

.[note]

Formularz jest potomkiem klasy [Container |component-model:#Container], a poszczególne elementy są potomkami [Component |component-model:#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.

```php

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:

```latte

{foreach $items as $item}

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

{/foreach}

```

A po wysłaniu wartość odczytamy:

```php

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