Form.rst

| checked                         |                                                                                                          |
| unchecked                       |                                                                                                          |
| label2                          |                                                                                                          |
| itemList                        |                                                                                                          |
| emptyHide                       |                                                                                                          |
| emptyItemAtStart                |                                                                                                          |
| emptyItemAtEnd                  |                                                                                                          |
| buttonClass                     |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| dateFormat                      | yyyy-mm-dd / dd.mm.yyyy                                                                                  |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| data-pattern-error              | Pattern violation: Text for error message                                                                |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| data-required-error             | Required violation: Text for error message                                                               |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| data-match-error                | Match violation: Text for error message                                                                  |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| data-error                      | Violation of 'check-type': Text for error message                                                        |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| decimalFormat                   | [precision,scale] Limits and formats input to a decimal number with the specified precision and scale.   |
|                                 | If no precision and scale are specified, the decimal format is pulled from the table definition.         |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| htmlAfter                       | HTML Code wrapped after the complete *FormElement*                                                       |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| htmlBefore                      | HTML Code wrapped before the complete *FormElement*                                                      |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| extraButtonLock                 | [0|1] Show a 'lock' on the right side of the input element. See :ref:`extraButtonLock`                   |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| extraButtonPassword             | [0|1] Show an 'eye' on the right side of the input element. See :ref:`extraButtonPassword`               |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| extraButtonInfo                 | Text. Show an 'i' on the right side of the input element. See :ref:`extraButtonInfo`                     |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| extraButtonInfoClass            | By default empty. Specify any class to be assigned to wrap extraButtonInfo                               |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| extraButtonInfoMinWidth         | See :ref:`extraButtonInfo`                                                                               |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| editor-plugins,                 | See :ref:`input-editor`                                                                                  |
| editor-toolbar,                 |                                                                                                          |
| editor-statusbar,               |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| fileButtonText                  | Overwrite default 'Choose File'                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| fillStoreVar                    | Fill the STORE_VAR with custom values. See :ref:`STORE_VARS`.                                            |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| form,                           | See :ref:`subrecord-option`                                                                              |
| page,                           |                                                                                                          |
| title,                          |                                                                                                          |
| extraDeleteForm,                |                                                                                                          |
| detail,                         |                                                                                                          |
| subrecordTableClass,            |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| min                      s/d/n  | Minimum and/or maximum allowed values for input field. Can be used for numbers, dates, or strings.       |
+---------------------------------+                                                                                                          |
| max                      s/d/n  | *Always use the international format 'yyyy-mm-dd[ hh:mm[:ss]]*                                           |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| processReadOnly                 | [0|1] By default FE's with type='readonly' are not processed during 'save'.                              |
|                                 | This option forces to process them during 'save' as well.                                                |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| retype,                         | See :ref:`retype`                                                                                        |
| retypeLabel,                    |                                                                                                          |
| retypeNote,                     |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| characterCountWrap,             | See :ref:`input-text`                                                                                    |
| hideZero,                       |                                                                                                          |
| emptyMeansNull,                 |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| showSeconds                     | 0|1 - Shows the seconds on form load. Default: 0                                                         |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| showZero                        | 0|1 - Empty timestamp: '0'(default) - nothing shown, '1' - the string '0000-00-00 00:00:00' is displayed |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| timeIsOptional                  | 0|1 - Used for datetime input. 0 (default): Time is required - 1: Entering a time is optional            |
|                                 | (defaults to 00:00:00 if none entered).                                                                  |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| typeAheadLimit,                 | See :ref:`input-typeahead`                                                                               |
| typeAheadInitialSuggestion,     |                                                                                                          |
| typeAheadMinLength,             |                                                                                                          |
| typeAheadSql,                   |                                                                                                          |
| typeAheadSqlPrefetch,           |                                                                                                          |
| typeAheadPedantic               |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| typeAheadTag,                   | See :ref:`type_ahead_tag`                                                                                |
| typeAheadGlueInsert,            |                                                                                                          |
| typeAheadGlueDelete,            |                                                                                                          |
| typeAheadTagInsert              |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| wrapRow                         | If specified, skip default wrapping (`<div class='col-md-?'>`). Instead the given string is used.        |
+---------------------------------+                                                                                                          |
| wrapLabel                       |                                                                                                          |
+---------------------------------+                                                                                                          |
| wrapInput                       |                                                                                                          |
+---------------------------------+                                                                                                          |
| wrapNote                        |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| trim                            | By default, whitespace is trimmed. To disable, use 'trim=none'. You can also specify custom trim         |
|                                 | characters: 'trim=\\ ' only trims spaces.                                                                |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| sqlValidate                     | See :ref:`sqlValidate`                                                                                   |
+---------------------------------+                                                                                                          |
| expectRecords                   |                                                                                                          |
+---------------------------------+                                                                                                          |
| messageFail                     |                                                                                                          |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| dataReference                   | Optional. See :ref:`applicationTest`                                                                     |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| requiredPosition                | See :ref:`requiredPosition`.                                                                             |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| minWidth                        | See :ref:`checkboxRadioMinWidth`.                                                                        |
+---------------------------------+----------------------------------------------------------------------------------------------------------+
| clearMe                         | 0 (off)|1(on) - Overwrite default from Form.parameter.clearMe or :ref:`configuration`. Show a small      |
|                                 | 'x' in input or textarea fields to clear the input.                                                      |
+---------------------------------+----------------------------------------------------------------------------------------------------------+


* `s/d/n`: string or date or number.

slaveId, sqlBefore, sqlAfter, ...
"""""""""""""""""""""""""""""""""

See :ref:`slave-id`


Native *FormElements*
"""""""""""""""""""""

* Like 'input', 'checkbox', ...

