Контроли на формуляра

Преглед на вградените контроли на формуляра.

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

Добавя текстово поле с един ред (клас TextInput). Ако потребителят не попълни полето, се връща празен низ '', или използвайте setNullable(), за да върнете null.

$form->addText('name', 'Имя:')
	->setRequired()
	->setNullable();

Този метод автоматично проверява UTF-8, подрязва левите и десните интервали и премахва прекъсванията на редовете, които могат да бъдат изпратени от атакуващ.

Максималната дължина може да бъде ограничена с помощта на setMaxLength(). Функцията addFilter() позволява да се промени стойността, въведена от потребителя.

Използвайте setHtmlType(), за да промените типа на входния елемент на search, tel, url, range, date, datetime-local, month, time, week, color. Препоръчваме да използвате addInteger и addEmail вместо number и email, тъй като те осигуряват валидиране от страна на сървъра.

$form->addText('color', 'Выберите цвет:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'недопустимое значение', '[0-9a-f]{6}');

Един елемент може да бъде зададен на така наречената “празна стойност”, която е нещо подобно на стойността по подразбиране, но ако потребителят не я презапише, тя връща празен низ или null.

$form->addText('phone', 'Телефон:')
	->setHtmlType('tel')
	->setEmptyValue('+420');

addTextArea(string|int $name, $label=null): TextArea

Добавя многоредово текстово поле (клас TextArea). Ако потребителят не попълни полето, се връща празен низ '' или използвайте setNullable(), за да върнете null.

$form->addTextArea('note', 'Примечание:')
	->addRule($form::MaxLength, 'Ваша заметка слишком длинная', 10000);

Автоматично проверява UTF-8 и нормализира прекъсванията на редовете до \n. За разлика от едноредовото поле за въвеждане, то не съкращава белите полета.

Максималната дължина може да бъде ограничена с помощта на setMaxLength(). Функцията addFilter() ви позволява да промените стойността, въведена от потребителя. Можете да зададете така наречената “празна стойност”, като използвате setEmptyValue().

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

Добавя поле за въвеждане на цяло число (клас TextInput). Връща цяло число или null, ако потребителят не е въвел нищо.

$form->addInteger('level', 'Уровень:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Уровень должен быть между %d и %d.', [0, 100]);

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

Добавя валидирано поле за имейл адрес (клас TextInput). Ако потребителят не е попълнил полето, се връща празен низ '' или използвайте setNullable(), за да върнете null.

$form->addEmail('email', 'Имейл:');

Проверява дали стойността е валиден имейл адрес. Не се проверява дали домейнът действително съществува, проверява се само синтаксисът. Автоматично проверява UTF-8, подрязва левите и десните интервали.

Максималната дължина може да бъде ограничена с помощта на setMaxLength(). Функцията addFilter() ви позволява да промените стойността, въведена от потребителя. Можете да зададете така наречената “празна стойност”, като използвате setEmptyValue().

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

Добавя поле за парола (клас TextInput).

$form->addPassword('password', 'Пароль:')
	->setRequired()
	->addRule($form::MinLength, 'Пароль должен быть длиной не менее %d символов', 8)
	->addRule($form::Pattern, 'Пароль должен содержать цифры', '.*[0-9].*');

Когато формулярът се изпрати отново, входът ще бъде празен. Той автоматично проверява UTF-8, подрязва левите и десните интервали и премахва прекъсванията на редовете, които могат да бъдат изпратени от атакуващ.

addCheckbox(string|int $name, $caption=null): Checkbox

Добавя квадратче за отметка (клас Checkbox). Полето връща или true, или false, в зависимост от това дали е маркирано.

$form->addCheckbox('agree', 'Я согласен с условиями')
	->setRequired('Вы должны согласиться с нашими условиями');

addCheckboxList(string|int $name, $label=null, array $items=null): CheckboxList

Добавя списък с квадратчета за избор на няколко елемента (клас CheckboxList). Връща масив от ключове на избрани елементи. Методът getSelectedItems() връща стойности вместо ключове.

$form->addCheckboxList('colors', 'Цвета:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Предаваме масив от елементи като трети параметър или метод setItems().

Можете да използвате setDisabled(['r', 'g']) за деактивиране на отделни елементи.

Елементът автоматично проверява дали не е извършена манипулация и дали избраните елементи наистина са едни от предлаганите и не са били деактивирани. Методът getRawValue() може да се използва за получаване на елементи, изпратени без тази важна проверка.

При задаване на стойности по подразбиране се проверява също дали те са един от предлаганите елементи, в противен случай се прави изключение. Тази проверка може да бъде деактивирана с помощта на checkDefaultValue(false).

addRadioList(string|int $name, $label=null, array $items=null): RadioList

Добавя радио бутони (клас RadioList). Връща ключа на избрания елемент или null, ако потребителят не е избрал нищо. Методът getSelectedItem() връща стойност вместо ключ.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Пол:', $sex);

Предаваме масив от елементи като трети параметър или на метода setItems().

Можете да използвате setDisabled(['m']) за деактивиране на отделни елементи.

Елементът автоматично проверява дали не е извършена манипулация и дали избраният елемент наистина е един от предлаганите и не е бил деактивиран. Методът getRawValue() може да се използва за извличане на изпратен елемент без тази важна проверка.

При настройката по подразбиране се проверява дали това е един от предлаганите елементи, в противен случай се подава изключение. Тази проверка може да бъде деактивирана с помощта на checkDefaultValue(false).

addSelect(string|int $name, $label=null, array $items=null): SelectBox

Добавя поле за избор (клас SelectBox). Връща ключа на избрания елемент или null, ако потребителят не е избрал нищо. Методът getSelectedItem() връща стойност вместо ключ.

$countries = [
	'CZ' => 'Чешская республика',
	'SK' => 'Словакия',
	'GB' => 'Великобритания',
];

$form->addSelect('country', 'Страна:', $countries)
	->setDefaultValue('SK');

Предаваме масив от елементи като трети параметър или метод setItems(). Масивът от елементи може да бъде и двуизмерен:

$countries = [
	'Europe' => [
		'CZ' => 'Чешская республика',
		'SK' => 'Словакия',
		'GB' => 'Великобритания',
	],
	'CA' => 'Канада',
	'US' => 'США',
	'?'  => 'другая',
];

В блоковете за селекция първият елемент често има специално значение, той служи като призив за действие. Използвайте метода setPrompt(), за да добавите такъв запис.

$form->addSelect('country', 'Страна:', $countries)
	->setPrompt('Выберите страну');

Можете също така да използвате setDisabled(['CZ', 'SK']) за деактивиране на отделни елементи.

Елементът автоматично проверява дали не е извършена манипулация и дали избраният елемент наистина е един от предлаганите и не е бил деактивиран. Методът getRawValue() може да се използва за извличане на изпратен елемент без тази важна проверка.

При настройката по подразбиране се проверява дали това е един от предлаганите елементи, в противен случай се подава изключение. Тази проверка може да бъде деактивирана с помощта на checkDefaultValue(false).

addMultiSelect(string|int $name, $label=null, array $items=null): MultiSelectBox

Добавя поле за множествен избор (клас MultiSelectBox). Връща масив от ключове на избрани елементи. Методът getSelectedItems() връща стойности вместо ключове.

$form->addMultiSelect('countries', 'Страны:', $countries);

Предаваме масив от елементи като трети параметър или метод setItems(). Масивът от елементи може да бъде и двуизмерен.

Можете да използвате setDisabled(['CZ', 'SK']) за деактивиране на отделни елементи.

Елементът автоматично проверява дали не е извършена манипулация и дали избраните елементи наистина са едни от предлаганите и не са били деактивирани. Методът getRawValue() може да се използва за получаване на елементи, изпратени без тази важна проверка.

При задаване на стойности по подразбиране се проверява също дали те са един от предлаганите елементи, в противен случай се прави изключение. Тази проверка може да бъде деактивирана с помощта на checkDefaultValue(false).

addUpload(string|int $name, $label=null): UploadControl

Добавя поле за качване на файлове (клас UploadControl). Връща обект FileUpload, дори ако потребителят не е качил файл, което може да се установи с помощта на метода FileUpload::hasFile().

$form->addUpload('avatar', 'Аватар:')
	->addRule($form::Image, 'Аватар должен быть в формате JPEG, PNG, GIF или WebP')
	->addRule($form::MaxFileSize, 'Максимальный размер - 1 МБ', 1024 * 1024);

Ако файлът е качен неправилно, формулярът не е изпратен успешно и се показва грешка. Т.е. не е необходимо да се проверява методът FileUpload::isOk().

Не се доверявайте на оригиналното име на файла, върнато от метода FileUpload::getName(), тъй като клиентът може да изпрати злонамерено име на файла с цел да повреди или да отвлече приложението ви.

Правилата MimeType и Image определят желания тип файл или изображение по неговата сигнатура. Целостта на целия файл не се проверява. Можете да разберете дали дадено изображение е повредено, например като се опитате да го изтеглите.

addMultiUpload(string|int $name, $label=null): UploadControl

Добавя поле за качване на множество файлове (клас UploadControl). Връща масив от обекти FileUpload. Методът FileUpload::hasFile() ще върне true за всеки от тях.

$form->addMultiUpload('files', 'Файлы:')
	->addRule($form::MaxLength, 'Может быть загружено не более %d файлов', 10);

Ако един от файловете не е качен правилно, формулярът няма да бъде изпратен успешно и ще бъде показана грешка. Т.е. не е необходимо да се проверява методът FileUpload::isOk().

Не се доверявайте на оригиналните имена на файловете, върнати от метода FileUpload::getName(), тъй като клиентът може да изпрати злонамерено име на файл с намерението да повреди или отвлече вашето приложение.

Правилата MimeType и Image идентифицират желания тип файл или изображение чрез неговия подпис. Целостта на целия файл не се проверява. Можете да разберете дали дадено изображение е повредено, например като се опитате да го изтеглите.

addHidden(string|int $name, string $default=null): HiddenField

Добавя скрито поле (клас HiddenField).

$form->addHidden('userid');

Използвайте setNullable(), за да го модифицирате така, че да връща null вместо празен низ. Функцията addFilter() ви позволява да промените представената стойност.

addSubmit(string|int $name, $caption=null): SubmitButton

Добавя бутон за изпращане (клас SubmitButton).

$form->addSubmit('submit', 'Зарегистрироваться');

Във формуляра може да има повече от един бутон за изпращане:

$form->addSubmit('register', 'Зарегистрироваться');
$form->addSubmit('cancel', 'Отмена');

За да разберете коя от тях е била натисната, използвайте

if ($form['register']->isSubmittedBy()) {
  // ...
}

Ако не искате да валидирате формуляра при натискане на бутон за изпращане (например бутоните Cancel или Preview), можете да го забраните с функцията setValidationScope().

addButton(string|int $name, $caption)Button

Добавя бутон (клас Button) без функция за изпращане. Това е полезно за свързване на друга функционалност към идентификатора, например действие на JavaScript.

$form->addButton('raise', 'Поднять зарплату')
	->setHtmlAttribute('onclick', 'raiseSalary()');

addImageButton(string|int $name, string $src=null, string $alt=null): ImageButton

Добавя бутон за изпращане като изображение (клас ImageButton).

$form->addImageButton('submit', '/path/to/image');

Ако се използва повече от един бутон за изпращане, можете да разберете кой от тях е бил натиснат с $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Добавя подформа (клас Container) или контейнер, който може да се третира по същия начин като форма. Това означава, че можете да използвате методи като setDefaults() или getValues().

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Ваше имя:');
$sub1->addEmail('email', 'Имейл:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Ваше имя:');
$sub2->addEmail('email', 'Имейл:');

След това изпратените данни се връщат като многомерна структура:

[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]

Преглед на настройките

Можем да извикаме следните методи за всички елементи (за пълен преглед вижте документацията на API):

setDefaultValue($value) задаване на стойността по подразбиране
getValue() извличане на текущата стойност
setOmitted() пропуснати стойности
setDisabled() деактивиране на входовете

Рендъринг:

setCaption() промяна на заглавието на елемента
setTranslator() задайте преводач
setHtmlAttribute() задаване на атрибут на елемент HTML
setHtmlId() задаване на атрибут на HTML id
setHtmlType() задаване на атрибут на HTML type
setHtmlName() задаване на атрибут на HTML name
setOption() задава визуализиране на данни

Валидиране:

setRequired() задължително поле
addRule() задаване на правило за валидиране
addCondition(), addConditionOn() задаване на условие за валидиране
addError() предаване на съобщение за грешка

Следните методи могат да бъдат извикани за елементите addText(), addPassword(), addTextArea(), addEmail(), addInteger():

setNullable() задава дали функцията getValue() да връща null вместо празен низ
setEmptyValue() задава специална стойност, която се третира като празен низ
setMaxLength() задава максималния брой разрешени символи
addFilter() промяна на входните стойности

пропуснати стойности

Ако не се интересувате от стойността, въведена от потребителя, можем да използваме setOmitted(), за да я пропуснем в резултата, предоставен от метода $form->getValues() или предаден на обработващите програми. Това е подходящо за различни пароли за валидиране, полета за защита от спам и др.

$form->addPassword('passwordVerify', 'Повторите пароль:')
	->setRequired('Введите пароль ещё раз, чтобы проверить опечатку')
	->addRule($form::Equal, 'Несоответствие пароля', $form['password'])
	->setOmitted();

Деактивиране на входните елементи

За да деактивирате въвеждането, можете да се обадите на setDisabled(). Такова поле не може да се редактира от потребителя.

$form->addText('username', 'Имя пользователя:')
	->setDisabled();

Обърнете внимание, че браузърът изобщо не изпраща забранените полета към сървъра, така че те дори няма да бъдат открити в данните, върнати от функцията $form->getValues().

Ако задавате стойност по подразбиране за дадено поле, трябва да го направите само след като сте го деактивирали:

$form->addText('username', 'Имя пользователя:')
	->setDisabled()
	->setDefaultValue($userName);

Потребителски контроли

В допълнение към широкия набор от вградени контроли на формуляра можете да добавяте свои собствени контроли, както следва

$form->addComponent(new DateInput('Дата:'), 'date');
// алтернативен синтаксис: $form['date'] = new DateInput('date:');

Формата е потомък на класа Container, а елементите са потомци на Component.

Има начин да се дефинират нови методи на формуляра за добавяне на персонализирани елементи (например ‘$form->addZip()’). Това са така наречените методи за разширение. Недостатъкът е, че подсказките за код в редакторите няма да работят за тях.

use Nette\Forms\Container;

// метод 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, 'Не менее 5 номеров', '[0-9]{5}');
});

//използване
$form->addZip('zip', 'ZIP код:');

Ниски полета

Не е необходимо да извиквате ‘$form->addXyz()’, за да добавите елемент към формуляра. Вместо това елементите на формуляра могат да се въвеждат изключително в шаблони. Това е полезно, ако трябва да създавате динамични елементи, например:

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

Стойностите могат да бъдат изтеглени след подаването им:

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

В първия параметър посочвате типа на елемента (DataFile за type=file, DataLine за едноредови входове като text, password или email и DataText за останалите). Вторият параметър съответства на атрибута на HTML name. Ако искате да запазите ключовете, можете да комбинирате първия параметър с DataKeys. Това е полезно за select, radioList или checkboxList.

Функцията getHttpData() връща обработените данни. В този случай това винаги ще бъде масив от валидни низове UTF-8, независимо от това какво е изпратил атакуващият чрез формуляра. Това е алтернатива на директната обработка на $_POST или $_GET, ако искате да получавате сигурни данни.

версия: 4.0