====== Field* class ======

The Field* complex of classes are all different input fields to insert into a [[form class|Form]]. There are both simple fields and more complex fields.

===== Base class =====

The base class is named ''Field'' and provides the basis for other form fields. The constructor for a form field looks like:

<code php>
public function __construct($label, $name, $options = array());
</code>

where $label is the field label, $name is the field name and $options can be any of the following:

^autofocus|If set to true, then this field is automatically focused on page load.|
^class|Additional classnames to apply to the input field (as an array).|
^container-class|Additional classnames to apply to the general container of the form field (as an array).|
^container-style|Styles to add to the form field container div.|
^dont-clear|If this is set it instructs Platform **not** to clear the form value if the form is reset (using the Platform reset function)|
^heading|If the field requires a heading, this can be provided as a string.|
^label-alignment|Select how to align the label of the field. Can be: //auto//, //top//, //bottom//, //left//, //right// or //none//.|
^options|If the field requires different options, these can be provided as an array here.|
^required|If this is true, then the field is required and will show an error if it isn't filled.|
^value|Provides a value to the field.|

Other options proved are applied directly to the resulting html tag as a property-value pair, so ''array('data-test' => 23)'' becomes //<input ... data-test=23>//

===== HTML composition of form fields =====

The input field itself will typically directly take the name given to it as it name attribute, and generate an id which is a combination of the form id and the field name, to ensure an unique id across the page.

<code php>
$form = new Form('testform');
$form->addField(new Field('Label', 'testfield'));
</code>

will generate a html field like

<code html>
<form id="testform">
...
<input name="testfield" id="testform_testfield">
...
</form>
</code>

One or more helper div's are created around the input field. There is always an outer div containing the entire field structure. This outer div will have the same id as the input field, but with //_container// appended to the end.

Inside this div, there can be up to three divs with these class names.

^//platform_field_label_container//|A container to help aligning a label and the field itself.|
^//platform_field_input_container//|A container to help aligning the field and the error message container.|
^//platform_field_error_container//|A container for displaying a field error message.|

Their presence and individual placement can vary depending on label alignment. Example of complete field output:

<code html>
<form id="testform">
<div class="testform_testfield_container">
  <div class="platform_field_label_container">
    <label for="testform_testfield">Label:</label>
    <div class="platform_field_input_container">
      <input name="testfield" id="testform_testfield">
      <div class="platform_field_error_container">
      </div>
    </div>
  </div>
</div>
</form>
</code>

==== Width and sizes ====

The field (which is considered both the field and the label will obtain 100 % of the available width).

The field itself can be one of three sizes.

A normal size field will be 280 px wide.
A small size field will be 120 px wide.
A tiny size field will be 50 px wide.

This can be overwritten by the field-width parameter. If there isn't enough free space the field will scale down.

The label will always be 130 px wide and if the label exceeds that amount it will appear over several lines. This can be overwritten by the label-width parameter.
The label will always have a 0 px padding before the text and a 5 px padding after the text.
===== Form fields =====

Here we go over each form field.

==== FieldButton ====

Provides an input button field which doesn't return any input.

==== FieldCheckbox ====

This provides a checkbox field which will return 1 if the box is checked and 0 is it isn't checked.

==== FieldCombobox ====

This provides a combobox field which is a field that allow any value, but will suggest values as the user starts typing. This field uses Jquery autocomplete and takes an option named ''datasource'' which should be compatible with the ''source'' field of Jquery autocomplete.

==== FieldComponent ====

This field allows to add [[Component Class|Components]] as form fields. Please refer to [[FieldComponent Class]] for using this feature.
==== FieldDatarecordCombobox ====

This is a variation of the Combobox which suggest values from a [[datarecord_class|Datarecord class]] and also only validates if the typed value can be resolved to an object of the given class. It takes an option named ''class'' which should name the class to use.

The field returns the key field ID of the selected Datarecord.

==== FieldDate ====

This provides an interface for selecting a date.

==== FieldDatetime ====

This provides an interface for selecting a date and a time.

==== FieldFile ====

This provides an interface for selecting a file. An existing file can be displayed in the field, so the user can choose to keep it, delete it or change it to another file. Files are uploaded on-the-fly.

The File field is a little special to use, as the output differs from the input. As an input one should pass the ''file_id'' of a [[file_class|File object]] which will be the file displayed as the currently selected file. 

But when content is returned from the field, a more complex array is returned with the following keys:

