AbstractBuildForm.php

<?php
/**
 * Created by PhpStorm.
 * User: crose
 * Date: 1/6/16
 * Time: 8:02 PM
 */
namespace qfq;

use qfq;
use qfq\Store;
use qfq\UserException;
use qfq\OnArray;

require_once(__DIR__ . '/../qfq/store/Store.php');
require_once(__DIR__ . '/../qfq/Constants.php');
require_once(__DIR__ . '/../qfq/exceptions/DbException.php');
require_once(__DIR__ . '/../qfq/exceptions/UserException.php');
require_once(__DIR__ . '/../qfq/Database.php');
require_once(__DIR__ . '/../qfq/helper/HelperFormElement.php');
require_once(__DIR__ . '/../qfq/helper/Support.php');
require_once(__DIR__ . '/../qfq/helper/OnArray.php');


/**
 * Class AbstractBuildForm
 * @package qfq
 */
abstract class AbstractBuildForm {
    protected $formSpec = array();  // copy of the loaded form
    protected $feSpecAction = array(); // copy of all formElement.class='action' of the loaded form
    protected $feSpecNative = array(); // copy of all formElement.class='native' of the loaded form
    protected $store = null;
    protected $evaluate = null;
    protected $buildElementFunctionName = array();
    protected $pattern = array();
    protected $wrap = array();

    private $formId = null;

    public function __construct(array $formSpec, array $feSpecAction, array $feSpecNative) {
        $this->formSpec = $formSpec;
        $this->feSpecAction = $feSpecAction;
        $this->feSpecNative = $feSpecNative;
        $this->store = Store::getInstance();
        $this->db = new Database();
        $this->evaluate = new Evaluate($this->store, $this->db);

//        $sip = $this->store->getVar(CLIENT_SIP, STORE_CLIENT);

        // render mode specific
        $this->fillWrap();

        $this->buildElementFunctionName = [
            'checkbox' => 'Checkbox',
            'dateJQW' => 'DateJQW',
            'datetimeJQW' => 'DateJQW',
            'email' => 'Input',
            'gridJQW' => 'GridJQW',
            'hidden' => 'Hidden',
            'text' => 'Input',
            'note' => 'Note',
            'password' => 'Input',
            'radio' => 'Radio',
            'select' => 'Select',
            'subrecord' => 'Subrecord',
            'upload' => 'File',
            'fieldset' => 'Fieldset',
            'pill' => 'Pill'
        ];

        $this->buildRowName = [
            'checkbox' => 'Native',
            'dateJQW' => 'Native',
            'datetimeJQW' => 'Native',
            'email' => 'Native',
            'gridJQW' => 'Native',
            'hidden' => 'Native',
            'text' => 'Native',
            'note' => 'Native',
            'password' => 'Native',
            'radio' => 'Native',
            'select' => 'Native',
            'subrecord' => 'Subrecord',
            'upload' => 'Native',
            'fieldset' => 'Fieldset',
            'pill' => 'Pill'
        ];

        $this->inputCheckPattern = OnArray::inputCheckPatternArray();

    }

    abstract public function fillWrap();

    /**
     * Builds complete form. Depending of Formspecification, the layout will plain / table / bootstrap.
     *
     * @return string The whole form as HTML
     * @throws CodeException
     * @throws DbException
     */
    public function process() {

        $html = $this->head();

        $filter = $this->getProcessFilter();

        if ($this->formSpec['multiMode'] !== 'none') {

            $parentRecords = $this->db->sql($this->formSpec['multiSql']);
            foreach ($parentRecords as $row) {
                $this->store->setVarArray($row, STORE_PARENT_RECORD, true);
                $html .= $this->elements($row['_id'], $filter);
            }
        } else {
            $html .= $this->elements($this->store->getVar(SIP_RECORD_ID, STORE_SIP), $filter);
        }

        // close the form
        $html .= $this->tail();


        $html .= $this->doSubrecords();

        return $html;
    }

    /**
     * Builds the head area of the form.
     *
     * @return string
     */
    public function head() {
        $html = '';

        $html .= '<div ' . $this->getAttribute('class', $this->formSpec['class'], TRUE) . '>'; // main <div class=...> around everything

        $html .= $this->wrapItem(WRAP_SETUP_TITLE, $this->formSpec['title'], true);

        $html .= $this->getFormTag();

        return $html;
    }

