K8 Forms

K8 Forms allows you with HTML snippets and a Json datastructure to create bootstrap 5 input forms.

Features:

K8 Web Kit generates from a table a k8 form structure automatically.
You can add attributes and own data-attributes as you like it.
Containers, like <div> or <fieldset> can be nested and consist own field arrays.
Individual HTML snippets can be added and used in the fieldwraptemplates
Fields in nested containers are automaically listed in a "formcollection"
Formatting numbers with decimal places:
gFormatinputfordisplay(element,value)
Even with a "step" tag the decimal numbers are not formatted well, so the formatting function is called on change

Examples

Example

Please, choose the example first. Then change then the structure and "Create form" to see the result:

Resulted Form

Template types

templatetypes:

blank (default)
save_cancel
form
form_save_cancel
masterform
filterform

The templatetype is like a wrapper for the form elements. It can be a "blank" (empty) or include the form tag, button tags and more.

With the propertry:

template

you can define your own html template. For more informations to the templates look to the template chapter.

Form layouts

The following bootstrap form layouts are supported, formlayout:

vertical
horizontal (default)
floating (not all input types are floating)

Using k8form

Show in div

The 'k8' library to create the form is located in 'masterdata/js/masterdata.js'.

By displaying the form in a 'div' element a templatetype with a form tag is necessary. If a selector is defined, in this case '#myform', the form is directly displayed in the element.

Display in form

The selector is defined, in this case '#myform', the form is directly displayed in the element. The default templatetype is "blank", so it is not necessary to define it here.

If you want to genrate only the HTML of the form, ignore the selector and and log k8form.createform to the console. It gives back the HTML:

console.log(k8form.createform(obj));

With init first

With the function k8form.initFormfields(options) a collection of the fields 'formcollection' is build up:

formcollection['name/identifier']

In the formcollection each field is listed as a pointer to its origin. This allows you to change the field properties easily.

With the formcollection you get a link to the fields, independent where the fields are located in the object sturcture. So you can dynamically add options or change parameters by different users.

More Examples

Overlay Form

Like this you create a small dialog with 2 fields and buttons:

ov_form

ov_form is your object to define the form. The templatetype 'form' with 2 input fields and an submit button is declared:

o_supplierID
o_doctypeID
OK

The overlay offers the class 'k8-overlay_content' to insert the content. This is the selector for our form.

k8form

With the k8form library the following functions are executed:

create the overlay: k8form.createOverlay({})
create the form: k8form.createform(ov_form)

el_form

The event listener is added and the form fields are returned in the object obj:

o_supplierID
o_doctypeID

Write your own code here.

k8form object structure

k8.createform(options):

templatetype

The templatetype is like a wrapper for the form elements. It can be a "blank" (empty) or include the form tag, button tags and more.

template

You can define your own html template. For more informations to the templates look to the template chapter.

formlayout

The supported formlayouts are: vertical, horizontal, floating.

selector

Set the selector to append the form to your tag.

form

Write your form attributes here.

method: GET

The value of the form elements is automatically filled with the parameters of the query string.

fields[]

This is an array of fields (form.elements) which are build.

containers[]

This is an array of containers, div or fieldset, which allows you to use all needed HTML structures.

translation

When it set to 'true' the function getl() is used to translate labels and placeholders.

id_preset

The id is automatically set equal to the name. To enforce a unique 'id' a preset can be set to the name.

templates and classes

For each form layout different classes and templates are used. By setting your own templates and classes you overwrite the defaults.

html

All HTML snippets from the section: html.masterdata can be used as fieldwraptemplate:

"fieldwraptemplate":"{{myfieldwraptemplate}}"

containers:

This is an example for a form with 2 blocks:

Containers have a template. It can be a div or a fieldset. With the placeholder {{innerHTML}} the content will be added. Containers can be nested. By using the bootstrap classes "row" and "col-sm-x" a multi column layout can be created. The fields for this container is defined by the "fields" array.

template

The default template is only a placeholder: {{innerHTML}}.Here you can define you own HTML template.

fields[]

Each container has a fields array. For more information look to the fields chapter beneath.

containers[]

Containers can be nested. To create a form with 2 blocks you nest the structure like this:

div class="row"
- div class="col-sm-6"
- div class="col-sm-6"

classes and templates

The defined classes and templates are only valid in this container:

fieldwraptempate
labelclass
fieldwrapclass

fields:

{
  "fields": [
    {
      /* process control properties */
      "identifier":"(optional) helpful with enabledArray"},
      "active":"(optional, default: true)",
      "figure":"(optional default:1=1 field,2=2fields: from/to)",
      "label":"(optional) My Input",
      "tagName":"(default) input",
      "inputgroup":{"look":"beneath"},
      "fieldclass":"(optional) form-control",
      "fieldclass_add":"(optional)",
      "labelclass":"(optional) form-label",
      "decimals (optional)":2,
      "fieldtemplate (optional)":"(optional) <input{{input_attributes}}>",
      "input_attributes (optional)":"autocomplete=\"OFF\"",

/* attributes */
      "name":"myinput",
      "id":"(optional) myinput",
      "type":"(default) string"
      "maxlength (optional)":50,
      "placeholder (optional)":"myfield",
      "options (optional)":[{"(for select and radio) look":"options section"}],
      "required (optional)":true,
      "readonly (optional)":true,
      "disabled (optional)":true,

/* more attributes in the attributes area */
      "attributes":{
        "step":"(optional) 0.1",
        "data-mytag":"this is my example",
        ...
      }
    }
  ]
}

