Component dbform
Description
A database record form edits a single record from a database relation.
Usually the form starts up empty and it does not have a current row.
Then a new record can be inserted or an existing record can be searched
for by entering some values. After a successful search the row found
becomes the current row. It can then be modified or deleted.
Format
< dbform ... > ... < /dbform >
Details
Component must not be used inside a form.| Include File: | dbform.hei |
| Session Mode: | create |
Properties
| Property | Kind | Description |
| Oid | ||
| Relation | Database relation. | |
| Key | Key field names, separated by comma. If you leave this empty,
the | |
| Keychange | Key field change model. Value "update" allows updating key fields. Value "copy" is like "update", but the modify button copies the record if key fields were changed. Value "none" disallows changing key fields. | |
| State | Use to disable form fields. | |
| Method | HTTP method to submit the form data set. Value "post" should be used when form processing causes side effects, e.g. modifies a database, and if the form contains fieldfileupload. | |
| Enctype | Content type for method "post". Use "multipart/form-data" with fieldfileupload. | |
| Successuri | Continue with this URI after the form has been submitted successfully. | |
| Fragment | Section name (The # part of the action URI without the #). No effect on successuri. | |
| Passwordfield | for password protection: password field name | |
| Msgallowed | Accepted messages. The enabled functions can be activated from the browser. |
Attributes
| Name | Description |
| ff | is an object that contains the form fields that are currently displayed. |
| row | is an object that contains the current row. It can be null in case there is no current row. |
| state | is the state "enabled" or "disabled" |
Messages
| Kind | Description |
| empty | Displays an empty form. Any field values included in the message are takes as default values of the form. |
| display | Displays a database record in a disabled form. Requires a key of the record as parameter. The key must consist of one or more fields. All field names provided must be legal column names found in the database. |
| modify | Displays a database record in an enabled form. Parameters are the same as with display. |
| searchdisplay | Works like display but performs an automatic query search. The key fields of the messages are compared with the fields of the same name contained in the database. Default comparison operator is a substring match (like "%...%"). Other operators can be selected using dbfieldoperator in a search form. |
| searchmodify | Works like modify but performs an automatic query search. The key fields of the messages are compared with the fields of the same name contained in the database. Default comparison operator is a substring match (like "%...%"). Other operators can be selected using dbfieldoperator in a search form. |
| copy | Displays a copy of a database record in an enabled form. Parameters are the same as with modify. |
Superclass
The component inherits Attributes, Methods, and Hookmethods from the following superclasses:
panel The ff attribute and the access functions panelobj(n) and panelfield(n) are important.
Hooks
CheckRecord () Is called before a record is stored into the database, either by insert or by update. The method must check the data entered for consistency. It must return an object containing all the fields that should be stored in the database, if everything was ok or deliver an error message as string otherwise. If an error message is issued the database is left unchanged.
this.ff contains the form data entered by the user. this.row contains in case of an update the current record in the database otherwise null. In simple cases CheckRecord should just return this.ff, after doing all necessary consistency checks. It can also return a copy of this.ff and add or remove fields to control the data written to the database. A common usage is to automatically calculate key fields. this.ff can also be changed directly, however these changes become visible in the form in case of an error.
CheckDelete () is called before a record is deleted from the database. The method must check if the record may be deleted. It must return null, if everything was ok or an error message otherwise. If an error message is issued the database is left unchanged.
this.ff contains the form data entered by the user which is normally irrelevant in case of a delete. this.row contains the current record in the database in case of an update, otherwise null.
CheckSelect (row) is called before a record becomes the current record of the form. row contains the record just read. The method can return an error message (which leaves the current row unchaged) or null.
get_row (row) is called after reading a record into this.row. This happens whenever the form is asked to display a new record and after insert and update operations. The purpose is to prepare the row fields for display. Result of get_row is a tuple that later becomes this.ff. As default get_row returns copy(row).
wrapInsert () is wrapped around the insert SQL statement. By default it just contains defbody. Arbitratry code can be inserted before or after the defbody to be executed before or after the SQL statement.
wrapUpdate () is wrapped around the update SQL statement. By default it just contains defbody. Arbitratry code can be inserted before or after the defbody to be executed before or after the SQL statement.
wrapDelete () is wrapped around the delete SQL statement. By default it just contains defbody. Arbitratry code can be inserted before or after the defbody to be executed before or after the SQL statement.
wrap_find_query () is wrapped around the query generation of the find button. That means the defbody returns a string that becomes the search condition of the query to be performed. You can either change the fields in this.ff to modify field values before query generation or you can generate a complete search condition and leave out defbody completely.
wrap_lookup_query () is wrapped around the query generation of the lookup button. That means the defbody returns a string that becomes the search condition of the query to be performed. You can either change the fields in this.ff to modify field values before query generation or you can generate a complete search condition and leave out defbody completely.
onDuplicate (oldrec) is called if a record with the same key is already present during an Insert operation. Per default this routine returns an appropriate error message.
onNotfound () is called if a record searched for is not present. Must return an error message.
onDbChange (newrec) is called if current record changed in the database or if it was deleted meanwhile. The routine should call select_row in order to reread the record and return an error message. Alternatively other methods to resolve the conflict can be implemented. The newrec parameter contains the current status of the record.
onKeyChange () is called prior to an update if the user changed the key of the current database record. Per default this routine checks the keychange attribute of the dbform and returns an error message if key changes are not allowed.
onSuccess () is called on successful completion of an operation
Methods
select_row (search_condition) queries the database according to the search condition. The first record found becomes the current row, unless the CheckSelect hook returns an error message. select_row returns true if a row was found, false if not, and an error message if CheckSelect delivered an error message.
insert_row () Performs an insert.
update_row () Performs an update.
modify_row () Performs an insert or an update depending on weather there is a current row or not.
copy_row () Performs a copy, i.e. the form will no longer be associatd with a database record but still contain the same field values. Performing a subsequent insert_row will store the form content as a new database record (assuming that the key field values have been changed to avoid a duplicate record error message).
delete_row () Performs a delete.
clear () Clears the form.
find_row () Search for the first matching row. All fields of a matching row must contain the form field's content as substring.
lookup_row () Search for the first matching row. All non-empty form fields must exactly match the row's fields.
first_row (direction) Show the first (or last in case direction="backward") record.
next_row (direction) Show the next (or previous in case direction="backward") record.
© 1996-2024 H.E.I. All Rights Reserved.