    /**
     * Wrap's $this->wrap[$item][WRAP_SETUP_START] around $value. If $flagOmitEmpty==true && $value=='': return ''.
     *
     * @param $item
     * @param $value
     * @param bool|false $flagOmitEmpty
     * @return string
     */
    public function wrapItem($item, $value, $flagOmitEmpty = false) {
        if ($flagOmitEmpty && $value === "")
            return '';
        return $this->wrap[$item][WRAP_SETUP_START] . $value . $this->wrap[$item][WRAP_SETUP_END];
    }

    /**
     * Rreturns complete '<form ...>'-tag
     *
     * @return string
     */
    public function getFormTag() {

        $attribute = $this->getFormTagAtrributes();

        return '<form ' . OnArray::toString($attribute, '=', ' ', "'") . '>';
    }

    /**
     * Build an assoc array with standard form attributes.
     *
     * @return mixed
     */
    public function getFormTagAtrributes() {

        //TODO: ttconetn id eintragen
//        $attribute['id'] = $this->store->getVar(STORE_TYPO3,'1234');
        $attribute['id'] = $this->getFormId();
        $attribute['method'] = 'post';
        $attribute['action'] = $this->getActionUrl();
        $attribute['target'] = '_top';
        $attribute['accept-charset'] = 'UTF-8';
        $attribute['autocomplete'] = 'on';
        $attribute['enctype'] = $this->getEncType();

        return $attribute;
    }

    /**
     * @return string
     */
    public function getFormId() {
        if ($this->formId === null) {
            $this->formId = uniqid('qfq-form-');
        }
        return $this->formId;
    }

    /**
     * Builds the HTML 'form'-tag inlcuding all attributes and target.
     *
     * Notice: the SIP will be transferred as POST Parameter.
     *
     * @return string
     * @throws DbException
     */
    public function getActionUrl() {
        return 'typo3conf/ext/qfq/qfq/api/save.php';

        $queryStringArray = array();

        Support::appendTypo3ParameterToArray($queryStringArray);

        return basename($_SERVER['SCRIPT_NAME']) . "?" . Support::arrayToQueryString($queryStringArray);
    }

    /**
     * Determines the enctype.
     *
     * See: https://www.w3.org/wiki/HTML/Elements/form#HTML_Attributes
     *
     * @return string
     * @throws DbException
     */
    public function getEncType() {

        $result = $this->db->sql("SELECT id FROM FormElement AS fe WHERE fe.formId=? AND fe.type='upload' LIMIT 1", ROW_REGULAR, [$this->formSpec['id']], 'Look for Formelement.type="upload"');
        return (count($result) === 1) ? 'multipart/form-data' : 'application/x-www-form-urlencoded';

    }

    abstract public function getProcessFilter();

    /**
     * @param $recordId
     * @param string $filter FORM_ELEMENTS_NATIVE | FORM_ELEMENTS_SUBRECORD | FORM_ELEMENTS_NATIVE_SUBRECORD
     * @param int $feIdContainer
     * @return string
     * @throws CodeException
     * @throws DbException
     * @throws \qfq\UserException
     */
    public function elements($recordId, $filter = FORM_ELEMENTS_NATIVE, $feIdContainer = 0) {
        $html = '';

        // get current data record
        if ($recordId > 0 && $this->store->getVar('id', STORE_RECORD) === false) {
            $row = $this->db->sql("SELECT * FROM " . $this->formSpec['tableName'] . " WHERE id = ?", ROW_REGULAR, array($recordId));
            $this->store->setVarArray($row[0], STORE_RECORD);
        }

        // Iterate over all FormElements
        foreach ($this->feSpecNative as $fe) {

            if (($filter === FORM_ELEMENTS_NATIVE && $fe['type'] === 'subrecord') ||
                ($filter === FORM_ELEMENTS_SUBRECORD && $fe['type'] !== 'subrecord')
            ) {
                continue; // skip this FE
            }

            // Log / Debug
            $this->store->setVar(SYSTEM_FORM_ELEMENT, $fe['name'] . ' / ' . $fe['id'], STORE_SYSTEM);

            // evaluate current FormElement
            $evaluate = new Evaluate($this->store, $this->db);
            $formElement = $evaluate->parseArray($fe, $fe['debug'] === 'yes');
            if ($fe['debug'] === 'yes') {
                throw new UserException($evaluate->getDebug(), ERROR_DEBUG);
            }

            // Get default value
            $value = $formElement['value'] === '' ? $this->store->getVar($formElement['name']) : $value = $formElement['value'];

            $htmlFormElementId = HelperFormElement::buildFormElementId($formElement['name'], $recordId);

            // Construct Marshaller Name
            $buildElementFunctionName = 'build' . $this->buildElementFunctionName[$formElement['type']];

            // Render pure element
            $elementHtml = $this->$buildElementFunctionName($formElement, $htmlFormElementId, $value);

            // Construct Marshaller Name
            $buildRowName = 'buildRow' . $this->buildRowName[$formElement['type']];

            $html .= $this->$buildRowName($formElement, $elementHtml);
        }

        // Log / Debug: Last FormElement has been processed.
        $this->store->setVar(SYSTEM_FORM_ELEMENT, '', STORE_SYSTEM);

        return $html;
    }

