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

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

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

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

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

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

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

Можете да промените визуалния характер на текстово поле до типове като search, tel или url, като използвате setHtmlType(), както е показано в спецификацията. Не забравяйте, че промяната на типа е само визуална и не изпълнява функции за валидиране. За типа url е подходящо да добавите специфично правило за URL.

За други типове входни данни, като number, range, email, date, datetime-local, time и color, използвайте специализирани методи като addInteger, addFloat, addEmail addDate, addTime, addDateTime и addColor, които осигуряват валидиране от страна на сървъра. Типовете month и week все още не се поддържат напълно от всички браузъри.

Един елемент може да бъде зададен на така наречената “празна стойност”, която е нещо подобно на стойността по подразбиране, но ако потребителят не я презапише, тя връща празен низ или 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('year', 'Year:')
	->addRule($form::Range, 'The year must be in the range %d to %d.', [1900, 2023 |1900, 2023]);

Елементът се визуализира като <input type="numeric">. Като използвате метода setHtmlType(), можете да промените типа на range за показване като плъзгач или на text, ако предпочитате стандартно текстово поле без специалното поведение на numeric.

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, 'Нивото трябва да е в диапазона от %d до %d.', [0, 100 |0, 100]);

Nette и браузърът Chrome приемат както запетая, така и точка като десетични разделители. За да направите тази функционалност достъпна във Firefox, се препоръчва да зададете атрибута lang или за конкретния елемент, или за цялата страница, например, <html lang="cs">.

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

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

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

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

addPassword (string|int $name, $label=null, $cols, ?int $maxLength=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).

Ако изпращате формуляр чрез метода GET, можете да изберете по-компактен метод за прехвърляне на данни, който спестява от размера на низ от заявки. Това се активира чрез задаване на HTML атрибут на формуляра:

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

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, ?int $size=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']) за деактивиране на отделни елементи.

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

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

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

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

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

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 идентифицират желания тип файл или изображение чрез неговия подпис. Целостта на целия файл не се проверява. Можете да разберете дали дадено изображение е повредено, например като се опитате да го изтеглите.

addDate (string|int $name, $label=null): DateTimeControl

Добавя поле, което позволява на потребителя лесно да въвежда дата, състояща се от година, месец и ден (клас DateTimeControl).

За стойност по подразбиране приема или обекти, реализиращи DateTimeInterface, низ с време, или число, представляващо времеви печат на UNIX. Същото се отнася и за аргументите на правилата Min, Max или Range, които определят минималната и максималната допустима дата.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

По подразбиране програмата връща обект DateTimeImmutable. Използвайки метода setFormat(), можете да зададете текстов формат или времева марка:

$form->addDate('date', 'Date:')
	->setFormat('Y-m-d');

addTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Добавя поле, което позволява на потребителя лесно да въвежда време, състоящо се от часове, минути и по избор секунди (клас DateTimeControl).

За стойност по подразбиране то приема или обекти, реализиращи DateTimeInterface, низ с време, или число, представляващо UNIX времеви печат. Използва се само информацията за времето от тези входове; датата се игнорира. Същото се отнася и за аргументите на правилата Min, Max или Range, които определят минималното и максималното разрешено време. Ако зададената минимална стойност е по-висока от максималната, се създава времеви диапазон, обхващащ полунощ.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

По подразбиране той връща обект DateTimeImmutable (с дата 1 януари, година 1). Чрез метода setFormat() можете да зададете текстов формат:

$form->addTime('time', 'Time:')
	->setFormat('H:i');

addDateTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

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

За стойност по подразбиране то приема или обекти, реализиращи DateTimeInterface, низ с време, или число, представляващо UNIX timestamp. Същото се отнася и за аргументите на правилата Min, Max или Range, които определят минималната и максималната допустима дата.

$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'));

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor (string|int $name, $label=null): ColorPicker

Добавя поле за избор на цвят (клас ColorPicker). Цветът е низ във формат #rrggbb. Ако потребителят не направи избор, върнатият цвят по подразбиране е черен #000000.

$form->addColor('color', 'Color:')
	->setDefaultValue('#3C8ED7');

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(). Ако обаче зададете setOmitted(false), Nette ще включи стойността им по подразбиране в тези данни.

Когато се извика setDisabled(), стойността на входа се изтрива от съображения за сигурност. Ако задавате стойност по подразбиране, е необходимо да го направите след нейното деактивиране:

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

Алтернатива на забранените входове са полетата с атрибут HTML readonly, които се изпращат на сървъра от браузъра. Въпреки че полето е само за четене, важно е да се разбере, че стойността му все пак може да бъде променена или подправена от нападател.

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

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

$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, ако искате да получавате сигурни данни.