.. _`input-option-autofocus`:

autofocus
;;;;;;;;;

The first *FormElement* with this attribute will get the focus after form load. If there is no such attribute
given to any *FormElement*, the attribute will be automatically assigned to the first editable *FormElement*.

To disable 'autofocus' on a form, set 'autofocus=0' on the first editable *FormElement*.

Note: If there are multiple pills defined on a form, only the first pill will be set with 'autofocus'.

.. _`extraButtonLock`:

extraButtonLock
;;;;;;;;;;;;;;;

* The user has to click on the lock, before it's possible to change the value. This will protect data against unwanted modification.
* After Form load, the value is shown, but not editable.
* Shows a 'lock' on the right side of an input element of type `text`, `date`, `time` or `datetime`.
* This option is not available for FormElements with `mode=readonly`.
* There is no value needed for this parameter.

.. _`extraButtonPassword`:

extraButtonPassword
;;;;;;;;;;;;;;;;;;;

* The user has to click on the eye (unhide) to see the value.
* After Form load, the data is hided by asteriks.
* Shows an 'eye' on the right side of an input element of type `text`, `date`, `time` or `datetime`.
* There is no value needed for this parameter.

.. _`extraButtonInfo`:

extraButtonInfo
;;;;;;;;;;;;;;;

* After Form load,  the `info` button/icon is shown but the information message is hidden.
* The user has to click on the `info` button/icon to see an additional message.
* The value of this parameter is the text shown to the user.
* Shows an `info` button/icon, depending of `extraButtonInfoPosition` in :ref:`configuration`

  * `auto`, depending on `FormElement` type:

    * on the right side of an input element for type `text`, `date`, `time` or `datetime`,
    * below the FormElement for all other types.

  * `below`: below the FormElement for all types.

* `extraButtonInfoMinWidth`: default is 250 and defines a minimal width.
* For `FormElement` with mode `below`, a `span` element with the given class in `extraButtonInfoClass` (FE, F, :ref:`configuration`)
  will be applied. E.g. this might be `pull-right` to align the `info` button/icon on the right side below the input element.


.. _`checkboxRadioMinWidth`:

Checkbox / Radio: minWidth
^^^^^^^^^^^^^^^^^^^^^^^^^^

Checkbox and Radio Elements, shown in plain horizontal mode, receives a minWidth to align them. The default is 80px and
might be defined per Form or per FormElement.


.. _`requiredPosition`:

Required Position
^^^^^^^^^^^^^^^^^

By default, input elements with `Mode=required` will be displayed with a 'red asterix' right beside the label. The position
of the 'red asterix' can be choosen via the `parameter` field::

   requiredPosition = label-left|label-right|input-left|input-right|note-left|note-right

The default is 'label-right'.

The definition can be set per Form (=affects all FormElements) or per FormElement.




.. _`input-checkbox`:

Type: checkbox
^^^^^^^^^^^^^^

Checkboxes can be rendered in mode:

* *single*:

  * One column in a table corresponds to one checkbox.
  * The value for statuses *checked* and *unchecked* are free to choose.
  * This mode is selected, if a) *checkBoxMode* = single, or b) *checkBoxMode* is missing **and** the number of fields of the column definition is <3.
  * *FormElement.parameter*:

    * *checkBoxMode* = single (optional)
    * *checked* = <value> (optional, the value which represents 'checked')

      * If *checked* is empty or missing: If *type* = 'enum' or 'set', get first item of the definition. If *type* = string, get default.

    * *unchecked* = <value> (optional, the value which represents 'unchecked')

      * If *unchecked* is empty or missing: If *type* = 'enum' or 'set', get second item of checked. If *type* = 'string', get ''.

    * *label2* = <value>       (Text right beside checkbox) (optional)


* *multi*:

  * One column in a table represents multiple checkboxes. This is typically useful for the column type *set*.
  * The value for status *checked* are free to choose, the value for status *unchecked* is always the empty string.
  * Each field key (or the corresponding value from the key/value pair) will be rendered right beside the checkbox.
  * *FormElement.parameter*

    * *checkBoxMode* = multi
    * *itemList* - E.g.:

      * ``itemList=red,blue,orange``
      * ``itemList=1:red,2:blue,3:orange``
      * If ':' or ',' are part of key or value, it needs to escaped by \\ .
        E.g.: `itemList=1:red\\: (with colon),2:blue\\, (with comma),3:orange``

  * *FormElement.sql1* = ``{{!SELECT id, value FROM SomeTable}}``
  * *FormElement.maxlength* - vertical or horizontal alignment:

    * Value: '', 0, 1 - The check boxes will be aligned vertical.
    * Value: >1 - The  check boxes will be aligned horizontal, with a linebreak every 'value' elements.

* *FormElement.parameter*:

  * *emptyHide*: Existence of this item hides an entry with an empty string. This is useful for e.g. Enums, which have an empty
    entry, but the empty value should not be selectable.
  * *emptyItemAtStart*: Existence of this item inserts an empty entry at the beginning of the selectlist.
  * *emptyItemAtEnd*: Existence of this item inserts an empty entry at the end of the selectlist.
  * *buttonClass*: Instead of the plain HTML  checkbox fields, Bootstrap
    `buttons <http://getbootstrap.com/docs/3.4/javascript/#buttons-checkbox-radio>`_. are rendered as `checkbox` elements. Use
    one of the following `classes <http://getbootstrap.com/docs/3.4/css/#buttons-options>`_:

    * `btn-default` (default, grey),
    * `btn-primary` (blue),
    * `btn-success` (green),
    * `btn-info` (light blue),
    * `btn-warning` (orange),
    * `btn-danger` (red).

    With a given *buttonClass*, all buttons (=radios) are rendered horizontal. A value in *FormElement.maxlength* has no effect.

