Form Fields
Overview of built-in form fields.
addText($name, $label=null)
Adds single line text field (class TextInput). Automatically trims left and right side whitespace. Beside preset validation rules, the following ones are available:
Form::MIN_LENGTH |
minimal string length | int $minLength |
Form::MAX_LENGTH |
maximal string length | int $maxLength |
Form::LENGTH |
exact length | [int $min, int $max] or int $length |
Form::EMAIL |
is value a valid email address? | |
Form::URL |
is value a valid URL? | |
Form::PATTERN |
tests the entire value against a regular expression, kind of like it is inside ^ and a $ | string $pattern |
Form::PATTERN_ICASE |
like Form::PATTERN , but case-insensitive |
string $pattern |
Form::INTEGER |
is value integer? | |
Form::NUMERIC |
alias of Form::INTEGER |
|
Form::FLOAT |
is value a floating point number? | |
Form::MIN |
minimum of the integer value | int|float $minimum |
Form::MAX |
maximum of the integer value | int|float $maximum |
Form::RANGE |
is value in the range? | [int $min, int $max] |
$form->addText('zip', 'Postcode:')
->setRequired()
->addRule(Form::PATTERN, 'Postcode must have exactly 5 numerals', '([0-9]\s*){5}');
The Form::INTEGER
, NUMERIC
a FLOAT
rules automatically convert the value to
integer (or float respectively). In addition, Form::URL
automatically completes the URL, for example,
nette.org
will be completed to https://nette.org
.
addPassword(string|int $name, $label=null): static
Adds password field (class TextInput). Automatically trims left and right side whitespace. Redrawing the form renders the input empty. Supports the same set of validation rules as addText.
$form->addPassword('password', 'Password:')
->setRequired()
->addRule(Form::MIN_LENGTH, 'Password has to be at least %d characters long', 3)
->addRule(Form::PATTERN, 'Password must contain a number', '.*[0-9].*');
addTextArea(string|int $name, $label=null): static
Adds a multiline text field (class TextArea). Supports the same set of validation rules as addText. Unlike oneline inputs, it does not trim the input's whitespace on either edge.
$form->addTextArea('note', 'Note:')
->setRequired(false) // optional
->addRule(Form::MAX_LENGTH, 'Your note is way too long', 10000);
addEmail(string|int $name, $label=null): static
Adds email address field with validity check (class TextInput). Supports the same set of validation rules as addText.
$form->addEmail('email', 'Email:');
addInteger(string|int $name, $label=null): static
Adds input field for integer. Supports the same set of validation rules as addText.
$form->addInteger('level', 'Level:')
->setDefaultValue(0)
->addRule($form::RANGE, 'Level must be between %d and %d.', [0, 100]);
addUpload(string|int $name, $label=null): static
Adds file upload field (class UploadControl). Beside preset validation rules, the following ones are available:
Form::MAX_FILE_SIZE |
verifies maximal file size | int $bytes |
Form::MIME_TYPE |
checks if MIME type is valid | string $mimeType or $mimeTypes[] . Can contain wildcards, such as video/* . |
Form::IMAGE |
checks if uploaded file is JPEG, PNG or GIF | |
Form::PATTERN |
tests the file name against a regular expression | string $pattern |
Form::PATTERN_ICASE |
like Form::PATTERN , but case-insensitive |
string $pattern |
$form->addUpload('thumbnail', 'Thumbnail:')
->setRequired(false) // optional
->addRule(Form::IMAGE, 'Thumbnail must be JPEG, PNG or GIF')
->addRule(Form::MAX_FILE_SIZE, 'Maximum file size is 64 kB.', 64 * 1024 /* size in Bytes */);
addMultiUpload(string|int $name, $label=null): static
Adds multiple file upload field. Validation rules are same as addUpload()
and adds following:
Form::MIN_LENGTH |
minimal count files | int $minCount |
Form::MAX_LENGTH |
maximal count files | int $maxCount |
Form::LENGTH |
exact count of uploaded files | [int $minCount, int $maxCount] or int $count |
$form->addMultiUpload('files', 'Files');
addHidden(string|int $name, string $default=null): static
Adds hidden field (class HiddenField).
$form->addHidden('userid');
addCheckbox(string|int $name, $caption=null): static
Adds a checkbox (class Checkbox). The return value
is either Boolean true
or false
, as checked or not checked.
$form->addCheckbox('agree', 'I agree with terms')
->setRequired('You must agree with our terms');
addRadioList(string|int $name, $label=null, array $items=null): static
Adds radio buttons (class RadioList). Array of offered values is passed as the third argument.
$sex = [
'm' => 'male',
'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);
// to list options within 1 line
$form->addRadioList('gender', 'Gender:', $sex)
->getSeparatorPrototype()->setName(null);
addCheckboxList(string|int $name, $label=null, array $items=null): static
Adds list of checkboxes for selecting multiple elements. Array of values is passed as the third argument. The component checks if the submitted values are from the given range.
$form->addCheckboxList('colors', 'Colors:', [
'r' => 'red',
'g' => 'green',
'b' => 'blue',
]);
addSelect(string|int $name, $label=null, array $items=null): static
Adds select box (class SelectBox). Array of offered
values is passed as third argument. Might as well be two-dimensional. The first item is often used as a call-to-action message,
but worthless when actually selected – that's what method setPrompt()
is for.
$countries = [
'Europe' => [
'CZ' => 'Czech republic',
'SK' => 'Slovakia',
'GB' => 'United Kingdom',
],
'CA' => 'Canada',
'US' => 'USA',
'?' => 'other',
];
$form->addSelect('country', 'Country:', $countries)
->setPrompt('Pick a country');
You can also add elements by using the setItems() method. If we want to get their values directly in place of key items, we can do this with the second argument:
$form->addSelect('country', 'Country:')
->setItems($countries, false);
Individual items may be, in addition to strings, objects Nette\Utils\Html::('option')
, which then can set
additional HTML attributes. However, the selected
and disabled
attributes do not set this way, the form
itself takes care of it. This also applies to addMultiSelect()
.
addMultiSelect(string|int $name, $label=null, array $items=null): static
Adds multichoice select box (class MultiSelectBox).
$form->addMultiSelect('options', 'Pick many:', $options);
addSubmit(string|int $name, $caption=null): static
Adds submit button (class SubmitButton).
$form->addSubmit('submit', 'Register');
It's okay to add more than one submit button.
$form->addSubmit('submit', 'Register');
$form->addSubmit('cancel', 'Cancel');
To find out which of them was clicked, use:
if ($form['submit']->isSubmittedBy()) {
// ...
}
If you don't want to validate the form when a submit button is pressed (such as Cancel or Preview buttons), you
can turn it off with setValidationScope([])
.
addButton(string|int $name, $caption): static
Adds button (class Button) without submit function. It is useful for binding other functionality to id, for example a JavaScript action.
$form->addButton('raise', 'Raise salary')
->setHtmlAttribute('onclick', 'raiseSalary()');
addImage(string|int $name, $alt=null): static
Adds submit button in form of an image (class ImageButton).
$form->addImage('submit', '/path/to/image');
addContainer(string|int $name): static
Adds a sub-form (class Container), or a container, which can
be treated the same way as a form. That means you can use methods like setDefaults()
or 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:');