Commit edbe0a7e authored by Carsten  Rose's avatar Carsten Rose
Browse files

Rename subtitle of Form.parameter and FormElement.parameter.

parent 4bdd3313
Pipeline #4976 passed with stages
in 3 minutes and 50 seconds
......@@ -39,9 +39,15 @@ 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 often updated
during the installation of new QFQ versions.
* 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:
......@@ -913,8 +919,8 @@ Fields:
.. _`field-value`:
FE: Value
^^^^^^^^^
FormElement.value
^^^^^^^^^^^^^^^^^
By default this field is empty: QFQ will fill it with the corresponding existing column value on form load.
For a customized default value define: ::
......@@ -930,8 +936,8 @@ Report syntax can also be used, see :ref:`report-notation`.
.. _`report-notation`:
FE: 'Report' notation
^^^^^^^^^^^^^^^^^^^^^
FormElement: 'Report' notation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The FE fields 'value' and 'note' understand the :ref:`Report` syntax. Nested SQL queries as well as links with SIP encoding
are possible. To distinguish between 'Form' and 'Report' syntax, the first line has to be `#!report`::
......@@ -2222,8 +2228,8 @@ One usecase why to split an upload: annotate individual pages by using the `Form
Class: Action
-------------
Type: before... | after...
^^^^^^^^^^^^^^^^^^^^^^^^^^
FormElement.type: before... | after...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These type of 'action' *FormElements* will be used to implement data validation or creating/updating additional records.
......@@ -2243,8 +2249,8 @@ Types:
.. _sqlValidate:
Parameter: sqlValidate
""""""""""""""""""""""
FormElement.parameter: sqlValidate
""""""""""""""""""""""""""""""""""
Perform checks by firing an SQL query and expecting a predefined number of selected records.
......@@ -2269,60 +2275,63 @@ Parameter: sqlValidate
.. _slave-id:
Parameter: slaveId
""""""""""""""""""
FormElement.parameter: slaveId
""""""""""""""""""""""""""""""
FormElement.parameter
;;;;;;;;;;;;;;;;;;;;;
Most of the slaveId concept is part of sqlInsert / sqlUpdate - see below.
* *slaveId* = `<id>`:
.. note::
* Auto fill: name the action `action`-*FormElement* equal to an existing column (table from the current form definition).
*slaveId* will be automatically filled with the value of the named column.
* *slaveId*: 0 (default) or any integer which references a record.
* Set *slaveId* explicit or by query: ``slaveId = 123`` or ``slaveId = {{SELECT id ...}}``
* *fillStoreVar* is fired first, than *slaveId*. Don't use ``{{slaveId:V}}`` in *fillStoreVar*.
* To set *slaveId*, a value from STORE_VARS can be used: ``slaveId={{someId:V}}``.
* ``{{slaveId:V}}`` can be used in any query of the current *FormElement* (but not *fillStoreVar*).
* If the *FormElement* name is equal to a column of the primary table: QFQ updates the current loaded primary table
record with the latest *slaveId*.
* If there is no such named column name, set *slaveId* = `0`.
.. important::
* Explicit definition: *slaveId* = `123` or *slaveId* = `{{SELECT id ...}}`
After an INSERT (= *sqlInsert*) the `last_insert_id()` is copied to *{{slaveId:V}}* automatically.
Note:
FormElement.parameter: sqlBefore / sqlInsert / sqlUpdate / sqlDelete / sqlAfter
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
* `{{slaveId:V}}` can be used in any query of the current *FormElement*.
* If the `action`-*FormElement* name exist as a column in the master record: Update that column *automatically* with the
recent slaveId
* After an INSERT the `last_insert_id()` becomes the *{{slaveId:V}}*.
* `fillStoreVar` is fired first, than `slaveId`.
* If `slaveId` is known in `fillStoreVar`, set: `slaveId={{someId:V}}`.
.. tip::
* Flexible way to update record(s), even on different table(s).
* Often used by *FormElement.type=afterSave* or similar.
.. note::
Parameter: sqlBefore / sqlInsert / sqlUpdate / sqlDelete / sqlAfter
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Form.parameter *sqlBefore* / *sqlAfter* is independent of Form.type *beforeLoad|Save|Insert|Update*.
* Save values of a form to different record(s), optionally on different table(s).
* Typically useful on 'afterSave' - be careful when using it earlier, e.g. beforeLoad.
All of the following attributes are optional.
FormElement.parameter
;;;;;;;;;;;;;;;;;;;;;
* *requiredList = [<fe.name>,]* - List of `native`-*FormElement* names.
* *requiredList* = `<fe.name[s]>` - List of `native`-*FormElement*: only if all of those elements are filled, the current
`action`-*FormElement* will be processed.
* Simplifies to completely enable or disable the current FormElement.
* If empty: process the current FormElement. *This the typical situation*.
* If not empty, all named FormElements will be checked: if all of them are filled, the current
*FormElement* will be processed else not.
* Note: The *requiredList* is independent of *FormElement.mode=required*.
* *sqlBefore* = `{{<query>}}` - always fired (before any *sqlInsert*, *sqlUpdate*, ..)
* *sqlInsert* = `{{<query>}}` - fired if *slaveId* == `0` or *slaveId* == `''`.
* *sqlUpdate* = `{{<query>}}` - fired if *slaveId* > `0`.
* *sqlDelete* = `{{<query>}}` - fired if *slaveId* > `0`, after *sqlInsert* or *sqlUpdate*. Be careful not to delete filled records!
Always add a check, if values given, not to delete the record! *sqlHonorFormElements* helps to skip such checks.
* *sqlAfter* = `{{<query>}}` - always fired (after *sqlInsert*, *sqlUpdate* or *sqlDelete*).
* *sqlHonorFormElements* = `<fe.name[s]>` list of *FormElement* names (this parameter is optional).
* *sqlBefore = {{<query>}}* - always fired (before any *sqlInsert*, *sqlUpdate*, ..)
* *sqlInsert = {{<query>}}* - fired if *slaveId == 0* or *slaveId == ''*.
* *sqlUpdate = {{<query>}}* - fired if *slaveId > 0*.
* *sqlDelete = {{<query>}}* - fired if *slaveId > 0*, after *sqlInsert* or *sqlUpdate*. Be careful not to delete
filled records! Look for *sqlHonorFormElements* to simplify checks.
* *sqlAfter = {{<query>}}* - always fired (after *sqlInsert*, *sqlUpdate* or *sqlDelete*).
* *sqlHonorFormElements = [<fe.name>,]* list of *FormElement* names.
* If one of the named *FormElements* is not empty:
* If one of the named *FormElements* is given:
* fire *sqlInsert* if *slaveId* == `0`,
* fire *sqlUpdate* if *slaveId* > `0`
* fire *sqlInsert* if *slaveId == 0*
* fire *sqlUpdate* if *slaveId* > 0*
* If all of the named *FormElements* are empty:
* fire *sqlDelete* if *slaveId* > `0`
* fire *sqlDelete* if *slaveId > 0*
Example
......@@ -2459,14 +2468,18 @@ See also :ref:`copy-form`.
Form Magic
----------
* Read the following carefully to understand and use QFQ form functionality.
* Check also the :ref:`Form process order<form-process-order>`.
Parameter
^^^^^^^^^
* Table column `id`: QFQ expect that each table, which will be loaded in a form, contains an autoincrement column of name `id`.
It's not necessary to create a FormElement `id` in a form - but it won't disturb.
.. important::
SIP parameter equal to a primary table column name.
* Parameter (one or more) in the SIP url, which exist as a column in the form table (SIP parameter name is equal to a table column name),
will be automatically saved in the record. This acts as 'hidden magic'.
Parameter (one or more) in the SIP url, which *exist* as a column in the form table (SIP parameter name is equal to a
table column name), will be automatically saved in the record.
Example: A slave record (e.g. an address of a person) has to be assigned to a master record (a person). Just give the
`pId` in the link who calls the address form. The following creates a 'new' button for an address for all persons, and
......@@ -2477,17 +2490,37 @@ Parameter
Such parameter, which the form expects to be in the SIP url, should be specified in Form.permitNew and/or Form.permitEdit.
It's only a check for the webmaster, not to forgot a parameter in a SIP url.
* FormElement.type = subrecord
.. note::
FormElement.type = subrecord
Subrecord's will automatically create `new`, `edit` and `delete` links. To inject parameter in those automatically created
links, use `FormElement.parameter.detail` . See :ref:`subrecord-option`.
.. note::
FormElement.type = extra
If a table column should be saved with a specific value, and the value should not be shown to the user, the FE.type='extra'
will do the job. The value could be static or calculated on the fly. Often it's easier to specify such a parameter/value
in the SIP url, but if the form is called from multiple places, an `extra` element is more suitable.
In traditional web applications HTML input fields of type hidden are often used for this. Those can be tempered by
an attacker. It's much safer to use
.. note::
slaveId concept
Subrecord's will automatically create `new`, `edit` and `delete` links. To inject parameter in those automatically created
links, use `FormElement.parameter.detail` . See :ref:`subrecord-option`.
For each *native* and *action* FormElement a few custom SQL command can be fired (*sqlBefore, sqlAfter, sqlInsert,
sqlUpdate, sqlDelete*). To assist the application developer the slaveId concept automatically checks if a
* *sqlInsert* or *sqlUpdate* has to be fired
* or even a *sqlDelete*.
* automatically update the named column.
* FormElement.type = extra
For details check :ref:slave-id.
If a table column should be saved with a specific value, and the value should not be shown to the user, the FE.type='extra'
will do the job. The value could be static or calculated on the fly. Often it's easier to specify such a parameter/value
in the SIP url, but if the form is called from multiple places, an `extra` element is more suitable.
Variables
^^^^^^^^^
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment