. 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 `` 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* = ,: 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 | | Background image. E.g. `fileadmin/images/scan.png` |
+-------------------+-----------------------+----------------------------------------------------------------------------------+
| defaultPenColor | | 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 | | Text file to annotate. |
+--------------------+-----------------------+----------------------------------------------------------------------------------+
| annotateUserName | | Will be shown at annotation line. |
+--------------------+-----------------------+----------------------------------------------------------------------------------+
| annotateUserUid | <123> | Will be shown at annotation line. |
+--------------------+-----------------------+----------------------------------------------------------------------------------+
| annotateUserAvatar | | 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* = |[width in pixel] - the final width of the modified image. If empty (or not given), no change.
* *keepOriginal* = |[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 <.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`.
.. _`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* = `` 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* = ``
* Applies only to 'plain' radio elements (not the Bootstrap 'buttonClass' from below)
* *vertical* or *horizontal* alignment:
* ``: '', 0, 1 - The radios will be aligned *vertical*.
* ``: >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* = - Instead of the plain radio fields, Bootstrap
`buttons `_. are rendered as `radio` elements. Use
one of the following `classes `_:
* `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`::
{{: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* = `{{!> first column represents *label*
* Two or more columns in resultset >> first column represents *id* and second column represents *label*.
* *FormElement.parameter*:
* *itemList* = `` - 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* = ``
* ``: |0|1: drop-down list.
* ``: >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* = ``
* *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=][|[maxLength=]][|nostrip][|icon][|link][|url][|mailto][|_rowClass][|_rowTooltip]*
* If the keyword is used, all parameter are position independent.
* Parameter are separated by '|'.
* *[title=]*: Title of the column. The keyword 'title=' is optional. Columns with a title starting with '_' won't be rendered.
* *[maxLength=]*: 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 ** 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* = `