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

UsersManual/index.rst: Rewrite of 'action'-FormElement definition.

parent b9f7797d
.. ==================================================
.. FOR YOUR INFORMATION
.. Header hierachy
.. ==
.. --
.. ^^
.. ''
.. --
.. ^^
.. ''
.. ;;
.. ,,
..
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
......@@ -1124,12 +1127,23 @@ Class: Action
Type: before... | after...
^^^^^^^^^^^^^^^^^^^^^^^^^^
These type of 'action' formelements will be used to implement data validation or creating/updating additional records.
Types:
* beforeLoad
* good to grant access permission.
* afterLoad
* beforeSave
* good to prohibit creating of duplicate records.
* afterSave
* good to create & update additional records.
* beforeInsert
* afterInsert
* beforeUpdate
......@@ -1137,68 +1151,64 @@ Types:
* beforeDelete
* afterDelete
* Check data
Validate
''''''''
Perform checks by fireing a SQL query and expecting a predefined number of selected records. Depending on the
'action'-type, the check is perform on form load or form save.
Perform checks by fireing a SQL query and expecting a predefined number of selected records.
* OK: the expected number of records has been selected. Continue processing the next FormElement.
* Fail: the expected number of records has not been selected (less or more): Display an error message and abort the
current form load or form save.
* OK: the `expectRecords` number of records has been selected. Continue processing the next FormElement.
* Fail: the `expectRecords` number of records has not been selected (less or more): Display the error message
`messageFail`and abort the whole (!) current form load or save.
FormElement.’‘’parameter’‘’:
* ‘’‘requiredList‘’‘ - List of `native`-FormElements: only if all of those elements are filled, the current
`action`-FormElement will be processed.
* ‘’‘sqlValidate’‘’ - query. E.g.: `sqlValidate={{!SELECT id FROM Person AS p WHERE p.name LIKE {{name:F:all}} AND p.firstname LIKE {{firstname:F:all}} }}`
* `requiredList` - List of `native`-formelement names: only if all of those elements are filled (!=0 and !=''), the *current*
`action`-FormElement will be processed. This will enable or disable the check, based on the user input! If no
`native`-formelement names are given, the specified check will always be performed.
* `sqlValidate` - validation query. E.g.: `sqlValidate={{!SELECT id FROM Person AS p WHERE p.name LIKE {{name:F:all}} AND p.firstname LIKE {{firstname:F:all}} }}`
* Pay attention to '{{!...' after the equal sign.
* ‘’‘expectRecords‘’‘ - number of records. E.g.: `expectRecords=0` or `expectRecords=0,1` or `expectRecords={{SELECT COUNT(id) FROM Person}}`
* `expectRecords` - number of expected records.
* `expectRecords=0` or `expectRecords=0,1` or `expectRecords={{SELECT COUNT(id) FROM Person}}`
* Separate multiple valid record numbers by ','. If at least one of those matches, the check will pass successfully.
* ‘’‘messageFail‘’‘ - Message to show. E.g.: `messageFail=There is already a person called {{firstname:F:all}} {{name:F:all}}`
* Insert / Update / Delete records
* `messageFail` - Message to show. E.g.: `messageFail=There is already a person called {{firstname:F:all}} {{name:F:all}}`
sqlInsert / sqlUpdate / sqlDelete
'''''''''''''''''''''''''''''''''
* Save values of a form to different record(s), optionally on different table(s).
* Typically usefull on 'afterSave' - be carefull when using it earlier, e.g. beforeLoad.
FormElement.’‘’parameter’‘’:
FormElement.’‘’parameter’‘’:
* ‘’‘requiredList‘’‘ - List of `native`-FormElements: only if all of those elements are filled, the current
* `requiredList` - List of `native`-FormElements: only if all of those elements are filled, the current
`action`-FormElement will be processed.
* ‘’‘slaveId‘’‘:
* If `slaveId` does not exist or is empty (e.g. a defined query has an empty result):
* `slaveId`:
* 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.
* If there is a primary table column, with the same name as the current `action`-FormElement: take the value from that column as `slaveId`.
* If not: treat it as '0'.
* If there is no such named columnname, set `slaveId=0`.
* A value of `0` means the following `sqlInsert` will be fired.
* A value > `0` means the following `sqlUpdate` will be fired and the `slaveId` specifies which one.
* Access the `slaveId` by using the variable `{{slaveId:V}}` inside of `sqlUpdate`, `sqlInsert` or `sqlDelete`.
* Explicit definition: `slaveId=123` or `slaveId={{SELECT id ...}}`
* ‘’‘sqlUpdate‘’‘ - query. E.g.: `sqlUpdate={{UPDATE Address SET street = '{{street:F:all}}' WHERE id={{slaveId:V}} LIMIT 1}}`
* ‘’‘sqlInsert‘’‘ - query. E.g.: `sqlInsert={{INSERT INTO Address (pId, street) VALUES ( {{id:R}}, '{{street:F:all}}' WHERE id={{slaveId:V}} }}`
* ‘’‘sqlDelete‘’‘ - query: E.g.: `sqlDelete={{DELETE FROM Address WHERE id={{slaveId:V}} AND ''='{{city:F:allbut:s}}' LIMIT 1}}`
* If the `action`-FormElement name exist as a column in the master record: Update that column with the recent slaveId
(after an INSERT the last_insert_id() acts as the new `slaveId`).
Detailed concept
''''''''''''''''
* `sqlInsert`: fired if `slaveId=0` or `slaveId=''`.
* `sqlUpdate`: fired if `slaveId>0`:
* `sqlDelete`: always fired (after sqlInsert or sqlUpdate) - the definition, when this query is fired, might change in
the future.
Complex forms often needs to create additional records or have to update existing records, depending on the master record
(existing or newly created). With the help of the following such situations are solved.
Note:
* 'slaveId'
* `{{slaveId:V}}` can be used in any query as the current slaveId. It's *important* to Specify Store V!
* name the action formelement equal to the real columnname. {{slaveId}} will represent the content of 'master.<name of action formelement>'
* explicitly define the 'slaveId' via {{SELECT ...}} or any other variable or constant.
* 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() acts as the new `slaveId`).
* 'sqlInsert', 'sqlUpdate', 'sqlDelete'
Example
'''''''
Situation 1: master.x_id=slave.id (1:1)
......
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