Platform-Wiki

User Tools

Site Tools

Trace: • component_class
field_class

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
field_class [2019/10/24 20:25] – created sahlfield_class [2022/05/23 10:41] (current) – [HTML composition of form fields] sahl
Line 1: Line 1:
 ====== Field* class ====== ====== Field* class ======
  
-The Field* complex of classes are all different input fields to insert into a [[class_form|Form]]. There are both simple fields and more complex fields.+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 ===== ===== Base class =====
Line 11: Line 11:
 </code> </code>
  
-where $label is the field label, $name is the field name and options can be one of the following:+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).| ^class|Additional classnames to apply to the input field (as an array).|
-^containerclass|Additional classnames to apply to the general container of the form 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.| ^heading|If the field requires a heading, this can be provided as a string.|
-^options|If the field requires different options, these can be provided as an array.| +^label-alignment|Select how to align the label of the field. Can be: //auto//, //top//, //bottom//, //left//, //right// or //none//.| 
-^required|If this is true, then the form is required.|+^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.| ^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>// 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 properties =====+===== HTML composition of form fields =====
  
-The resulting HTML tags will typically get a name attribute corresponding to the name given in the constructor and an id of the form id + _ + the name. So+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> <code php>
Line 35: Line 39:
 <code html> <code html>
 <form id="testform"> <form id="testform">
 +...
 <input name="testfield" id="testform_testfield"> <input name="testfield" id="testform_testfield">
 +...
 </form> </form>
 </code> </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 ===== ===== Form fields =====
  
 Here we go over each form field. Here we go over each form field.
 +
 +==== FieldButton ====
 +
 +Provides an input button field which doesn't return any input.
  
 ==== FieldCheckbox ==== ==== FieldCheckbox ====
Line 51: Line 100:
 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 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 ==== ==== FieldDatarecordCombobox ====
  
-This is a variation of the Combobox which suggest values from a [[class_datarecord|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.+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. The field returns the key field ID of the selected Datarecord.
Line 69: Line 121:
 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. 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. To set a value in the field, one should pass the ''file_id'' of a [[class_file|File object]] which will be the file displayed.+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. 
  
-When getting the value from the field (after the form is posted) ...TODO....+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 ==== ==== FieldHTML ====
Line 97: Line 156:
 ==== FieldMultiplier ==== ==== 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 the same fields, so it is used for form sections which needs to appear as many time as they are needed.+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. 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.
Line 137: Line 196:
 </code> </code>
  
-Multiple multipliers can be nested (which is very cool).+Multiple multipliers can be nested.
  
 ==== FieldNumber ==== ==== FieldNumber ====
Line 145: Line 204:
 ==== FieldPassword ==== ==== FieldPassword ====
  
-A field which is used for passwords. Values passed to this field is never displayed 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.+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. 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 ==== ==== FieldSelect ====
Line 164: Line 225:
  
 This renders a multi-line textarea. 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.
field_class.1571948752.txt.gz · Last modified: 2019/10/24 20:25 by sahl
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki