Index...
Centrallix Documentation
|
widget/form
form :: A nonvisual container used to group a set of form element widgets into a single record or object
Metadata:
| type: | widget/form |
| visual: | no |
| container: | yes |
| form element: | no |
Overview:
The form widget is used as a high-level container for form elements. Essentially, a form widget represents a single record of data, or the attributes of a single object in the objectsystem (or of a single query result set object). Form widgets must be used in conjunction with an ObjectSource widget, which does the actual transferring of data to and from the server.
Forms have five different "modes"of operation, each of which can be specifically allowed or disallowed for the form.
No Data - form inactive/disabled, no data viewed/edited.
View - data being viewed readonly.
Modify - existing data being modified.
Query - query criteria being entered (used for query-by-form applications)
New - new object being entered/created.
Occasionally, the user may perform an operation which inherently disregards that the form may contain unsaved data. When this occurs and there is newly created or modified data in the form, the application must ask the user whether the data in the form should be saved or discarded, or whether to simply not even perform the operation in question. Since DHTML does not inherently have a "three-way confirm" message box (with save, discard, and cancel buttons), Centrallix allows a form to specify a "three-way confirm" window. This should be a hidden (visible=no) "widget/htmlwindow" object which may contain any content, but should at least contain three buttons named "_3bConfirmSave", "_3bConfirmDiscard", and "_3bConfirmCancel" directly in the htmlwindow. During a confirm operation, this window will become "application-modal"; that is, no other widgets in the application may be accessed by the user until one of the three buttons is pushed.
Several settings on the form widget control what state, or "mode", the form can be in: allow_query, allow_new, allow_modify, allow_view, and allow_nodata. These can beused to constrain a form to perform a specific task, such as only searching, or only creating new records. For example, a form with only allow_search enabled will always return to the search (QBF) mode and will never display the searched-for data that is returned in the objectsource.
Usage:
Although the form widget itself is nonvisual in nature, it can contain visual widgets, including other containers, which may then in turn contain form elements as well. The form widget may be contained within any widget with a visual container (otherwise, the form elements would not show up on the page).
Properties:
| Property | Type | Description |
|---|
| allow_query |
yes/no |
Allow query by form |
| allow_new |
yes/no |
Allow creation of new records |
| allow_modify |
yes/no |
Allow modification of existing records |
| allow_view |
yes/no |
Allow viewing of existing data |
| allow_nodata |
yes/no |
Allow the 'no data' state |
| allow_delete |
yes/no |
Allow deletion of the displayed record |
| confirm_delete |
yes/no |
Whether to pop up an OK/Cancel message box asking the user whether he/she is sure the record should be deleted |
| auto_focus |
yes/no |
Default "yes". Whether to automatically place the focus on the first form element in the form when the form transitions to the New, Modify, or Search mode for any reason other than the user manually putting focus on one of the form elements. |
| enter_mode |
string |
Can be "save" (default), "nextfield", or "lastsave". Controls what to do when the user presses ENTER while in a form element in this form. "save" means to save the record immediately. "nextfield" means to move to the next form field, as if TAB were pressed instead. "lastsave" means to move to the next form field, but once ENTER is pressed on the very last field, to then save the record. Most people prefer "save" for this, since that is consistent with how normal applications work, but people in finance or accounting work often prefer "lastsave" since it allows them to perform high-speed data entry using a numeric keypad. |
| next_form |
string |
Specifies another form to transfer focus to when the user presses TAB at the end of the form. |
| next_form_within |
string |
Similar to "next_form", but searches for the next form after this one within a given widget or component. Transitioning from one component context to another is permitted (you could specify a "widget/page" widget here, and cause focus to transfer to another form in the same application, regardless of level of component nesting; this may or may not be desired behavior). |
| tab_revealed_only |
yes/no |
When tabbing between form elements, if this is set to "yes", do not transfer focus to form elements that are not currently visible to the user. |
| allow_obscure |
yes/no |
Default "no". If this is set to "yes", then the form will permit its data to be obscured (hidden from the user, via a window closure or tab page switch) and unsaved at the same time. If set to "no", the form will require the user to save or cancel any data modifications before the form may be obscured. |
| MultiEnter |
integer |
Enable MultiEnter |
| TabMode |
string |
How to react to a tab in a control |
| ReadOnly |
integer |
Allow changes |
| _3bconfirmwindow |
string |
The name of the window to use for all 3-way confirm operations (save/discard/cancel) |
Child Properties:
(of formelement child widgets)
| Property | Type | Description |
|---|
| fieldname |
string |
Fieldname (from the dataset) to bind this element to |
(of formstatus child widgets)
none currently available
Actions:
| Action | Description |
|---|
| Clear |
Clears the form to a 'no data'state. |
| Delete |
Deletes the current object displayed. |
| Discard |
Cancels an edit of form contents. |
| Edit |
Allows editing of form's contents. |
| First |
Moves the form to the first object in the objectsource. |
| Last |
Moves the form to the last object in the objectsource. |
| New |
Allows creation of new form contents. |
| Next |
Moves the form to the next object in the objectsource. |
| Prev |
Moves the form to the previous object in the objectsource. |
| Query |
Allows entering of query criteria. |
| QueryExec |
the query and returns data. |
| Save |
Saves the form's contents. |
Events:
none currently available
Client Properties:
| Property | Type | Description |
|---|
| is_discardable |
true/false |
Whether the form has a status or modifications that can be discarded / canceled. |
| is_editable |
true/false |
True if the form is in a state where the data can be edited (but isn't currently being edited). |
| is_newable |
true/false |
True if the form is in a state where a new record can be created. |
| is_queryable |
true/false |
Whether the form can be placed into "QBF" (query by form) mode so that the user can enter query criteria. |
| is_queryexecutable |
true/false |
Whether the form is in "QBF" (query by form) mode so that the query can actually be run. |
| is_savable |
true/false |
Whether the form has data in it that can be saved with the Save action. |
| lastrecid |
integer |
The number of the last record in the query results, starting with '1'. Null if no data is available or if the last record has not yet been determined. |
| recid |
integer |
The current record in the data source being viewed, starting with '1'. Null if no data is available. |
none currently available
Sample Code:
form1 "widget/form"
{
//Form elements here
}
Comments...
(none yet)
Add a Comment...
|
