Form.rst



Form

General

Important
Primary key: QFQ expect that each table, which will be loaded into a form, contains a primary key called id.
That one should be autoincrement.  It's not necessary to create a FormElement id in a form.


Forms will be created by using the Form Editor on the Typo3 frontend (HTML form).


The Form editor itself consist of two predefined QFQ forms: form and formElement - these forms are regular updated
during installation of newer QFQ versions.


Every form consist of a) a Form record and b) multiple FormElement records.


A form is assigned to a  table. Such a table is called the primary table for this form.


Forms can roughly categorized into:


Simple form: the form acts on one record, stored in one table.
The form will create necessary SQL commands for insert, update and delete (only primary record) automatically.


Advanced form: the form acts on multiple records, stored in more than one table.
Fields of the primary table acts like a simple form, all other fields have to be specified with action/afterSave records.


Multi form: (multi-form) the form acts simultaneously on more than one record. All records use the same FormElements.
The FormElements are defined as a regular simple / or advanced form, plus an SQL Query, which selects and
iterates over all records. Those records will be loaded at the same time.


Delete form: any form can be used as a form to :ref:`delete-record`.


Form mode: The parameter 'r' (given via URL or via SIP) decide if the form is in mode:


New:

Missing parameter 'r' or 'r=0'
On form load, no record is displayed.
Saving the form creates a new primary record.
E.g.: http://example.com/index.php?id=home&form=Person  or http://example.com/index.php?id=home&form=Person&r=0


Edit:

Parameter 'r>0'
On form load, the specified record (<tablename>.id= <r>) will be loaded and displayed.
Saving the form will update the existing record.
E.g.: http://example.com/index.php?id=home&form=Person&r=123


Providing additional parameter:
Often, it is necessary to store additional, for the user not visible, parameter in a record. See :ref:`form-magic`.


Display a form:

Create a QFQ tt_content record on a Typo 3 page.
Inside the QFQ record: form  = <formname>. E.g.:
Static: form = Person

Dynamic 1: form  = {{form:SE}}  (the left form is a keyword for QFQ, the right form is a variable name)
Dynamic 2: form  = {{SELECT f.name FROM Form AS f WHERE f.id=...}}  (the left form is a keyword for QFQ, the right form is a variable name)


With the Dynamic option, it's easily possible to use one Typo3 page and display different forms on that specific
page.


If a form is edited using the JSON form editor then a backup of the previous version is saved. See :ref:`formAsFile`.


Form process order
Depending on form load / save or record delete, different tasks are performed. Processing is divided into:

Native FormElements like: input, select list, checkbox, radio, ....

upload elements are categorized as native FormElement, but will be processed later.

pill, fieldset and subrecord elements are only processed during form load, they do not impact save or delete.


Action FormElement like before..., after..., sendmail ...

Each FormElement has an order.
Native FormElements which 'name':

corresponds to a column in the form primary table: are grouped together in one insert or update query.
do not correspond to a column in the primary table: needs an explicit defined Action FormElement to be handled.

FormElement processing order:


Record locking
Support for record locking is given with mode:


exclusive: user can't force a write.
Including a timeout (default 15 mins recordLockTimeoutSeconds in :ref:`configuration`) for maximum lock time.


advisory: user is only warned, but allowed to overwrite.

none: no bookkeeping about locks.

Details:

For 'new' records (r=0) there is no locking at all.
The record locking protection is based on the tablename and the record id. Different Forms, with the same primary table,
will be protected by record locking.
Action-FormElements updating non primary table records are not
protected by 'record locking': the QFQ record locking is NOT 100%.
The 'record locking' mode will be specified per Form. If there are multiple Forms with different modes, and there is
already a lock for a tablename / record id pair, the most restrictive will be applied.
A user opens a form: starting with the first change of content, a record lock will be acquired in the background. If
the lock is denied (e.g. another user already owns a lock on the record) an alert is shown. This means: the lock timeout
counts from the first change, not from the last modification on the form.
If a timeout expires, the lock becomes invalid. During the next change in a form, the lock is acquired again.
A lock is assigned to a record of a table. Multiple forms, with the same primary table, uses the same lock for a given record.
If a user tries to delete a record and another user already owns a lock on that record, the delete action is denied.
If there are different locking modes in multiple forms, the most restricting mode applies for the current lock.
If the same user opens the same recording in different tabs or browsers, the user has the possibility to skip a lock.


