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
OidId  
RelationRelation Name Database relation. 
KeyString Key field names, separated by comma. If you leave this empty, the Component Editor tries to determine it from the relation. 
KeychangeString(60) 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.  
StateString(60) Use to disable form fields. 
MethodString(60) 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.  
EnctypeString(60) Content type for method "post". Use "multipart/form-data" with fieldfileupload.  
SuccessuriString(60) Continue with this URI after the form has been submitted successfully.  
FragmentString(10) Section name (The # part of the action URI without the #). No effect on successuri. 
PasswordfieldString(20)  for password protection: password field name  
MsgallowedString(60) 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
emptyDisplays an empty form. Any field values included in the message are takes as default values of the form.
displayDisplays 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.
modifyDisplays 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.
copyDisplays 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:

sesform The ok, success, and ff attributes might be of interest.
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.


This page was dynamically generated by the web application development tool RADpage of H.E.I.
© 1996-2017 H.E.I. All Rights Reserved.



Homepage
Intro/Features
Component Guide
Programming
  Language Guide
  Language Ref.
  Component Ref.
    Concepts
    Component List
    Component Table
    Component
  Class Library
  User Components
  Tryout Form
  Tutorial
  New Features
  heitml 1
User Guide
FAQ
Mailinglist
Discussion Group
Services
Pricing/Register
Download
Frame
 
Contact
 
 
 
Search: