Методы форм

В данном разделе собраны все часто используемые методы объектов класса Form с пояснениями. Методы разбиты на логические группы.

Управление полями формы

• addField($field_data)- добавление поля в форму, $field_data - массив параметров поля
• removeField($field)- удаление поля из формы
• setHtmlParams($field, $html_params) - добавление html параметров к полю формы, $field может быть массивом полей
• setCaption($field, $caption) - задание подписи к полю формы
• setHelpText($field, $text) - задание подписи к полю формы

Добавление и удаление правил валидации

• setRequired($field) - сделать поле обязательным для заполнения
• setRequiredFields($fields) - сделать все или несколько полей обязательными для заполнения
• addRule($field, $rule, $value, [$message]) - добавить правило для проверки поля формы
• removeRule($field, $rule) - удалить правило проверки поля формы

Принятие и проверка данных

• setValue($field, $value) - установить значение поля формы
• submit() - получение данных из POST запроса
• validate([$fields]) - проверить все или выборочные поля формы на соответствие правилам
• addError($error [, $field]) - добавить ошибку к полю формы либо просто в общий список ошибок
• isSubmitted() - проверка на отправку формы методом POST
• isValid() - проверка на наличие в форме хотя бы одной ошибки
• getState() - текущее состояние формы в виде массива с параметрами и ошибками валидации
• getErrors() - возвращает массив с ошибками формы, ошибки представлены в виде массивов с элементами: 0 - текстовое название поля, 1 - текст ошибки, 2 - название поля в SQL таблице
• displayErrors() - вывод всех ошибок формы общим списком

Отображение полей формы

• display([$fields, $format]) - вывести все или выборочные поля формы в нужной последовательности
• setDisplayWithErrors() - устанавливает опцию для вывода ошибок формы рядом с полями формы, поля с ошибками получают специальный css класс
• displayFieldHtml($field) - выводит одно поле формы, только input без названия

Получение данных из формы

• getValue($field) - возвращает значение одного поля формы
• all([$fields]) - возвращает значения всех или выборочных полей формы в виде массива
• getEnumTitle($field) - возвращает заголовок (не ключ) поля типа enum, если значение задано
• composeMessage([$fields]) - составляет сообщение из всех или выборочных заполненных полей формы
• getMultipleFilesValue($field) - возвращает значение поля типа file в случае если данное поле может принимать несколько файлов за раз, свойство multiple

Специальные методы

• useTokenCSRF() - говорит форме использовать CSFR токен при валидации
• displayTokenCSFR() - выводит скрытое поле с CSRF токеном для валидации
• filterValuesList($field, $params) - если форма создана из модели, дает возможность фильтрации списка возможных значений для полей типа emun и many_to_many, принимая параметры в виде, описанном в разделе Конструктор запросов.
• setEnumEmptyValueTitle($field, $title) - для полей типа enum дает возможность сменить текст для пустого значения
• loadRecord([$fields]) - если форма создана из модели и указан id записи, дает возможность загрузить в форму все или выборочные значения полей записи
• setDisplaySelects($field) - для полей типа date и date_time, задает возможность вывода в виде тэгов select
• setDisplayRadio($field) - для полей типа enum дает возможность вывода в виде radio кнопок
• setDisplayTable($field, $columns) - для полей типа many_to_many и enum дает возможность вывода в виде таблицы с чекбоксами, $columns - количество колонок в таблице, что означает возможность множественного выбора
• setFieldProperty($field, $property, $value) - задать значение одного из полей формы (свойства описаны в разделе
• getFieldProperty($field, $property) - вернуть значение свойства одного из полей формы

$fields = [ 
    ['Имя', 'char', 'name', ['regexp' => '/w/', 'max_length' => 50]), 
    ['О себе', 'text', 'about', ['min_length' => 30]), 
    ['Пароль', 'password', 'password'], 
    ['Email', 'email', 'email'], 
    ['Телефон', 'phone', 'phone', ['format' => '/^d-d{3}-d{3}-d{4}$/']), 
    ['Страница в соц сети', 'redirect', 'redirect'], 
    ['Возраст', 'int', 'age'], 
    ['Согласен получать рассылку', 'bool', 'news'] 
];

$form = new Form($fields); 
$form -> setRequiredFields(['name', 'age', 'email']);
$form -> addRule('name', 'min_length', 3, 'Имя должно содержать не менее 3 символов.');
$form -> removeRule('phone', 'format');
$form -> useTokenCSRF();

$form -> submit() -> validate();

if($form -> isSubmitted() && $form -> isValid())
{
    if($form -> getValue('news') && $form -> getValue('email'))
       Email::send( ... ); 

    $mv -> reload('?sent');
}