Field* class

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

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

public function __construct($label, $name, $options = array());

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

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>

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.

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

will generate a html field like

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

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.

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

<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>

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.

Here we go over each form field.

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

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

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.

This field allows to add Components as form fields. Please refer to FieldComponent Class for using this feature.

This is a variation of the Combobox which suggest values from a 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.

This provides an interface for selecting a date.

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

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 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:

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

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.

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

One cannot set or read a value from this field.

This corresponds to a normal hidden field.

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.

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

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.

$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
    )
  )
);

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

<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>

Multiple multipliers can be nested.

An input field which only accept numbers.

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.

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.

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

This renders a text field.

This renders a multi-line textarea.

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

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:

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.'>';
}

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:

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

…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.

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

customcomponent.js

addCustomPlatformFunction(function(item) {
  $('.mycomponent', item).dosomething...
}

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:

namespace MyNameSpace;
 
class FieldCustomField {
  ...
}
 
$form = new Form(...);
$form->addFormFieldNameSpace('MyNameSpace');

…you can create a form html field like:

test.form

<h1>My form</h1>
<customfield name="myfieldname" label="Mylabel">

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.