Forms

Rack provides a set of classes enable form handling and rendering in include/form.php. This page discusses the public form API.

The core of Rack's form system is the <php>Form</php> class. All interactions with a form and it's fields should happen through this class, or one of its subclasses.

The constructor of the form class takes two arguments, the form's name (which is an id-like string) and a lists of fields. The latter may be left out, as fields can be added through the <php>add_field($field_name, $field)</php> and <php>add_fields($fields)</php> functions.

If the form has been submitted, the fields will automatically be filled with the submitted data once they're added to the form. If needed, this process can be manually executed by calling the function <php>initizize()</php> on the form object.

Sometimes, it may be desirable to populate the fields with default data. This can be done through the <php> populate_field($field_name, $values)</php> and <php>populate_fields($values)</php> functions, which set the values of the fields without overwriting submitted data.

Forms can be validated through their <php>validate()</php> function, which will return <php>true</php> if the form has been submitted and all fields have valid input and will return <php>false</php> otherwise.

When custom validation is needed, this should generally be done by subclassing the <php>Form</php> class and overriding its <php>validate()</php> function. In some specific cases, it may be more desirable to subclass a single <php>Field</php> class and override its <php>validate()</php> function instead.

There are tree main rendering strategies supported. Automatic rendering, semi-automatic rendering and manual rendering. Automatic rendering can be done calling the function <php>render($action=null, array $attributes=[])</php>, which allows for customizing the arguments of the <form> tag.

Semi-automatic rendering can be done by manually calling the function <php>render_field($key, array $attributes=[], array $error_attributes=[], array $parent_attributes=[])</php> for every field of the form. This renders the form according to the following template

<PHP>

 <label></label>
 <field $attributes> 
 <span $error_attributes></span> // for each error

</PHP>

Manual rendering can be achieved by iterating over the form's fields and calling the field's <php>render(array $attributes=[])</php> and <php>render_label()</php> functions. The field's errors should then also be rendered manually.

(Semi) Automatic can be customized by subclassing the <php>Form</php> class and overriding its render functions. Rack already provides a class to render forms compatible with Bootstrap 3, called <php>Bootstrap3Form</php>.

The <php>Form</php> class exposes the following public functions:

• <php>construct($name, array $fields=[])</php> * <php>initialize()</php> * <php>is_submitted()</php> * <php>validate()</php> * <php>render(array $attributes=[], $action=null)</php> * <php>render_field($key, array $attributes=[], array $error_attributes=[], array $parent_attributes=[])</php> * <php>add_field($field_name, $field)</php> and <php>add_fields($fields)</php> * <php>delete_field($field_name)</php> * <php>get_field($field_name)</php> and <php>get_fields()</php> * <php>get_name()</php> * <php>get_value($field_name)</php> and <php>get_values()</php> * <php>set_value($field_name, $value)</php> and <php>set_values($values)</php> * <php>populate_field($field_name, $values)</php> and <php>populate_fields($values)</php> ===== Fields ===== ==== Field class ==== The <php>Field</php> class provides the base implementation for all fields supported by Rack. Its constructor has the following signature <php>construct($label, $optional=false, array $attributes=[], $name=, $form=null)</php>. It should be noted that fields are required by default and the attributes used for rendering the HTML tag of the field (e.g. <input>) can be provided on intialization. In the default validation strategy, validation fails (returns <php>false</php>) if… - …the field is not optional and empty (a string only containing whitespace counts as empty) - …the maxlength HTML5 attribute is set and the value is a string that is longer than the defined maxlength - …the minlength HTML5 attribute is set and the value is a string that is shorter than the defined minlength In all other cases, validation succeeds (returns <php>true</php>). Field subclasses may extend or override this strategy. It should be noted that required fields will render the HTML5 required attribute. ==== Supported fields ==== === InputField === A general implementation of the HTML <input> element.he constructor has the custom signature <php>construct($type, $label, $optional=false, array $attributes=[], $name=, $form=null)</php>, where <php>$type</php> corresponds to the HTML type attribute. <php>InputField</php> does not implement custom validation. === TextAreaField === An implementation of the HTML <textarea> element. <php>TextAreaField</php> does not implement a custom constructor or custom validation. === SelectField === An implementation of the HTML <select> element. The constructor has the custom signature <php>__construct($label, $options, $optional=false, array $attributes=[], $name=, $form=null))</php>, where <php>$options</php> is an array containing all options of the field. The following snippet demonstrates the accepted formats for the <php>$options</php> array. <PHP> $options = [ 1) Single value: <option>Option Name</option> 'Option Name', 2) Value mapped to display name: <option value=“option_value”>Option Name</option> 'option_value' ⇒ 'Option Name', 3) Single value, with attributes: <option class=“class_name” disabled>Option Name</option> ['Option Name', ['disabled', 'class' ⇒ 'class_name']], 4) Value mapped to display name with attributes: <option value=“option_value” class=“class_name” disabled>Option Name</option> 'option_value' ⇒ ['Option Name', ['disabled', 'class' ⇒ 'class_name']], ]; </PHP> <php>SelectFields</php> does implement custom validation, which fails if… * …the field is not optional and no value has been submitted * …the selected value is not disabled Validation succeeds in all other cases. Please do note that due to PHP limitations, it is impossible to render options with integer keys (array keys) or options with string keys that contain integer values (e.g. <php>“8”</php> or <php>“22”</php>).