====== Form class ======

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

===== Form rendering =====

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

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

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

===== Obtaining form data =====

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:

<code php>
$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(); 
</code>

===== Easy forms =====

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

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

This file can be used like

<code php>
$form = new Form('form_id', 'testform.form');
</code>

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 HTML form element =====
The form is rendered as a form with an ID equal to the form id given under construction, so

<code php>
$form = new Form('testform');
</code>

gives

<code html>
<form id="testform">
</code>

===== Additional validation =====
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.

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

$form->addValidationFunction('myValidationFunction');
</code>

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.

===== Handling server side errors, when posting with javascript =====

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.

<code javascript 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');
</code>

<code php backend.php>
if ($form->validate()) $result = array('status' => 1);
else $result = array('status' => 0, 'errors' => $form->getAllErrors());
echo json_encode($result);
</code>