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.