Exclusive
An existing lock on a record forbids any write action on that record. Exception: locks owned by the same user might be overwritten.

Advisory
An existing lock on a record informs the user that another user is currently working on that record. Nevertheless,
writing is allowed.

None
No locking at all.

Comment- and space-character
The following applies to the fields Form.parameter and FormElement.parameter:

Lines will be trimmed - leading and trailing spaces will be removed.
If a leading and/or trailing space is needed, escape it: \ hello world \ > ' hello world '.
Lines starting with a '#' are treated as a comment and will not be parsed. Such lines are treated as 'empty lines'.
The comment sign can be escaped with \ .


Form Settings


Name
Description


Name
Unique and speaking name of the Form. Form will be identified by this name. Use only '[a-zA-Z0-9._+-]'. form-name


Title
Title, shown on/above the form. form-title


Note
Personal editor notes. form-note


Table
Primary table of the form. form-tablename


Primary Key
Primary key of the indicated table. Only needed if != 'id'. form-primary-key


Required Parameter NEW
Name of required SIP parameter to create a new record (r=0), separated by comma. '#' as comment delimiter. See :ref:`form-requiredParameter`


Required Parameter EDIT
Name of required SIP parameter to edit an existing record (r>0), separated by comma. '#' as comment delimiter. See :ref:`form-requiredParameter`


Permit New
'sip, logged_in, logged_out, always, never' (Default: sip): See :ref:`form-permitNewEdit`


Permit Edit
'sip, logged_in, logged_out, always, never' (Default: sip): See :ref:`form-permitNewEdit`


Permit REST
See :ref:`restApi`


Escape Type Default
See :ref:`variable-escape`.


Show button
'new, delete, close, save' (Default: 'new,delete,close,save'): Shown named buttons in the upper right corner of the form.
See :ref:`form-showButton`


Forward Mode
'auto | close | no | url | url-skip-history | url-sip | url-sip-skip-history' (Default: auto): See :ref:`form-forward`.


Forward (Mode) Page


URL / Typo3 page slug or b) Forward Mode (via '{{...}}') or combination of a) & b). See :ref:`form-forward`.


labelAlign
Label align (default/left/center/right)/ Default: 'default' (defined by Config). form-label-align


Parameter
Misc additional parameters. See :ref:`form-parameter`.


BS Label Columns
The bootstrap grid system is based on 12 columns. The sum of bsLabelColumns,
bsInputColumns and bsNoteColumns should be 12. These values here are the base values
for all FormElements. Exceptions per FormElement can be specified per FormElement.
Default: label=col-md-3, input=col-md-6, note=col-md-3. See :ref:`form-layout`.


BS Input Columns


BS Note Columns


multiMode
NOT IMPLEMENTED - 'none, horizontal, vertical' (Default 'none')


multiSql
NOT IMPLEMENTED - Optional. SQL Query which selects all records to edit.


multiDetailForm
NOT IMPLEMENTED - Optional. Form to open, if a record is selected to edit (double click on record line)


multiDetailFormParameter
NOT IMPLEMENTED - Optional. Translated Parameter submitted to detail form (like subrecord parameter)


multiFormWrap
By default (if empty) wraps the form in a HTML table. Alternative is to use CSS grid. See :ref:`multi-form-grid`.


multiFormCellWrap
By default (if empty) wraps each input in <td>. If 'multiFormWrap' is given but multiFormCellWrap is empty, than the default is <div>.
See :ref:`multi-form-grid`.


permitNew & permitEdit
Depending on r, the following access permission will be taken:


r=0 - permitNew

r>0 - permitEdit