    abstract public function tail();

    abstract public function doSubrecords();

    abstract public function buildRowNative($formElement, $elementHtml);

    abstract public function buildRowPill($formElement, $elementHtml);

    abstract public function buildRowFieldset($formElement, $elementHtml);

    abstract public function buildRowSubrecord($formElement, $elementHtml);

    /**
     * Extract Tag from $tag (might contain further attributes) and wrap it around $value. If $flagOmitEmpty==true && $value=='': return ''.
     *
     * @param $tag
     * @param $value
     * @param bool|false $flagOmitEmpty
     * @return string
     */
    public function wrapTag($tag, $value, $flagOmitEmpty = false) {
        if ($flagOmitEmpty && $value === "")
            return '';

        // <div class="container-fluid"> >> </div>
        $arr = explode(' ', $tag);
        $closing = '</' . substr($arr[0], 1) . '>';

        return $tag . $value . $closing;
    }

    /**
     * Builds a label, typically for an html-'<input>'-element.
     *
     * @param array $htmlFormElementId
     * @param $label
     * @return string
     */
    public function buildLabel($htmlFormElementId, $label) {
        $html = '<label for="' . $htmlFormElementId . '">' . $label . '</label>';

        return $html;
    }

    /**
     * Builds HTML 'input' element.
     * Format: <input name="$htmlFormElementId" <type="email|input|password|url" [autocomplete="autocomplete"] [autofocus="autofocus"]
     *           [maxlength="$maxLength"] [placeholder="$placeholder"] [size="$size"] [min="$min"] [max="$max"]
     *           [pattern="$pattern"] [readonly="readonly"] [required="required"] [disabled="disabled"] value="$value">
     *
     *
     * @param array $formElement
     * @param $htmlFormElementId
     * @param $value
     * @return string
     * @throws UserException
     */
    public function buildInput(array $formElement, $htmlFormElementId, $value) {
        $textarea = '';

        $attribute = $this->getAttribute('name', $htmlFormElementId);
        $htmlTag = '<input';

        // MIN( $formElement['maxLength'], tabledefinition)
        $maxLength = $this->getColumnSize($formElement['name']);
        if ($maxLength !== false) {
            if (is_numeric($formElement['maxLength'])) {
                if ($formElement['maxLength'] > $maxLength) {
                    $formElement['maxLength'] = $maxLength;
                }
            } else {
                $formElement['maxLength'] = $maxLength;
            }
        }

        // Check for input type 'textarea'
        $colsRows = explode(',', $formElement['size'], 2);
        if (count($colsRows) === 2) {
            // <textarea>
            $htmlTag = '<textarea';

            $attribute .= $this->getAttribute('cols', $colsRows[0]);
            $attribute .= $this->getAttribute('rows', $colsRows[1]);
            $textarea = htmlentities($value) . '</textarea>';

        } else {
            // <input>
            if ($formElement['maxLength'] > 0) {
                $value = substr($value, 0, $formElement['maxLength']);

                $attribute .= $this->getAttributeList($formElement, ['type', 'size', 'maxLength']);
                $attribute .= $this->getAttribute('value', htmlentities($value), false);
            }
        }

        // 'maxLength' needs an upper 'L': naming convention for DB tables!
        $attribute .= $this->getAttributeList($formElement, ['autocomplete', 'autofocus', 'placeholder']);
        $attribute .= $this->getAttribute('title', $formElement['tooltip']);
        $attribute .= $this->getInputCheckPattern($formElement['checkType'], $formElement['checkPattern']);

        $attribute .= $this->getAttributeMode($formElement);

        return "$htmlTag $attribute>$textarea";

    }