* *No preselection*:

  * If a form is in 'new' mode and if there is a default value configured on a table column, such a value is shown by default.
    There might be situations, where the user should be forced to select a value (e.g. specifying the gender). An unwanted
    default value can be suppressed by specifying an explicit definition on the FormElement field `value`::

      {{<columnName>:RZ}}

    For existing records the shown value is as expected the value of the record. For new records, it's the value `0`,
    which is typically not one of the ENUM / SET values and therefore nothing is selected.


Type: date
^^^^^^^^^^

* Range datetime: '1000-01-01' to '9999-12-31' or '0000-00-00'. (http://dev.mysql.com/doc/refman/5.5/en/datetime.html)
* Optional:

  * *FormElement.parameter.dateFormat*: yyyy-mm-dd | dd.mm.yyyy

Type: datetime
^^^^^^^^^^^^^^

* Range datetime: '1000-01-01 00:00:00' to '9999-12-31 23:59:59' or '0000-00-00 00:00:00'. (http://dev.mysql.com/doc/refman/5.5/en/datetime.html)
* Optional:

  * *FormElement.parameter*:

    * *dateFormat* = yyyy-mm-dd | dd.mm.yyyy
    * *showSeconds* = 0|1 - shows the seconds. Independent if the user specifies seconds, they are displayed '1' or not '0'.
    * *showZero* = 0|1 - For an empty timestamp, With '0' nothing is displayed. With '1' the string '0000-00-00 00:00:00' is displayed.

Type: extra
^^^^^^^^^^^

* The element behaves like, and can be used as, a HTML hidden input element - with the difference & advantage, that the
  element never leaves the server and therefore can't be manipulated by a user.
* The following names are reserved and can't be used to name 'extra' FormElements: 'id', 'type', 'L'.
* The element is not transferred to the the browser.
* The element can be used to define / pre calculate values for a column, which do not already exist as a native *FormElement*.
* The element is build / computed on form load and saved alongside with the SIP parameter of the current form.
* The element is not recalculated during save - it's stored during 'Form Load' inside the current form SIP handle.
* Access the value without specifying any store (default store priority is sufficient).

.. _`input-text`:

Type: text
^^^^^^^^^^

General input for any text.

.. _`field-size`:

* By default, the maximum length of input data is automatically restricted by the underlying database column.
* HTML decides between one line input (=Input text) and multiline input (=Textarea).
* *FormElement.size* = [<width>[,<min height (lines)>[,<max height (pixel)>]]]

  * The parameter is optional and controls the behaviour of the input / textarea element.
  * The `<width>` is counted in 'characters'.

    * But: the *visible* width of an input element is defined by the Bootstrap column width (and *not* the width given
      here). Finally: the value here is meaningless. Nevertheless it has to be given for future compatibility.

  * `<min-height>`:

    * Counted as 'lines'.
    * If not set the height is treated as 1.
    * A `<min-height>` of 1 forces an one line input. Exception: `<max-height>` > 0 enables `auto-grow`.

  * `<max-height>`:

    * Controls the `auto-grow`-Mode.
    * Counted in 'pixel'.
    * If not set it becomes the default of 350 pixels.
    * If > 0, the `auto-grow` mode is activated and the height of the textarea will be dynamically updated
      up to `<max-height>`.
    * If = 0, the `auto-grow` mode is disabled.

* *FormElement.parameter*:

.. _`retype`:

  * *retype* = 1 (optional): Current input element will be rendered twice. The form can only submitted if both elements are equal.

    * *retypeLabel* = <text> (optional): The label of the second element.
    * *retypeNote* = <text> (optional): The note of the second element.

  * *characterCountWrap* = <span class="qfq-cc-style">Count: | </span> (optional).
    Displays a character counter below the input/textarea element.
  * Also check the  :ref:`fe-parameter-attributes` *data-...-error* to customize error messages shown by the validator.
  * *hideZero* = 0|1 (optional): `with hideZero=1` a '0' in the value will be replaced by an empty string.
  * *emptyMeansNull* = [0|1] (optional): with `emptyMeansNull` or `emptyMeansNull=1` a NULL value will be written if
    the value is an empty string
  * *inputType* = number (optional). Typically the HTML tag 'type' will be 'text', 'textarea' or 'number' (detected automatically).
    If necessary, the HTML tag 'type' might be forced to a specific given value.
  * *step* = Step size of the up/down buttons which increase/decrease the number of in the input field. Optional.
    Default 1. Only useful with `inputType=number` (defined explicit via `inputType` or detected automatically).
  * *textareaResize* = 0|1 (optional). Be default = 1 (=on). A textarea element is resizable by the user.

.. _`input-typeahead`:

Type Ahead
""""""""""

Activating `typeahead` functionality offers an instant lookup of data and displaying them to the user, while the user is
typing, a drop-down box offers the results. As datasource the regular SQL connection or a LDAP query can be used.
With every keystroke (starting from the *typeAheadMinLength* characters), the already typed value will be transmitted to
the server, the lookup will be performed and the result, upto *typeAheadLimit* entries, are displayed as a drop-down box.

* *FormElement.parameter*:

  * *typeAheadLimit* = <number>. Max numbers of result records to be shown. Default is 20.
  * *typeAheadMinLength* = <number>. Minimum length to type before the first lookup starts. Default is 2.

Depending of the `typeahead` setup, the given FormElement will contain the displayed `value` or `id` (if an id/value dict is
configured).

Configuration via Form / FormElement
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

All of the `typeAhead*` (except `typeAheadLdap`, `typeAheadInitialSuggestion`) and `ldap*` parameter can be specified either in
*Form.parameter* or in *FormElement.parameter*.

SQL
;;;

* *FormElement.parameter*:

  * *typeAheadSql* = ``SELECT ... AS 'id', ... AS 'value' FROM ... WHERE name LIKE ? OR firstName LIKE ? LIMIT 100``

    * If there is only one column in the SELECT statement, that one will be used and there is no dict (key/value pair).
    * If there is no column `id` or no column `value`, then the first column becomes `id` and the second column becomes `value`.
    * The query will be fired as a 'prepared statement'.
    * The value, typed by the user, will be replaced on all places where a `?` appears.
    * All `?` will be automatically surrounded by '%'. Therefore wildcard search is implemented: `... LIKE '%<?>%' ...`

  * *typeAheadSqlPrefetch* = ``SELECT firstName, ' ', lastName FROM Person WHERE id = ?``

    * If the query returns several results, only the first one is returned and displayed.
    * If the query selects multiple columns, the columns are concatenated.

  * *typeAheadInitialSuggestion* = ``{{!SELECT fr.id AS id, fr.name AS value FROM Fruit AS fr}}``

    * Shows suggestions when the input element gets the focus, before the user starts to type anything.
    * If given, *typeAheadMinLength* will be set to 0.
    * Limit the number of rows via SQL ``... LIMIT ...`` clause.

LDAP
;;;;

See :ref:`LDAP_Typeahead`


.. _`type_ahead_tag`:

Type Ahead Tag
""""""""""""""

Extend a TypeAhead input element to take more than one token (=tag) in the same input element.

This mode supports only *typeAheadSql* (no LDAP).

Usage: A user might choose one or more tags from a typeahead list (to minimize typos and to reuse already given tags).

The user starts typing and for each keypress *typeAheadSql* is searched for all matches. The user selects an element
by clicking on it or by using one of the *typeAheadTagDelimiter* key presses (by default tab or comma). If a tag is
selected, it will be visual separated from the input cursor. Already selected tags can not be edited but removed
(clicking on the x). Further tags can be added.

*typeAheadTag* support two different modes: a) *Tag* , b) *Glue*.

.. _`ta_mode_tag`:

Mode: Tag
;;;;;;;;;

Tags will be loaded and saved as a comma separated list. Maximum length of saved tags is limit by
the size of the column (incl. separator).

Additional arguments needed for *typeAheadTag*:

* *FormElement.parameter*:

  * *typeAheadTag* = [0|1] - Default 0 (=off), existence or =1 switches the mode *typeAheadTag* on.
  * *typeAheadTagDelimiter* = List of ASCII codes to separate tags during input. Default '9,44' (tab and comma).

.. _`ta_mode_glue`:

Mode: Glue
;;;;;;;;;;

For each selected tag a glue record, pointing to the tag, is created.

The *Glue* mode will be activated by setting *FormElement.parameter.typeAheadGlueInsert* with a corresponding SQL statement.

Glue records will be created or deleted, as the user select or deselect tags. Processing of those Glue records will be done
after the primary form record has been written and before any after*-action FormElements will be processed.

*FormElement.name* should **not** point to a column in the form primary table. Instead a free name should be used for the *typeAhead*
FormElement.

The maximum number of tags is not limited - but take care to size the FormElement big enough (*FormElement.maxLength*) to
show all tags.

On *Form load* (to show already assigned tags) a comma separated list has to be given in *FormElement.value*, based on
the previously saved Glue records. The string format is identically to the one used in mode *Tag*.

Extra parameter for mode = *Tag* :

* *FormElement.parameter*:

  * *typeAheadTagInsert* = {{INSERT INTO Tag (....) VALUES (...)}} - Only needed with *typeAheadPedantic=0*.
  * *typeAheadGlueInsert* = {{INSERT INTO glueTag (...) VALUES (...)}}
  * *typeAheadGlueDelete* = {{DELETE FROM glueTag WHERE ...}}

**Example**:

Table *Person* with some records.
Table *Fruit* with a list of fruits.
Table *FruitPerson* with glue records.

Usage: assign favourite fruits to a person. The fruits are the tags, the glue records will assign the fruits to a person.

The form will be open with a person record and has only one FormElement.

* Form.name=personFavouriteFruits
* Form.title=Person Favourite Fruits
* Form.primaryTable = Person

* FormElement[1].name = myFavoriteFruits
* FormElement[1].type = Text
* FormElement[1].value = {{SELECT GROUP_CONCAT( CONCAT(f.id, ':', f.name)) FROM FruitPerson AS fp, Fruit AS f WHERE fp.pId={{id:R}} AND fp.fruitId=f.id ORDER BY f.name}}
* FormElement[1].parameter:

  * typeAheadTag = 1
  * typeAheadSql = SELECT f.id AS 'id', f.name AS 'value' FROM Fruit AS f WHERE f.name LIKE ?
  * typeAheadMinLength = 1
  * typeAheadGlueInsert = {{INSERT INTO FruitPerson (pId, fruitId) VALUES ({{id:R}}, {{tagId:V}} ) }}
  * typeAheadGlueDelete = {{DELETE FROM FruitPerson WHERE pId={{id:R}} AND fruitId={{tagId:V}} }}

Explanation:

* On form load, without any assigned tags (=fruits), *FormElement.value* will be empty.
* The User will assign three fruits: Apple, Banana, Lemon.
* On form save, QFQ does:

  * compares the old tag assigment (empty) with the new tag assigment (3 elements).
  * for each new assigned tag:

    * the *tagId* and *tagValue* will be stored in STORE_VAR (that's the one selected by the user and defined
      via *typeAheadSql*)
    * *typeAheadGlueInsert* will be fired (with the replaced variable *{{tagId:V}}*).

* The user loads the person favourite fruit form again (same user).
* *FormElement.value* will now be: ``1:Apple,3:Banana,10:Lemon``.
* The user removes 'Banana' and adds 'Orange'.
* On form save, QFQ does:

  * compares the old tag assigment (3 elements) with the new tag assigment (also 3 elements, but different).
  * for each new assigned tag:

    * the *tagId* and *tagValue* will be stored in STORE_VAR.
    * *typeAheadGlueInsert* will be fired (with the replaced variable *{{tagId:V}}*).

  * for each removed assigned tag:

    * the *tagId* and *tagValue* will be stored in STORE_VAR.
    * *typeAheadGlueDelete* will be fired (with the replaced variable *{{tagId:V}}*).

.. _`input-editor`:

Type: editor
^^^^^^^^^^^^

* TinyMCE (https://www.tinymce.com, community edition) is used as the QFQ Rich Text Editor.
* The content will be saved as HTML code in the database.

.. important::

    *FormElement.encode*: To save HTML code, incl. HTML tags (bold, table, lists, ...), the **htmspecialchar**
    encoding can't be used, cause the HTML tags loose their meaning. Therefore **single tick** or **none**  is necessary.


* *FormElement.checktype*

  * *all*: The only useful setting for Editor. HTML tags might contain ``% ' " < >`` and so on. This is **dangerous**
    due of potential inserted malicous code! But there is no other option, cause the HTML tags are required.

* All configuration and plugins will be configured via the 'parameter' field. Just prepend the word 'editor-' in front
  of each TinyMCE keyword. Check possible options under:

  * https://www.tinymce.com/docs/configure/,
  * https://www.tinymce.com/docs/plugins/,
  * https://www.tinymce.com/docs/advanced/editor-control-identifiers/#toolbarcontrols

* Bars:

  * Top: *menubar* - by default hidden.
  * Top: *toolbar* - by default visible.
  * Bottom: *statusbar* - by default hidden, exception: *min_height* and *max_height* are given via size parameter.

* The default setting in *FormElement.parameter* is::

    editor-plugins=code link lists searchreplace table textcolor textpattern visualchars
    editor-toolbar=code searchreplace undo redo | styleselect link table | fontselect fontsizeselect | bullist numlist outdent indent | forecolor backcolor bold italic editor-menubar=false
    editor-statusbar=false

* To deactivate the surrouding `<p>` tag, configure in *FormElement.parameter*::

     editor-forced_root_block = false

  This might have impacts on the editor. See https://www.tinymce.com/docs/configure/content-filtering/#forced_root_block

* Set 'extended_valid_elements' to enable HTML tags and their attributes. Example: ::

    editor-extended_valid_elements = span[class|style]

* Set 'editor-content_css' to use a custom CSS to style elements inside the editor. Example: ::

    editor-content_css = fileadmin/custom.css

* *FormElement.size* = <min_height>,<max_height>: in pixels, including top and bottom bars. E.g.: 300,600


Type: annotate
^^^^^^^^^^^^^^

Annotate image or text. Typically the image or text has been uploaded during a previous step. The annotation will be
saved in *FormElement.name* column of the current record. The uploaded file itself will not be modified. The annotations
can be shown in edit (and might be  modified) or in readonly mode.

Two modes are available:

grafic
    A simple grafic editor to paint on top of the image (best by a tablet with pen or grafic tablet). The uploaded image
    is shown in the background. All drawings are saved as a JSON fabric.js data string. Supported file types:
    **png, svg**. PDF files can be easily divided into per page SVG files during upload - see :ref:`split-pdf-upload`

text
    Per code line, annotation(s) can be added. Different users can add individual annotations. A user can only edit the
    own annotations. The annotations are saved as QFQ internal JSON string.


.. note::

    Drawing with fabric.js might produce a lot data. Take care the column type/size is big enough (>=64kB).


Grafic
""""""

An image, specified by ``FormElement.parameter.imageSource={{pathFileName}}``, will be displayed in the background. On
form load, both, the image and an optional already given grafical annotations, will be displayed. The image is SIP
protected and will be loaded on demand.

**Form.parameter**

+-------------------+-----------------------+----------------------------------------------------------------------------------+
| Attribute         | Value                 | Description                                                                      |
+===================+=======================+==================================================================================+
| annotateType      | grafic                | *grafic|text*. Default is *grafic*. Select mode.                                 |
+-------------------+-----------------------+----------------------------------------------------------------------------------+
| imageSource       | <path filename>       | Background image. E.g. `fileadmin/images/scan.png`                               |
+-------------------+-----------------------+----------------------------------------------------------------------------------+
| defaultPenColor   | <rgb hex value>       | Pen default color, after loading the fabric element. Default is '0000FF' (blue). |
+-------------------+----------------------------------------------------------------------------------------------------------+

.. note::

    By using the the `FormElement` `annotate`, the JS code `fabric.min.js` and `qfq.fabric.min.js` has to be included. See :ref:`setup-css-js`.

Code
""""

**Form.parameter**

+--------------------+-----------------------+----------------------------------------------------------------------------------+
| Attribute          | Value                 | Description                                                                      |
+====================+=======================+==================================================================================+
| annotateType       | text                  | *grafic|text*. Default is *grafic*. Select mode.                                 |
+--------------------+-----------------------+----------------------------------------------------------------------------------+
| textSource         | <path filename>       | Text file to annotate.                                                           |
+--------------------+-----------------------+----------------------------------------------------------------------------------+
| annotateUserName   | <john doe>            | Will be shown at annotation line.                                                |
+--------------------+-----------------------+----------------------------------------------------------------------------------+
| annotateUserUid    | <123>                 | Will be shown at annotation line.                                                |
+--------------------+-----------------------+----------------------------------------------------------------------------------+
| annotateUserAvatar | <https://gravatar...> | Will be shown at annotation line.                                                |
+--------------------+-----------------------+----------------------------------------------------------------------------------+
| highlight          | auto                  | off,auto,javascript,qfq,python,matlab                                            |
+--------------------+-----------------------+----------------------------------------------------------------------------------+


Type: imageCut
^^^^^^^^^^^^^^

Uploaded images can be cut or rotate via QFQ (via fabric.js). The modified image is saved under the given pathFileName.

* The 'value' of the `FormElement` has to be a valid PathFileName to an image.
* Valid image file formats are SVG, PNG, JPG, GIF.
* Invalid or missing filenames results to an empty 'imageCut' element.

* *FormElement.parameter*:

  * *resizeWidth* = <empty>|[width in pixel] - the final width of the modified image. If empty (or not given), no change.
  * *keepOriginal* = <empty>|[string] - By default: '.save'. If empty (no string given), don't keep the original. If an
    extension is given and if there is not already a <pathFileName><.extension>, than the original file is to copied to it.


Type: note
^^^^^^^^^^

An FormElement without any 'input' functionality -just to show some text. Use the typical fields 'label', 'value' and
'note' to be displayed in the corresponding three standard columns.

Type: password
^^^^^^^^^^^^^^

* Like a `text` element, but every character is shown as an asterisk.

Often the following form.Parameter arguments are used here:

* retype, retypeLabel, retypeNote - see `retype`_.
* :ref:`extraButtonPassword<extrabuttonpassword_>`.


.. _`input-radio`:

Type: radio
^^^^^^^^^^^

* Radio Buttons will be built from one of three sources:

  1. 'sql1': E.g. *{{!SELECT type AS label FROM Car }}* or *{{!SELECT type AS label, typeNr AS id FROM Car}}* or *{{!SHOW tables}}*.

     * Resultset format 'named': column 'label' and optional a column 'id'.
     * Resultset format 'index':

       * One column in resultset >> first column represents *label*
       * Two or more columns in resultset >> first column represents *id* and second column represents *label*.

  2. *FormElement.parameter*:

     * *itemList* = `<attribute>` E.g.: *itemList=red,blue,orange* or *itemList=1:red,2:blue,3:orange*
     * If ':' or ',' are part of key or value, it needs to escaped by \\ . E.g.: `itemList=1:red\\: (with colon),2:blue\\, (with comma),3:orange`

  3. Definition of the *enum* or *set* field (only labels, ids are not possible).


* *FormElement.maxlength* = `<value>`

  * Applies only to 'plain' radio elements (not the Bootstrap 'buttonClass' from below)
  * *vertical* or *horizontal* alignment:

    * `<value>`: '', 0, 1 - The radios will be aligned *vertical*.
    * `<value>`: >1 - The readios will be aligned *horizontal*, with a linebreak every 'value' elements.


* *FormElement.parameter*:

  * *emptyHide*: Existence of this item hides an entry with an empty string. This is useful for e.g. Enums, which have an empty
    entry, but the empty value should not be selectable.
  * *emptyItemAtStart*: Existence of this item inserts an empty entry at the beginning of the selectlist.
  * *emptyItemAtEnd*: Existence of this item inserts an empty entry at the end of the selectlist.
  * *buttonClass* = <class> - Instead of the plain radio fields, Bootstrap
    `buttons <http://getbootstrap.com/docs/3.4/javascript/#buttons-checkbox-radio>`_. are rendered as `radio` elements. Use
    one of the following `classes <http://getbootstrap.com/docs/3.4/css/#buttons-options>`_:

    * `btn-default` (default, grey),
    * `btn-primary` (blue),
    * `btn-success` (green),
    * `btn-info` (light blue),
    * `btn-warning` (orange),
    * `btn-danger` (red).

    With a given *buttonClass*, all buttons (=radios) are rendered horizontal. A value in *FormElement.maxlength* has no effect.

* *No preselection*:

  * If there is a default configured on a table column, such a value is selected by default. If the user should actively
    choose an option, the 'preselection' can be omitted by specifying an explicit definition on the FormElement field `value`::

      {{<columnName>:RZ}}

    For existing records the shown value is as expected the value of the record. For new records, it's the value `0`,
    which is typically not one of the ENUM values and therefore nothing is selected.

.. _`input-select`:

Type: select
^^^^^^^^^^^^

* Select lists will be built from one of three sources:

  * *FormElement.sql1* = `{{!<SQL Query}}`

    * E.g. *{{!SELECT type AS label FROM Car }}* or *{{!SELECT type AS label, typeNr AS id FROM Car}}* or *{{!SHOW tables}}*.

    * Resultset format 'named': column 'label' and optional a column 'id'.
    * Resultset format 'index':

      * One column in resultset >> first column represents *label*
      * Two or more columns in resultset >> first column represents *id* and second column represents *label*.

  * *FormElement.parameter*:

    * *itemList* = `<attribute>` - E.g.: *itemList=red,blue,orange* or *itemList=1:red,2:blue:3:orange*
    * If ':' or ',' are part of key or value, it needs to escaped by \\ . E.g.: `itemList=1:red\\: (with colon),2:blue\\, (with comma),3:orange`

  * Definition of the *enum* or *set* field (only labels, ids are not possible).

* *FormElement.size* = `<value>`

  * `<value>`: <empty>|0|1: drop-down list.
  * `<value>`: >1: Select field with *size* rows height. Multiple selection of items is possible.

* *FormElement.parameter*:

  * *emptyItemAtStart*: Existence of this item inserts an empty entry at the beginning of the selectlist.
  * *emptyItemAtEnd*: Existence of this item inserts an empty entry at the end of the selectlist.
  * *emptyHide*: Existence of this item hides the empty entry. This is useful for e.g. Enums, which have an empty
    entry and the empty value should not be an option to be selected.
  * *datalist*: Similar to 'typeAhead'. Enables the user to select a predefined option (sql1, itemList) or supply any
    free text. Attention: Safari (and some other) browsers do not support this fully - https://caniuse.com/#search=datalist.

.. _`subrecord-option`:

Type: subrecord
^^^^^^^^^^^^^^^

The *FormElement* type 'subrecord' renders a list of records (so called secondary records), typically to show, edit, delete
or add new records. The list is defined as an SQL query. The number of records shown is not limited. These *FormElement*
will be rendered inside the form as a HTML table.

* *mode / modeSql* = `<type/value>`

  * *show / required*: the regular mode to show the subrecords
  * *readonly*: New / Edit / Delete Buttons are disabled
  * *hidden*: The FormElement is rendered, but hidden with `display='none'`.

* *dynamicUpdate* - not supported at the moment.

* *sql1* = `{{!SQL Query}}`

  * SQL query to select records. E.g.::

      {{!SELECT addr.id AS id, CONCAT(addr.street, addr.streetnumber) AS a, addr.city AS b, addr.zip AS c FROM Address AS addr}}

  * Notice the **exclamation mark** after '{{' - this is necessary to return an array of elements, instead of a single string.
  * Exactly one column **'id'** has to exist; it specifies the primary record for the target form.
    In case the id should not be visible to the user, it has to be named **'_id'**.
  * Column name: *[title=]<title>[|[maxLength=]<number>][|nostrip][|icon][|link][|url][|mailto][|_rowClass][|_rowTooltip]*

    * If the keyword is used, all parameter are position independent.
    * Parameter are separated by '|'.
    * *[title=]<text>*: Title of the column. The keyword 'title=' is optional. Columns with a title starting with '_' won't be rendered.
    * *[maxLength=]<number>*: Max. number of characters displayed per cell. The keyword 'maxLength=' is optional. Default
      maxLength '20'. A value of '0' means no limit. This setting also affects the title of the column.
    * *nostrip*: by default, html tags will be stripped off the cell content before rendering. This protects the table
      layout. 'nostrip' deactivates the cleaning to make pure html possible.
    * *icon*: the cell value contains the name of an icon in *typo3conf/ext/qfq/Resources/Public/icons*. Empty cell values
      will omit an html image tag (=nothing rendered in the cell).
    * *link*: value will be rendered as described under :ref:`column-link`
    * *url*: value will be rendered as a href url.
    * *mailto*: value will be rendered as a href mailto.
    * *_rowClass*

      * The value is a CSS class name(s) which will be rendered in the *<tr class="<_rowClass>">* of the subrecord table.
      * The column itself is not rendered.
      * By using Bootstrap, the following predefined classes are available:

        * Text color: *text-muted|text-primary|text-success|text-info|text-warning|text-danger* (http://getbootstrap.com/docs/3.4/css/#helper-classes)
        * Row background: *active|success|info|warning|danger* (http://getbootstrap.com/docs/3.4/css/#tables-contextual-classes)

    * *_rowTooltip*

      * Defines the title attribute (=tooltip) of a subrecord table row.

    * Examples::

         {{!SELECT id, note1 AS 'Comment', note2 AS 'Comment|50' , note3 AS 'title=Comment|maxLength=100|nostrip', note4 AS '50|Comment',
         'checked.png' AS 'Status|icon', email AS 'mailto', CONCAT(homepage, '|Homepage') AS 'url',
         CONCAT('d|s|F:', pathFileName) AS 'Download|link',
         ELT(status,'info','warning','danger') AS '_rowClass', help AS '_rowTooltip' ...}}

* *FormElement.parameter*

  * *form* = `<form name>` - Target form, e.g. *form=person*
  * *page* = `<T3 page alias or id>` - Target page with detail form. If none specified, use the current page.
  * *extraDeleteForm*: Optional. The per row delete Button will reference the form specified here (for deleting) instead of the default (*form*).
  * *detail* = `<string>` - Mapping of values from

    * a) the primary form,
    * b) the current row,
    * c) any constant or '{{...}}' -

    to the target form (defined via `form=...`).

    * Syntax::

        <source table column name 1|&constant 1>:<target column name 1>[,<source table column name 2|&constant 2>:<target column name 2>][...]

    * Example: *detail=id:personId,rowId:secId,&12:xId,&{{a}}:personId*  (rowId is a column of the current selected row defined by sql1)
    * By default, the given value will overwrite values on the target record. In most situations, this is the wished behaviour.
    * Exceptions of the default behaviour have to be defined on the target form in the corresponding *FormElement* in the
      field *value* by changing the default Store priority definition. E.g. `{{<columnName>:RS0}}` - For existing records,
      the store `R` will provide a value. For new records, store `R` is empty and store S will be searched for a value:
      the value defined in `detail` will be choosen. At last the store '0' is defined as a fallback.
    * *source table column name*: E.g. A person form is opened with person.id=5 (r=5). The definition `detail=id:personId`
      and `form=address` maps person.id to address.personId. On the target record, the column personId becomes '5'.
    * *Constant '&'*: Indicate a 'constant' value. E.g. `&12:xId` or `{{...}}` (all possibilities, incl. further SELECT
      statements) might be used.

  * *subrecordTableClass*: Optional. Default: 'table table-hover qfq-subrecord-table qfq-color-grey-2'. If given, the default will be
    overwritten. Example::

        subrecordTableClass = table table-hover qfq-subrecord-table qfq-table-50

  * Tablesorter in Subrecord::

        subrecordTableClass = table table-hover qfq-subrecord-table tablesorter tablesorter-pager tablesorter-filter

  * *subrecordColumnTitleEdit*: Optional. Will be rendered as the column title for the new/edit column.
  * *subrecordColumnTitleDelete*: Optional. Will be rendered as the column title for the delete column.

**Subrecord DragAndDrop**

Subrecords inherently support drag-and-drop, see also :ref:`drag_and_drop`.
The following parameters can be used in the `parameter` field to customize/activate drag-and-drop:

* *orderInterval*: The order interval to be used, default is 10.
* *dndTable*: The table that contains the records to be ordered.
  If not given, the table name of the form specified via `form=...` is used.
* *orderColumn*: The dedicated order column in the specified dndTable (needs to match a column in the table definition).
  Default is `ord`.

If `dndTable` is a table with a column `orderColumn`, QFQ automatically applies drag-and-drop logic
to the rendered subrecord. It does so by using the subrecord field *sql1*. The `sql1` query should
include a column `id` (or `_id`) and a column `ord` (or `_ord`). E.g.::

  FE.sql1 = {{!SELECT p.id AS _id, p.ord AS _ord, p.name FROM Person WHERE p.email!='' ORDER BY p.ord}}

In case the modified ord value should be shown without reloading the page, add html id `qfq-dnd-ord-id-...`::

  FE.sql1 = {{!SELECT p.id AS _id, p.ord AS _ord, p.name
                      , CONCAT('<span id="qfq-dnd-ord-id-', p.id,'">', p.ord, '</span>') AS 'Ord|nostrip'
                 FROM Person WHERE p.email!='' ORDER BY p.ord}}


.. tip::

    * If you want to deactivate a drag-and-drop that QFQ automatically renders, set the `orderColumn` to a non-existing column.
      E.g., `orderColumn = nonExistingColumn`. This will deactivate drag-and-drop.
    * In order to evaluate the `sql1` query dynamically during a drag-and-drop event, the STORE_RECORD (with the current subrecord)
      is loaded.
    * The stores STORE_RECORD, STORE_SIP and STORE_SYSTEM are supported during a drag-and-drop event and can be used in FE.sql1 query.

      * STORE_SIP: SIP values on form load
      * STORE_RECORD: values of the current record loaded in the form.

    * If the subrecord is rendered with drag-and-drop active, but the order is not affected upon reload, there is
      most likely a problem with evaluating the `sql1` query at runtime.

Type: time
^^^^^^^^^^

* Range time: '00:00:00' to '23:59:59' or '00:00:00'. (http://dev.mysql.com/doc/refman/5.5/en/datetime.html)
* Optional:
* *FormElement.parameter*

  * *showSeconds* = `0|1` - shows the seconds. Independent if the user specifies seconds, they are displayed '1' or not '0'.
  * *showZero* =  `0|1` - For an empty timestamp, With '0' nothing is displayed. With '1' the string '00:00[:00]' is displayed.

.. _`input-upload`:

Type: upload
^^^^^^^^^^^^

An upload element is based on a 'file browse'-button and a 'trash'-button (=delete). Only one of them is shown at a time.
The 'file browse'-button is displayed, if there is no file uploaded already.
The 'trash'-button is displayed, if there is a file uploaded already.

After clicking on the browse button, the user select a file from the local filesystem.
After choosing the file, the upload starts immediately, shown by a turning wheel. When the server received the whole file
and accepts (see below) the file, the 'file browse'-button disappears and the filename is shown, followed by a 'trash'-button.
Either the user is satisfied now or the user can delete the uploaded file (and maybe upload another one).

Until this point, the file is cached on the server but not copied to the `fileDestination`. The user have to save the
current record, either to finalize the upload and/or to delete a previously uploaded file.

The FormElement behaves like a

* *native FormElement* (showing controls/text on the form) as well as an
* *action FormElement* by firing queries and doing some additional actions during form save.

Inside the *Form editor* it's shown as a 'native FormElement'.
During saving the current record, it behaves like an action FormElement
and will be processed after saving the primary record and before any action FormElements are processed.

* *FormElement.value* = `<string>` - By default, the full path of any already uploaded file is shown. To show something
  different, e.g. only the filename, define:

  * ``{{filenameBase:V}}`` (see :ref:`STORE_VARS`)
  * ``{{SELECT SUBSTRING_INDEX( '{{pathFileName:R}}', '/', -1)  }}``

See also :ref:`download Button<downloadButton>` to offer a download of an uploaded file.

FormElement.parameter
"""""""""""""""""""""

* *fileButtonText*: Overwrite default ‘Choose File’
* *capture* = `camera` - On a smartphone, after pressing the 'open file' button, the camera will be opened and a
  choosen picture will be uploaded. Automatically set/overwrite `accept=image/*`.

* *accept* = `<mime type>,image/*,video/*,audio/*,.doc,.docx,.pdf`

  * List of mime types (also known as 'media types'): http://www.iana.org/assignments/media-types/media-types.xhtml
  * If none mime type is specified, 'application/pdf' is set. This forces that always (!) one type is specified.
  * To allow any type, specify ``*`` or ``*/*`` or ``*.*``.
  * One or more media types might be specified, separated by ','.
  * Different browser respect the given definitions in different ways. Typically the 'file choose' dialog offer:

    * the specified mime type (some browers only show 'custom', if more than one mime type is given),
    * the option 'All files' (the user is always free to **try** to upload other file types) - but the server won't accept them,
    * the 'file choose' dialog only offers files of the selected (in the dialog) type.

  * If for a specific file type is no mime type available, the definition of file extension(s) is possible. This is **less