Form methods

In this section all often used methods of "Form" objects are collected with explanations. Methods are divided into logical groups.

Management of form fields

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

Adding and deleting rules

  • setRequired($field) - to make a field mandatory
  • setRequiredFields($fields) - to make all or some fields mandatory
  • addRule($field, $rule, $value[, $message]) - to add the rule for the form field validation
  • removeRule($field, $rule) - to delete the rule of form field validation

Accept and verify data

  • getDataFromArray($source) - to load data from an array into form object
  • getDataFromPost() - to load data from $_POST array into form object
  • setValue($field, $value) - specify the field value of the form
  • validate([$fields]) - validate all or selected fields to match rules
  • addError($error [, $field]) - to add an error to a form field
  • isValid() - checks if the form has at least one error
  • getErrors() - returns an array with errors of the form, errors are presented as arrays with elements: 0 - the text name (title) of a field, 1 - the text of an error, 2 - the name of a field in SQL table
  • displayErrors() - display all errors of the form as a general list

Display the fields

  • display([$fields]) - display all or selected fields of the form in the required sequence as a table (the names on the left, the fields on the right)
  • displayVertical([$fields]) - display all or selected fields of the form as DIV tags (the name is located above the field)
  • setDisplayWithErrors() - sets an option to display form errors near the form fields (fields with errors get a special css class)
  • displayFieldHtml($field) - display one field of the form (only "input" without a name or wrappers)

Retrieving data from a form

  • getValue($field) - returns a value of one form field
  • getAllValues([$fields]) - returns values of all or selected fields of the form as an array
  • getEnumTitle($field) - returns a value (not a key) of an "enum" field (if value is specified)
  • composeMessage([$fields]) - assembles a message from all or selected filled fields of the form

Special methods

  • filterValuesList($field, $params) - if the form is created from a model, gives an option of filtering the list of possible values for "enum" and "many_to_many" fields, accepting parameters in the way as described in Query constructor section
  • setEnumEmptyValueTitle($field, $title) - for "enum" fields gives an option to change the text for an empty value
  • loadRecord([$fields]) - if the form is created from a model and the record id is specified, gives an option to load into the form all or selected values of the record
  • setDisplaySelects($field) - for "date" and "date_time" fields, gives an option to display as select tags
  • setDisplayRadio($field) - for enum type fields gives an option to display as radio buttons
  • setDisplayTable($field, $columns) - for "many_to_many" and "enum" type fields gives an option to display as a table with checkboxes, $columns – a number of columns in a table, that means there is an option for multiple choice
  • setFieldProperty($field, $property, $value) - set the value of one of the form fields (the properties are described in datatypes sections)
  • getFieldProperty($field, $property) - return a property value of one of the form fields

Sample

<? 
$fields = array( 
    array("Name", "char", "name", array("regexp" => "/w/", "max_length" => 50)),
    array("About", "text", "about", array("min_length" => 30)),
    array("Password", "password", "password"),
    array("Email", "email", "email"),
    array("Phone", "phone", "phone", array("format" => "/^d-d{3}-d{3}-d{4}$/")),
    array("Social media page", "redirect", "redirect"),
    array("Age", "int", "age"),
    array("Agree to receive newsletters ", "bool", "news")
);

$form = new Form($fields);
$form -> setRequiredFields(array("name", "age", "email"));
$form -> addRule("name", "min_length", 3, "Name should contain at least 3 symbols.");
$form -> removeRule("phone", "format");

if(!empty($_POST))
{ 
    $form -> getDataFromPost() -> validate();

    if($form -> isValid())
    { 
        $message = $form -> composeMessage();
 
        if($form -> news && $form -> email) 
            Email :: send( ... );
    }
}
?>

<form action="" method="post">
    <? echo $form -> setDisplayWithErrors() -> displayVertical(); ?>
    <p><input type="submit" value="Send" /></p>
</form>