    /**
     * Format's an attribute: $type=$value. If $flagOmitEmpty==true && $value=='': return ''.
     *
     * @param $type
     * @param $value
     * @param bool|false $flagOmitEmpty
     * @return string
     */
    public function getAttribute($type, $value, $flagOmitEmpty = true) {
        if ($flagOmitEmpty && $value === "")
            return '';

        return $type . '="' . trim($value) . '" ';
    }

    /**
     * @param $column
     * @return bool|int|string
     */
    private function getColumnSize($column) {
        $matches = array();

        $typeSpec = $this->store->getVar($column, STORE_TABLE_COLUMN_TYPES);

        if (1 === preg_match('/\((.+)\)/', $typeSpec, $matches)) {
            if (is_numeric($matches[1]))
                return $matches[1];
        }

        return false;
    }

    /**
     * Builds a HTML attribute list, based on  $attributeList.
     *
     * E.g.: attributeList: [ 'type', 'autofocus' ]
     *       generates: 'type="$formElement['type']" autofocus="$formElement['autofocus']" '
     *
     * @param array $formElement
     * @param array $attributeList
     * @return string
     */
    private function getAttributeList(array $formElement, array $attributeList) {
        $attribute = '';
        foreach ($attributeList as $item) {
            if (isset($formElement[$item]))
                $attribute .= $this->getAttribute(strtolower($item), $formElement[$item]);
        }
        return $attribute;
    }

    /**
     * Construct HTML Input attribute for Client Validation:
     *
     *   type     data                      predefined
     *   -------  -----------------------   -------------------------------------------------------------------------------
     *   min|max  <min value>|<max value>   min="%s"|max="%s"
     *   pattern  <regexp>                  pattern="%s"
     *   number   -                         pattern="^[0-9]*$"
     *   email    -                         pattern="^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*(\.[a-z]{2,4})$"
     *
     * For 'min|max' and 'pattern' the 'data' will be injected in the attribute string vai '%s'.
     *
     * @param $type
     * @param $data
     * @return string
     * @throws \qfq\UserException
     */
    private function getInputCheckPattern($type, $data) {
        if ($type === '') {
            return '';
        }

        $attribute = '';

        $arrAttr = explode("|", $this->inputCheckPattern[$type]);
        $arrData = explode("|", $data);

        for ($ii = 0; $ii < count($arrAttr); $ii++) {
            if ($arrAttr[$ii]) {
                if (!isset($arrData[$ii]))
                    throw new UserException("Missing MIN|MAX values", ERROR_MISSING_MIN_MAX);
                $attribute .= str_replace('%s', trim($arrData[$ii]), $arrAttr[$ii]) . ' ';
            }
        }
        return $attribute;
    }


    /**
     * Set corresponding html attributes readonly/required/disabled, based on $formElement['mode'].
     *
     * @param array $formElement
     * @return string
     * @throws UserException
     */
    private function getAttributeMode(array $formElement) {
        $attribute = '';

        switch ($formElement['mode']) {
            case 'show':
                break;
            case 'readonly':
                $attribute .= $this->getAttribute('readonly', 'readonly');
                break;
            case 'required':
                $attribute .= $this->getAttribute('required', 'required');
                break;
            case 'lock':
                break;
            case 'disabled':
                $attribute .= $this->getAttribute('disabled', 'disabled');
                break;
            default:
                $this->store->setVar(SYSTEM_FORM_ELEMENT, $formElement['name'] . ' / ' . $formElement['id'], STORE_SYSTEM);
                $this->store->setVar(SYSTEM_FORM_ELEMENT_COLUMN, 'mode', STORE_SYSTEM);
                throw new UserException("Unknown mode '" . $formElement['mode'] . "'", ERROR_UNKNOWN_MODE);
                break;
        }
        return $attribute;
    }