^mimetype| The mimetype of the file.|
^status  | The status of the field. This can be: //changed// which means that new file data is available, //removed// which means that the user chose to remove the file, and an empty value which means that nothing is changed.|
^original_file| The original name of the file.|
^temp_file| The location of a temporary file with file data of the uploaded file (if status is //changed//).|

This array can be passed directly into a [[datarecord_class|Datarecord]] file field which will sort everything out automatic, but needs a little more work when used manually.

==== FieldHTML ====

This field is used to have generic HTML inside the form and have a special constructor which just takes the HTML to render in place of this field.

<code php>
$field = new FieldHTML('<b>This is just HTML to include inside my form');
</code>

One cannot set or read a value from this field.

==== FieldHidden ====

This corresponds to a normal hidden field.

==== FieldMulticheckbox ====

Options should be given to this field, and then each option will be displayed with a checkbox. The value of the option is the display value and the hash is the value included in the array if the checkbox is checked.

==== FieldMultidatarecordcombobox ====

This is exactly the same as the Datarecordcombobox except that it allows several inputs and therefore returns an array instead of a single key.

==== FieldMultiplier ====

The Multiplier is a field which allow one to add several fields to it and then it will render each of these fields. If one of these fields are filled, a new section will be spawned with another copy of the same fields, so it is used for form sections which needs to appear as many time as they are needed.

The field return an array with an element for each time a section was spawned, where each element is the value of the contained fields.

An example could be a form where a parent could register herself and each of her children, where the number of children isn't known from the beginning.

<code php>
$form = new Form('parent_form');
$form->addField(new FieldText('Parent name', 'parent_name'));
$multiplier = new FieldMultiplier('', 'children');
$multiplier->addFields(new FieldText('Child name', 'child_name'));
$multiplier->addFields(new FieldNumber('Child age', 'child_age'));
$form->addField($multiplier);

// Example of output
$result = array(
  'parent_name' => 'Michael Sahl',
  'children' => array(
    0 => array(
      'child_name' => 'Andy',
      'child_age' => 6
    ),
    1 => array(
      'child_name' => 'Berit',
      'child_age' => 14
    )
  )
);
</code>

When using the easy forms html-like files, multipliers are used like the following:

<code html>
<text label="Parent name" name="parent_name">
<multiplier name="children">
<text label="Child name" name="child_name">
<number label="Child age" name="child_age">
</multiplier>
</code>

Multiple multipliers can be nested.

==== FieldNumber ====

An input field which only accept numbers.

==== FieldPassword ====

A field which is used for passwords. Values passed to this field are never displayed in the html code and is only considered regarding if they are there or not. If there is a value, the field will display XXXXXX, and if there isn't a value, the field will be empty.

When extracting a value from the field, ''null'' will be returned if nothing was changed, so if a password is already set and ''null'' is returned, the password should be preserved. Any other value returned from this field corresponds to what the user actually typed.

This behavior is directly compatible with the Datarecord object and values can be passed into a Datarecord password field.

==== FieldSelect ====

This renders a html select and should be provided options where the values are the display values and the hashed the values returned by the field.

==== FieldSubmit ====

This renders a submit button, which will post the form if pressed.

==== FieldText ====

This renders a text field.

==== FieldTextarea ====

This renders a multi-line textarea.

===== Creating your own form field =====

To create your own form field, you need to extend the ''Platform\Field'' object.

==== Rendering input ====

Overwrite the ''renderInput()'' function with code to render your input field. This input field should expose the field ID, field classes, name, value and additional attributes from the Field class. For an example of this, it is best to observe the ''FieldText'' class:

<code php>
public function renderInput() {
    echo '<input class="'.$this->getClassString().'" type="text" name="'.$this->name.'" id="'.$this->getFieldIdForHTML().'" value="'.htmlentities($this->value, ENT_QUOTES).'"'.$this->additional_attributes.'>';
}
</code>

==== Validating input ====

Overwrite the ''parse($value)'' function to parse and validate your input. The ''$value'' variable will be the $_POST input related to your field, so if your field is named ''test'' you will receive the content of ''$_POST['test']''.

This function should accomplish two things. First it should validate if the input is valid for the field. If the input is valid the function should return true. If the input isn't valid, an error should be raised by the field, which could be done like:

<code php>
$this->triggerError('There is an error in the input field');
</code>

...and the function should return false.

Furthermore the value intended as the real output from the form should be saved in the ''$this->value'' variable. For simple fields this could just be a copy of ''$value'' but for more sofisticated fields, this value maybe needs postprocessing.

==== Using script ====

If the field requires javascript, this can be included using ''Page::JSfile($file)''. It should be wrapped in the ''addCustomPlatformFunction'' such as:

<code javascript customcomponent.js>
addCustomPlatformFunction(function(item) {
  $('.mycomponent', item).dosomething...
}
</code>
==== Other services of the Field class ====

The field class takes care of handling the label of the field.

You can get your field to work with the easy html form files, by naming your class Field* and adding the namespace of your class to the Form class, by using the ''addFormFieldNameSpace()'' function.

So if you do this:

<code php>
namespace MyNameSpace;

class FieldCustomField {
  ...
}

$form = new Form(...);
$form->addFormFieldNameSpace('MyNameSpace');

</code>

...you can create a form html field like:

<code html test.form>
<h1>My form</h1>
<customfield name="myfieldname" label="Mylabel">
</code>

==== Best practices ====

If you need to modify base field parameters such as adding a new class to the field, do this in the constructor with the proper functions instead of doing it in the ''renderInput()'' function.