Form class

The form class takes care of html form input, by both rendering forms and setting/receiving form input.

A form is rendered by first configuring the form object and then rendering it.

$form = new Form('form_id');
$form->addField(new FieldText('Type something', 'field_title'));
$form->addField(new FieldSubmit('Save form', 'save_form'));
$form->render();

This will render a form with a text input field labeled Type something and a submit button labeled Save form

Validation of the form and retrieval of form data, also requires that the form is setup and then validated. As it is important that the form is set up exactly the same way as the posted form, usually the same object is used, and as an example we can type everything in a single example:

$form = new Form('form_id');
$form->addField(new FieldText('Type something', 'field_title'));
$form->addField(new FieldSubmit('Save form', 'save_form'));
 
if ($form->isSubmitted()) {
  // The form was submitted.
  if ($form->validate()) {
    // Form input was validated.
    $values = $form->getValues();
    // $values now contain all form values.
    // Do something when form was posted with success.
  } else {
    // When the form didn't validate, it have already been prepared with proper error messages,
    // so we run-through down to displaying it again where it will also contain the entered values.
  }
} else {
  // Values can be pre-added to the form if desired
  $form->setValues(
    array(
      'field_title' => 'Pretyped value';
    )
  );
}
 
$form->render(); 

In order to provide an easier way to design forms, one can prepare a special html file

testform.form

<h2>Please fill this form</h2>
<text label="Type something" name="field_title">
<submit label="Save form" name="save_form">

This file can be used like

$form = new Form('form_id', 'testform.form');

which will actually provide the same form as above. As one can see the file consist of normal HTML, but with some special tags. These tags should match the last part of every Field*-class, so <text> match the FieldText class. The tag attribute label will become the field label and the attribute name will become the name of the field. Every other attribute will be passed as an option to the field, so required will match array('required' ⇒ true) and so on.

Never use real html form elements, such as <form>, <input> and <select> as this will confuse the Platform form system.

The form is rendered as a form with an ID equal to the form id given under construction, so

$form = new Form('testform');

gives

<form id="testform">

The form will validate itself from some basic rules such as having required fields filled in, and valid input according to field types, but sometimes extended validation is necessary. For frontend validation basic javascript can be used on the form, but in the backend one needs to add a validation function to the form.

function myValidationFunction($form) {
  if ($form->getFieldByName('fullname')->getValue() == 'Hitler') {
    $form->getFieldByName('fullname')->triggerError('This name is not allowed here');
    return false;
  }
}
 
$form->addValidationFunction('myValidationFunction');

The validation function is passed the form, and should return true if everything is OK, otherwise it should trigger an error on the appropriate form field and return false.

When doing a normal post, server side errors are automatic added to the form, but when posting using javascript, you need to pass server side errors back to the form. Platform provides easy functions to do that.

frontend.js

$.post('backend.php', form.serialize(), function(data) {
  if (data.status == 1) {
    // Everything is fine
  } else {
    // There was backend errors. Add them to the form.
    add_errors_to_form(form, data.errors);
  }
}, 'json');

backend.php

if ($form->validate()) $result = array('status' => 1);
else $result = array('status' => 0, 'errors' => $form->getAllErrors());
echo json_encode($result);