    /**
     * Builds HTML 'checkbox' element.
     *
     * Checkboxes will only be submitted, if they are checked. Therefore, a hidden element with the unchecked value will be transfered first.
     *
     * Format: <input type="hidden" name="$htmlFormElementId" value="$valueUnChecked">
     *         <input name="$htmlFormElementId" type="checkbox" [autofocus="autofocus"]
     *            [readonly="readonly"] [required="required"] [disabled="disabled"] value="<value>" [checked="checked"] >
     *
     * @param array $formElement
     * @param $htmlFormElementId
     * @param $value
     * @return string
     * @throws UserException
     */
    public function buildCheckbox(array $formElement, $htmlFormElementId, $value) {
        $itemKey = array();
        $itemValue = array();

        // Fill $itemKey & $itemValue
        $this->getKeyValueListFromSqlEnumSpec($formElement, $itemKey, $itemValue);

        // Get fallback, if 'checkBoxMode' is not defined:
        if (!isset($formElement['checkBoxMode'])) {
            // This fallback is problematic if 'set' or 'enum' has 2 : defaults to single but maybe multi is meant.
            $formElement['checkBoxMode'] = (count($itemKey) > 2) ? 'multi' : 'single';
        }

        if ($formElement['checkBoxMode'] === 'multi') {
            $htmlFormElementId .= '[]';
        } else {
            // Fill meaningfull defaults to parameter:checked|unchecked
            $this->prepareCheckboxCheckedUncheckedValue($itemKey, $formElement);
        }

        $attributeBase = $this->getAttributeMode($formElement);
        $attributeBase .= $this->getAttribute('type', $formElement['type']);

        switch ($formElement['checkBoxMode']) {
            case 'single':
                $html = $this->buildCheckboxSingle($formElement, $htmlFormElementId, $attributeBase, $value);
                break;
            case 'multi';
                $html = $this->buildCheckboxMulti($formElement, $htmlFormElementId, $attributeBase, $value, $itemKey, $itemValue);
                break;
            default:
                throw new UserException('checkBoxMode: \'' . $formElement['checkBoxMode'] . '\' is unknown.', ERROR_CHECKBOXMODE_UNKNOWN);
        }

        return $html;
    }

    /**
     * Look for key/value list (in this order, first match counts) in
     *  a) `sql1`
     *  b) `parameter:itemList`
     *  c) table.column definition
     *
     * Copies the found keys to &$itemKey and the values to &$itemValue
     * If there are no &$itemKey, copy &$itemValue to &$itemKey.
     *
     * @param array $formElement
     * @param $itemKey
     * @param $itemValue
     * @throws CodeException
     * @throws \qfq\UserException
     */
    public function getKeyValueListFromSqlEnumSpec(array $formElement, &$itemKey, &$itemValue) {
        $fieldType = '';
        $itemKey = array();
        $itemValue = array();

        if (count($formElement) < 20)
            throw new CodeException("Invalid (none or to small) Formelement", ERROR_MISSING_FORMELEMENT);

        $itemValue = $this->getItemsForEnumOrSet($formElement['name'], $fieldType);

        if (is_array($formElement['sql1'])) {
            if (count($formElement['sql1']) > 0) {
                $keys = array_keys($formElement['sql1'][0]);
                $itemKey = array_column($formElement['sql1'], 'id');

                // If there is no column 'id' and at least two columns in total
                if (count($itemKey) === 0 && count($keys) >= 2) {
                    $itemKey = array_column($formElement['sql1'], $keys[0]);
                }

                $itemValue = array_column($formElement['sql1'], 'label');
                // If there is no column 'label' (e.g.: SHOW tables)
                if (count($itemValue) === 0) {
                    $idx = count($keys) == 1 ? 0 : 1;
                    $itemValue = array_column($formElement['sql1'], $keys[$idx]);
                }
            }
        } elseif (isset($formElement['itemList']) && strlen($formElement['itemList']) > 0) {
            $arr = KeyValueStringParser::parse($formElement['itemList'], ':', ',', KVP_IF_VALUE_EMPTY_COPY_KEY);
            $itemValue = array_values($arr);
            $itemKey = array_keys($arr);
        } elseif ($fieldType === 'enum' || $fieldType === 'set') {
            // already done at the beginning with '$this->getItemsForEnumOrSet($formElement['name'], $fieldType);'
        } else {
            throw new UserException("Missing definition (- nothing found in 'sql1', 'parameter:itemValues', 'enum-' or 'set-definition'", ERROR_MISSING_ITEM_VALUES);
        }

        if (count($itemKey) === 0) {
            $itemKey = $itemValue;
        }

        if (isset($formElement['emptyItemAtStart'])) {
            array_unshift($itemKey, '');
            array_unshift($itemValue, '');
        }

        if (isset($formElement['emptyItemAtEnd'])) {
            $itemValue[] = '';
            $itemKey[] = '';
        }
    }

