Form.rst

.. ==================================================
.. ==================================================
.. ==================================================
.. Header hierarchy
.. ==
..  --
..   ^^
..    ""
..     ;;
..      ,,
..
.. --------------------------------------------used to the update the records specified ------
.. Best Practice T3 reST: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html
..             Reference: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/Index.html
.. Italic *italic*
.. Bold **bold**
.. Code ``text``
.. External Links: `Bootstrap <http://getbootstrap.com/>`_
.. Internal Link: :ref:`downloadButton` (default url text) or :ref:`download Button<downloadButton>` (explicit url text)
.. Add Images:    .. image:: ../Images/a4.jpg
..
..
.. Admonitions
..           .. note::   .. important::     .. tip::     .. warning::
.. Color:   (blue)       (orange)           (green)      (red)
..
.. Definition:
.. some text becomes strong (only one line)
..      description has to indented

.. -*- coding: utf-8 -*- with BOM.

.. include:: Includes.txt


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:

.. image:: Images/FormProcess.png

.. _record_locking:

Record locking
--------------

Forms and 'record delete'-function support basic record locking. 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.
By default the record lock mode is 'exclusive' and the default timeout is 15 minutes. Both can be configured per form.
The general timeout can also be configured in :ref:`configuration` (will be copied to the form during creating the form).

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 `Form` acts on further records (e.g. via FE action), those further records are not protected by this basic record locking.

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.

Exclusive
^^^^^^^^^

An existing lock on a record forbids any write action on that record.

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-space-character:

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-main:

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`                                                          |