Form methods

This section contains all frequently used methods of objects of the Form class with explanations. The methods are divided into logical groups.

Managing form fields

• addField($field_data) - adding a field to the form, $field_data is an array of field parameters
• removeField($field) - removing a field from the form
• setHtmlParams($field, $html_params) - adding html parameters to the form field, $field can be an array of fields
• setCaption($field, $caption) - setting a caption for the form field
• setHelpText($field, $text) - setting a caption for the form field

Adding and removing validation rules

• setRequired($field) - make a field mandatory
• setRequiredFields($fields) - make all or some fields mandatory
• addRule($field, $rule, $value, [$message]) - add a rule to validate a form field
• removeRule($field, $rule) - remove a rule to validate a form field

Submitting and validating data

• setValue($field, $value) - set the value of a form field
• submit() - receive data from a POST request
• validate([$fields]) - check all or selected form fields for compliance with the rules
• addError($error [, $field]) - add an error to a form field or just to the general list of errors
• isSubmitted() - check for form submission using the POST method
• isValid() - check for at least one error in the form
• getState() - current state of the form as an array with parameters and validation errors
• getErrors() - returns an array with form errors, errors are presented as arrays with the following elements: 0 - text field name, 1 - error text, 2 - field name in the SQL table
• displayErrors() - output of all form errors as a common list

Displaying form fields

• display([$fields, $format]) - display all or selected form fields in the desired sequence, format available options: table, divs, inputs
• setDisplayWithErrors() - sets the option to display form errors next to form fields, fields with errors receive a special CSS class
• displayFieldHtml($field) - displays one form field, only input without a name

Getting data from the form

• getValue($field) - returns the value of one form field
• all([$fields]) - returns the values ​​of all or selected form fields as an array
• getEnumTitle($field) - returns the title (not the key) of the enum field if the value is set
• composeMessage([$fields]) - composes a message from all or selected filled form fields
• getMultipleFilesValue($field) - returns the value of the file field if this field can accept multiple files at a time, the multiple property

Special methods

• useTokenCSRF() - tells the form to use the CSFR token for validation
• displayTokenCSFR() - displays a hidden field with the CSRF token for validation
• filterValuesList($field, $params) - if the form is created from a model, it allows filtering the list of possible values ​​for emun and many_to_many fields, accepting parameters in the form described in the Query builder section.
• setEnumEmptyValueTitle($field, $title) - for enum type fields, it allows changing the text for an empty value
• loadRecord([$fields]) - if the form is created from a model and the record id is specified, it allows loading all or selected values ​​of the record fields into the form
• setDisplaySelects($field) - for date and date_time type fields, it specifies the ability to output as select tags
• setDisplayRadio($field) - for enum type fields, it allows output as radio buttons
• setDisplayTable($field, $columns) - for many_to_many and enum fields enables output in the form of a table with checkboxes, $columns is the number of columns in the table, which means the possibility of multiple selection
• setFieldProperty($field, $property, $value) - set the value of one of the form fields (properties are described in the section
• getFieldProperty($field, $property) - return the value of the property of one of the form fields

$fields = [
    ['Name', 'char', 'name', ['regexp' => '/w/', 'max_length' => 50]),
    ['About me', 'text', 'about', ['min_length' => 30]),
    ['Password', 'password', 'password'],
    ['Email', 'email', 'email'],
    ['Phone', 'phone', 'phone', ['format' => '/^d-d{3}-d{3}-d{4}$/']),
    ['Social network page', 'redirect', 'redirect'],
    ['Age', 'int', 'age'],
    ['I agree to receive the newsletter', 'bool', 'news']
];

$form = new Form($fields);
$form -> setRequiredFields(['name', 'age', 'email']);
$form -> addRule('name', 'min_length', 3, 'The name must contain at least 3 characters.');
$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');
}