    /**
     * Get the attribute definition list of an enum or set column. For strings, get the default value. Return elements as an array.
     *
     * @param $column
     * @param $fieldType
     * @return array
     * @throws UserException
     */
    private function getItemsForEnumOrSet($column, &$fieldType) {

        // Get column definition
        $fieldTypeDefinition = $this->store->getVar($column, STORE_TABLE_COLUMN_TYPES);

        if ($fieldTypeDefinition === false) {
            throw new UserException("Column '$column' unknown in table '" . $this->formSpec['tableName'] . "'", ERROR_DB_UNKNOWN_COLUMN);
        }

        $length = strlen($fieldTypeDefinition);

        // enum('...   set('
        switch (substr($fieldTypeDefinition, 0, 4)) {
            case 'enum':
                $startPosition = 5;
                break;
            case 'set(':
                $startPosition = 4;
                break;
            default:
                $fieldType = 'string';
                return array();
        }

        // enum('a','b','c', ...)   >> [ 'a', 'b', 'c', ... ]
        // set('a','b','c', ...)   >> [ 'a', 'b', 'c', ... ]
        $items = OnArray::trimArray(explode(',', substr($fieldTypeDefinition, $startPosition, $length - $startPosition - 1)), "'");
        $fieldType = substr($fieldTypeDefinition, 0, $startPosition - 1);

        return $items;
    }

    /**
     * For CheckBox's with only one checkbox: if no parameter:checked|unchecked is defined, take defaults:
     *
     *    checked: first Element in $itemKey
     *  unchecked: ''
     *
     * @param array $itemKey
     * @param array $formElement
     * @throws UserException
     */
    private function prepareCheckboxCheckedUncheckedValue(array $itemKey, array &$formElement) {

        if (!isset($formElement['checked'])) {
            if (isset($itemKey[0])) {
                // First element in $itemKey list
                $formElement['checked'] = $itemKey[0];
            } else {
                // Take column default value
                $formElement['checked'] = $this->store->getVar($formElement['name'], STORE_TABLE_DEFAULT);
            }
        }

        // unchecked
        if (!isset($formElement['unchecked'])) {
            if (isset($itemKey[1])) {
                $formElement['unchecked'] = ($itemKey[0] === $formElement['checked']) ? $itemKey[1] : $itemKey[0];
            } else {
                $formElement['unchecked'] = '';
            }
        }

        if ($formElement['checked'] === $formElement['unchecked']) {
            throw new UserException('FormElement: type=checkbox - checked and unchecked can\'t be the same: ' . $formElement['checked'], ERROR_CHECKBOX_EQUAL);
        }

    }

    /**
     * Build a Checkbox based on two values.
     *
     * @param array $formElement
     * @param $htmlFormElementId
     * @param $attribute
     * @param $value
     * @return string
     */
    public function buildCheckboxSingle(array $formElement, $htmlFormElementId, $attribute, $value) {
        $html = '';

        $attribute .= $this->getAttribute('name', $htmlFormElementId);
        $attribute .= $this->getAttribute('value', $formElement['checked'], false);
        if ($formElement['checked'] === $value) {
            $attribute .= $this->getAttribute('checked', 'checked');
        }

        $attribute .= $this->getAttributeList($formElement, ['autofocus']);

        $html = $this->buildNativeHidden($htmlFormElementId, $formElement['unchecked']);

        $html .= '<input ' . $attribute . '>';
        if (isset($formElement['label2'])) {
            $html .= $formElement['label2'];
        }

        return $html;
    }

    /**
     * Builds a real HTML hidden form element. Usefull for Checkboxes, Multiple-Select and Radios.
     *
     * @param $htmlFormElementId
     * @param $value
     * @return string
     */
    public function buildNativeHidden($htmlFormElementId, $value) {
        return '<input type="hidden" name="' . $htmlFormElementId . '" value="' . htmlentities($value) . '">';
    }

