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.

• Forms are synced between the database and form files. 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

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.