Own HTML Code can be placed in:

fieldwraptemplate
fieldtemplate

Declaration of a placeholder in fieldwraptemplate:

The HTML File has to be placed in the folder with the datadefinition, naming like this:

<datadefinition>_k8form_<placeholder_name>.html

identifier

Normally the most important property of the form elements is the name. The identifier allows you to prepare different inputs for the same field. Example: normally the field userID is a hidden field (identifier: userID_hidden). When the admin is logged in you want to allow him to change the userID. So you create the userID as datalist with the identifier "userID_datalist". Depending on the logged in user, you can activate or deactivate the fields.

active

The field can be set to: true / false. Only active fields are displayed in the form.

figure

The default is 1. In filter forms it can be set to 2. So 2 fields: from/to are displayed.

label

If the label is not set, it will be automatically set to 'name'. If the translation is activated, it will be translated according to the translation file.

tagName

Default is "input". tagNames with special behavior are:

input (default)
select
textarea
button
all others are allowed to implement HTML elements

inputgroup

The inputgroup allow several input fields and html elements in one line. Please have a look to the inputgroup chapter.

options

By select and type=radio the options need to be filled out. Please look to the options chapter.

fieldclass

The fieldclass overwrites the class of the field.

fieldclass_add

fieldclass_add is added to the class of the field.

labelclass

The labelclass overwrites the class of the label.

decimals

A step attribute is added to the field.

fieldtemplate

An own fieldtemplate replaces the standard fieldtemplate.

input_attributes

Attributes can additionally added as string to 'input_attributes'.

attributes{}

All attributes of this data structure are added to the tag.

name

This is the most important attribute and the only one which is required.

The id is automatically added and is set equal to the name.

type

The following input types have a special behavior:

hidden
number
checkbox
radio

All other types can be used with standard functionality:

text
date
time
datetime-local
...

maxlength

maxlength limits the allowed caracters to the specified number.

placeholder

The placeholder attribute is added. A translation is supported, if activated.

required

true / false

readonly

true / false

disabled

true / false

inputgroup:

Example of an simple bootstrap inputgroup:

More about inputgroups by Bootstrap inputgroups.

Input groups with 2 elements are still easy; with several elements they are more and more complicated. To handle them in k8forms choose one of the following solutions:

fieldwraptemplate includes the fulll html
fieldwraptemplate={{myfile}}, loaded by k8WebKit
structure in JavaScript

options:

All properties are appended as attribute.

The options array is used for the 'select' fields and also for the radio buttons.

The shortcut for an easy list of elements is this:

Templates

Template types (templatetype)

An individual template can be defined (template) or one of the following templatetypes can be choosen:

blank

form

form_save_cancel

masterform

filterform

Template structure

template
- fieldwraptemplate
  - labeltemplate
  - fieldtemplate
- fieldwraptemplate (with inputgroup)
  - labeltemplate
  - inputgroup.template
    - fieldtemplate
- fieldwraptemplate_radio
  - labeltemplate_radio
  - fieldradiotemplates[]
    - fieldtemplate
    - texttemplate
- fieldwraptemplate_checkbox
  - labeltemplate
  - fieldtemplate
- fieldwraptemplate_button
  - inputgroup.template
    - fieldtemplate

