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. .. -*- coding: utf-8 -*- with BOM.
...@@ -1124,12 +1127,23 @@ Class: Action ...@@ -1124,12 +1127,23 @@ Class: Action
Type: before... | after... Type: before... | after...
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
These type of 'action' formelements will be used to implement data validation or creating/updating additional records.
Types: Types:
* beforeLoad * beforeLoad
* good to grant access permission.
* afterLoad * afterLoad
* beforeSave * beforeSave
* good to prohibit creating of duplicate records.
* afterSave * afterSave
* good to create & update additional records.
* beforeInsert * beforeInsert
* afterInsert * afterInsert
* beforeUpdate * beforeUpdate
...@@ -1137,68 +1151,64 @@ Types: ...@@ -1137,68 +1151,64 @@ Types:
* beforeDelete * beforeDelete
* afterDelete * afterDelete
* Check data Validate
''''''''
Perform checks by fireing a SQL query and expecting a predefined number of selected records. Depending on the Perform checks by fireing a SQL query and expecting a predefined number of selected records.
'action'-type, the check is perform on form load or form save.
* OK: the expected number of records has been selected. Continue processing the next FormElement. * OK: the `expectRecords` 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 * Fail: the `expectRecords` number of records has not been selected (less or more): Display the error message
current form load or form save. `messageFail`and abort the whole (!) current form load or save.
FormElement.’‘’parameter’‘’: FormElement.’‘’parameter’‘’:
* ‘’‘requiredList‘’‘ - List of `native`-FormElements: only if all of those elements are filled, the current * `requiredList` - List of `native`-formelement names: only if all of those elements are filled (!=0 and !=''), the *current*
`action`-FormElement will be processed. `action`-FormElement will be processed. This will enable or disable the check, based on the user input! If no
* ‘’‘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}} }}` `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. * 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. * 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). * 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. * 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. `action`-FormElement will be processed.
* ‘’‘slaveId‘’‘: * `slaveId`:
* Auto fill: name the action `action`-FormElement equal to an existing column (table from the current form definition).
* If `slaveId` does not exist or is empty (e.g. a defined query has an empty result): `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 there is no such named columnname, set `slaveId=0`.
* If not: treat it as '0'.
* A value of `0` means the following `sqlInsert` will be fired. * Explicit definition: `slaveId=123` or `slaveId={{SELECT id ...}}`
* 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`.
* ‘’‘sqlUpdate‘’‘ - query. E.g.: `sqlUpdate={{UPDATE Address SET street = '{{street:F:all}}' WHERE id={{slaveId:V}} LIMIT 1}}` * `sqlInsert`: fired if `slaveId=0` or `slaveId=''`.
* ‘’‘sqlInsert‘’‘ - query. E.g.: `sqlInsert={{INSERT INTO Address (pId, street) VALUES ( {{id:R}}, '{{street:F:all}}' WHERE id={{slaveId:V}} }}` * `sqlUpdate`: fired if `slaveId>0`:
* `sqlDelete`: always fired (after sqlInsert or sqlUpdate) - the definition, when this query is fired, might change in
* ‘’‘sqlDelete‘’‘ - query: E.g.: `sqlDelete={{DELETE FROM Address WHERE id={{slaveId:V}} AND ''='{{city:F:allbut:s}}' LIMIT 1}}` the future.
* 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
''''''''''''''''
Complex forms often needs to create additional records or have to update existing records, depending on the master record Note:
(existing or newly created). With the help of the following such situations are solved.
* '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>' * If the `action`-FormElement name exist as a column in the master record: Update that column *automatically* with the
* explicitly define the 'slaveId' via {{SELECT ...}} or any other variable or constant. 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) 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