    /**
     * Build as many Checkboxes as items
     * @param array $formElement
     * @param $htmlFormElementId
     * @param $attributeBase
     * @param $value
     * @param array $itemKey
     * @param array $itemValue
     * @return string
     */
    public function buildCheckboxMulti(array $formElement, $htmlFormElementId, $attributeBase, $value, array $itemKey, array $itemValue) {
        // Defines which of the checkboxes will be checked.
        $values = explode($value, ',');

        $attributeBase .= $this->getAttribute('name', $htmlFormElementId);

        $html = $this->buildNativeHidden($htmlFormElementId, $value);

        $flagFirst = true;
        $ii = 0;
        $jj = 0;
        foreach ($itemKey as $item) {
            $ii++;
            $jj++;
            $attribute = $attributeBase;
            if ($flagFirst) {
                $flagFirst = false;
                if (isset($formElement['autofocus']))
                    $attribute .= $this->getAttribute('autofocus', $formElement['autofocus']);
            }
            $attribute .= $this->getAttribute('value', $item);
            if ($item === $values[$jj]) {
                $attribute .= $this->getAttribute('checked', 'checked');
            }
            $html .= '<input ' . $attribute . '>';
            $html .= $itemValue[$ii];
            if ($ii === $formElement['maxLength']) {
                $ii = 0;
                $html .= '<br>';
            }
        }
        return $html;
    }

    /**
     * Submit hidden values by SIP.
     *
     * Sometimes, it's usefull to precalculate values during formload and to submit them as hidden fields.
     * To avoid any manipulation on those fields, the values will be transferred by SIP.
     *
     * @param array $formElement
     * @param $htmlFormElementId
     * @param $value
     * @return string
     */
    public function buildHidden(array $formElement, $htmlFormElementId, $value) {

        $this->store->setVar($htmlFormElementId, $value, STORE_SIP, false);
    }

    /**
     * Build HTML 'radio' element.
     *
     * Checkboxes will only be submitted, if they are checked. Therefore, a hidden element with the unchecked value will be transfered first.
     *
     * Format: <input type="hidden" name="$htmlFormElementId" value="$valueUnChecked">
     *         <input name="$htmlFormElementId" type="radio" [autofocus="autofocus"]
     *            [readonly="readonly"] [required="required"] [disabled="disabled"] value="<value>" [checked="checked"] >
     *
     * @param array $formElement
     * @param $htmlFormElementId
     * @param $value
     * @return string
     * @throws UserException
     */
    public function buildRadio(array $formElement, $htmlFormElementId, $value) {
        $itemKey = array();
        $itemValue = array();

        // Fill $itemKey & $itemValue
        $this->getKeyValueListFromSqlEnumSpec($formElement, $itemKey, $itemValue);

        $attributeBase = $this->getAttributeMode($formElement);
        $attributeBase .= $this->getAttribute('name', $htmlFormElementId);
        $attributeBase .= $this->getAttribute('type', $formElement['type']);

        $jj = 0;
        $flagFirst = true;

        $html = $this->buildNativeHidden($htmlFormElementId, $value);
        for ($ii = 0; $ii < count($itemValue); $ii++) {
            $jj++;
            $attribute = $attributeBase;
            if ($flagFirst) {
                $flagFirst = false;
                if (isset($formElement['autofocus']))
                    $attribute .= $this->getAttribute('autofocus', $formElement['autofocus']);
            }

            $attribute .= $this->getAttribute('value', $itemKey[$ii]);
            if ($itemKey[$ii] === $value) {
                $attribute .= $this->getAttribute('checked', 'checked');
            }
            $html .= '<input ' . $attribute . '>';
            $html .= $itemValue[$ii];
            if ($jj === $formElement['maxLength']) {
                $jj = 0;
                $html .= '<br>';
            }
        }
        return $html;
    }