For each of the formlayouts (vertical, horizontal and floating are different templates defined.

containers template

fieldwraptemplate horizontal form

labeltemplate

fieldtemplate

fieldwraptemplate_radio horizontal

fieldtemplate_radio

fieldwraptemplate_button

K8 Web Kit HTML import

In K8 Web Kit the k8form definition is defined in the datadefinition. The HTML conent of this files in the folder are automatically added to the datadefintion (_datadefinitions.php). Here are the naming specification:

Filename: <datadefID>_k8form_<placeholder>
Datadefinition: k8form.html.<placeholder>

The placeholder in the datadefinition:
template:{{placeholder}}

Filename: <datadefID>_masterdata_<object>_container
Datadefinition: k8form.html. <object>_container

The placeholder in the datadefinition:
template:{{<object>_container}}

Supported properties:

fieldwraptemplate
fieldtemplate
inputgroup.template

Datalist

Datadefinition for the search

The datadefinition for the search is in this example: "k8components". To use it for a datalist search, the property "datalistcolumn" needs to be set:

datalistcolumn: text1

Attention: the text 1 column should be unique, other wise it is not possible to choose the right record!

Datadefinition for the form

In the form 2 elements are defined:

componentID, hidden
text1, the datalist field

The <input> for the datalist needs to have the attribute "list".

JavaScript

By each key press an Ajax request is executed, giving back the matching records. The datalist input is initialized like this:

var settingsk8components={"datadefinition":"of items"};
var data_components=[];
var settingscomponents.datalistcolumn="search";
var datalistfield="text1";
var el_datalistfield=el_form.elements.namedItem(datalistfield);
var myk8=Object.create(k8);

let el_datalist=document.createElement("datalist");

if(!gbnull(settingsk8components.masterdata.url_readfilter)){
  el_datalistfield.addEventListener("input",function(e){
    var el=e.target;
    settingsk8components.masterdata.data_readfilter.clause=settingscomponents.datalistcolumn+" like '%"+el.value+"%'";
    settingsk8components.masterdata.data_readfilter.clause=gsclauseand(settingsk8components.masterdata.data_readfilter.clause,"addressID="+el_addressID.value,!gbnull(el_addressID.value));
    $.getJSON(settingsk8components.masterdata.url_readfilter,settingsaddressemployees.masterdata.data_readfilter,function(oJson) {
      data_components=oJson;
      myk8.fillDatalist({"el_datalist":el_datalist,"data":data_components,"field":settingscomponents.datalistcolumn});
    })
    .fail(function(jqxhr, textStatus, error ) {
        var err = textStatus + ", " + error;
        console.log("saverecord.Request Failed: " + err );
    });
  });
}

The response of the Ajax request is inserted in the datalist.

After changing the "input" the corresponding "id" is set:

Datalist and masterdata

The master data plugin allows you to declare a datalist field which is filled by a foreign table (datadefinition). This example is taken from the invoice example. A customer is inserted into the invoice:

The field 'partnerdisp' is a datalist field with a link to the datadefinition 'customer'. After change the key of the table 'customer_er' is inserted into the field 'accountID' and the fields of data-fieldlist are inserted too.

Requirement

In the datadefinition for the search the 'datalistcolumn' is declared.
In this datadefinition the datadefinition for the search is added in 'settingsaddintioanl'

Masterform supports the datalist field. By pressing any key an ajax request is send to the server and the result is added to the datalist.

By change of the field, the ID of the foreign table is set. This is only working well, when the datalistcolumn is unique.

To get this support of the masterdata element, this properties have to be set:

datalist
- datadefID
- IDfield, if the field is member of an input-group, the hidden field of this input-group is used as IDfield
- onlyoptions: true/(default: false)

To fill additional fields after choosing the foreign key, the fields need to be written in the 'data-fieldlist'.

attributes
- data-fieldlist:"partnernumber,name1,name2,street,country,code,city"

Data exchange: Form <=> JavaScript

Not all form elements can easily exchanged by value. Thease functions help you with the data exchange:

Functions

obj2form(obj,el_form,bonlyadd)
form2obj(el_form)
$(el_form).serializeJSON({checkboxUncheckedValue: "0"})

The differences to the PHP handling are:

checkbox: unchecked returns 0
disabled fields are also returned

Form

Json Source/Result

please take care to write Json here
with ->Form you fill the form
change the form data
with submit you get back result

Please edit and press "->Form"

Form validation

Validation is an important subject by data entry. The most common validations are by:

HTML
JavaScript
PHP

HTML Validation

This are the HTML validation related attributes:

pattern
min
max
required
step
minlength
maxlength

For more details look at: Mozilla Contraint validation

CSS

This are the CSS pseudo classes for validation:

required
valid
invalid

All invalid elements show a red exclamation mark:

Valid required inputs show a green checked symbol: .

The submit event only takes effect after the HTML validation is successful.

JavaScript Validation

This is the call back function of the datadefinition:

dataBeforeSave(el_md,dat,settings);

The process of validation:

remove the invalid class for all elments
checked element is invalid:
- set the invalid class for this element
- 1st invalid element?
focus the 1st invalid element
if necessary, output a message

Example of a JavaScript validation with masterdata form:

PHP Validation

The masterdata data access class implemented the following checks:

field is included in the table
data entry valid for the SQL column type
required by insert

The datadefinition uses the following include for validation:

An error in this validation is returned by Ajax and displayed in the message tag.

Example of PHP validation with masterdata data access class:

<?php
if(getFromArray($this->postfields,'status',0)==1){
  $fieldsmissing=array();
  $keyvalue=getfromArray($this->postfields,$this->key,0);
  if(gbnull($keyvalue)){
    $this->error='save first preparation status';
  }else{
    if(!$this->dbclass->bexist('k8references','clientID='.$this->clientID.' and basetype="'.$this->db->real_escape_string($this->table).
            '" and baseID="'.$this->db->real_escape_string($keyvalue).'" and type="image"')){
      $this->error.='upload picture please';
    }
  }
  if(gbnull(getFromArray($this->postfields,'componentnumber')))$fieldsmissing[]='componentnumber';
  if(gbnull(getFromArray($this->postfields,'text1')))$fieldsmissing[]='text1';
  if(gbnull(getFromArray($this->postfields,'textdimensions')))$fieldsmissing[]='textdimensions';
  if(gbnull(getFromArray($this->postfields,'descriptionlong')))$fieldsmissing[]='descriptionlong';
  if(count($fieldsmissing)>0){
    $this->error=gsclauseand($this->error,'missing fields: '.implode(',',$fieldsmissing),true,", ");
  }
}