    /**
     * Builds a Selct (Dropdown) Box.
     *
     * @param array $formElement
     * @param $htmlFormElementId
     * @param $value
     * @return mixed
     */
    public function buildSelect(array $formElement, $htmlFormElementId, $value) {
        $itemKey = array();
        $itemValue = array();

        // Fill $itemKey & $itemValue
        $this->getKeyValueListFromSqlEnumSpec($formElement, $itemKey, $itemValue);

        $attribute = $this->getAttributeMode($formElement);
        $attribute .= $this->getAttribute('name', $htmlFormElementId);
        $attribute .= $this->getAttributeList($formElement, ['autofocus']);

        if (isset($formElement['size']) && $formElement['size'] > 1) {
            $attribute .= $this->getAttribute('size', $formElement['size']);
            $attribute .= $this->getAttribute('multiple', 'multiple');
        }

        $option = '';
        $selected = 'selected';
        for ($ii = 0; $ii < count($itemValue); $ii++) {
            $option .= '<option ';

            $option .= $this->getAttribute('value', $itemKey[$ii]);
            if ($itemKey[$ii] === $value) {
                $option .= $selected;
                $selected = '';
            }

            $option .= '>' . $itemValue[$ii] . '</option>';
        }

        return '<select ' . $attribute . '>' . $option . '</select>';
    }

    /**
     * Constuct a HTML table of the subrecord data.
     * Column syntax definition: https://wikiit.math.uzh.ch/it/projekt/qfq/qfq-jqwidgets/Documentation#Type:_subrecord
     *
     * @param array $formElement
     * @param $htmlFormElementId
     * @param $value
     * @return string
     * @throws UserException
     */
    public function buildSubrecord(array $formElement, $htmlFormElementId, $value) {
        $html = '';

        $primaryRecord = $this->store->getStore(STORE_RECORD);

        if (!isset($primaryRecord['id'])) {
            return 'Please save main record fist.';
        }

        if (!is_array($formElement['sql1'])) {
            throw new UserException('Missing \'sql1\' Query', ERROR_MISSING_SQL1);
        }

        // No records?
        if (count($formElement['sql1']) == 0) {
            return '';
        }

        if (!isset($formElement['sql1'][0]['id'])) {
            throw new UserException('Missing column \'id\' in  \'sql1\' Query', ERROR_DB_MISSING_COLUMN_ID);
        }

        // construct column attributes
        $control = $this->getSubrecordColumnControl(array_keys($formElement['sql1'][0]));

//        $html .= '<b>' . $formElement['label'] . '</b>';
//        $html .= '<table border="1">';
        $html .= '<table class="table">';
        $html .= '<tr><th></th><th>' . implode('</th><th>', $control['title']) . '</th></tr>';
        foreach ($formElement['sql1'] as $row) {

            $html .= '<tr>';
            $html .= '<td>' . $this->editLink($formElement, $row['id'], $primaryRecord) . '</td>';

            foreach ($row as $columnName => $value) {
                $html .= '<td>' . $this->renderCell($control, $columnName, $value) . '</td>';
            }
            $html .= '</tr>';
        }
        $html .= '</table>';

        return $html;
    }

    /**
     * Get various column format information based on the 'raw' column title. The attributes are separated by '|' and specified as 'key' or 'key=value'.
     *
     * - Return all parsed values as an assoc array.
     * - For regular columns: If there is no 'width' specified, take the default 'SUBRECORD_COLUMN_WIDTH'
     * - For 'icon /  url / mailto': no width limit.
     *
     * Returned assoc array:
     *  title      Only key. Element is non numeric, which is not a keyword 'width/nostrip/icon/url/mailto'
     *  width      Key/Value Pair. Not provided for 'icon/url/mailto'.
     *  nostrip    Only key. Do not strip HTML Tags from the content.
     *  icon       Only key. Value will rendered (later) as an image.
     *  url        Only key. Value will rendered (later) as a 'href'
     *  mailto     Only key. Value will rendered (later) as a 'href mailto'
     *
     *
     * @param $titleRaw
     * @return array
     * @throws UserException
     */
    private function getSubrecordColumnControl(array $titleRaw) {
        $control = array();

        foreach ($titleRaw AS $columnName) {
            $flagWidthLimit = true;
            $control['width'][$columnName] = SUBRECORD_COLUMN_WIDTH;

            // a) 'City@width=40', b) 'Status@icon', c) 'Mailto@width=80@nostrip'
            $arr = KeyValueStringParser::parse($columnName, '=', '|', KVP_IF_VALUE_EMPTY_COPY_KEY);
            foreach ($arr as $attribute => $value) {
                switch ($attribute) {