Name
DIODisplay — Database Interface Objects Display Class
Synopsis
DIODisplay (objectName
| #auto) (-option | option
| -option | option
| ...)
Description
DIODisplay is an HTML display class that uses a DIO object
to do the database work and a form object to do the
displaying.
Options
-
The DIO object to be used in conjunction with this
display object. This is a required field.
-
If cleanup is true, when the display object is shown,
it will automatically destroy the DIO object, the form
object and itself. Default is true.
-
If confirmdelete is true, attempting to delete a
record from the database first requires that the user
confirm that they wish to delete it. If it is false,
deletion occurs without prompting the user. Defaults
to true.
-
The name of a procedure to handle errors when they
occur. During the processing of requests and pages,
sometimes unexpected errors can occur. This procedure
will handle any errors. It is called with a single
argument, the error string. Use of the Tcl errorInfo
and errorCode variables is also recommended though.
If no errorhandler is specified, the handle_error
method within the Display object will handle the
error.
-
Specify a list of fields to be used in this object.
The fields list is actually created by using the
field command to add fields to the
display, but this option can be useful to sometimes
over-set the list of fields created.
-
A Rivet form object to use when displaying a form. If
one is not specified, the display object will
automatically create one when it is necessary.
-
A list of functions to be displayed in the main menu.
This is a list of functions the user is allowed to
execute.
-
How many records to show per page on a search or
list. Default is 25.
-
A list of fields to display in each row of a search or
list. When a search or list is conducted and the
resulting rows are displayed, this list will limit
which fields are displayed. Default is all fields.
-
-rowfunctions functionList
A list of functions to display in each row of a search
or list.
-
A list of fields to allow a user to search by. This
list will appear in the main screen as a drop-down box
of fields the user can search on.
-
The title of the display object. This will be output
as the title of the HTML document.
DIO Display Object Commands
-
objectName
cleanup ?value
?
Return the current cleanup value. If
value
is
specified, it sets a new value for the cleanup
option.
-
Delete the specified key from the
database.
The default action of this method is to call the DIO
object's delete command. This method can be
overridden.
-
Destroy the diodisplay object.
-
Return the current DIO value. If
value
is
specified, it sets a new value for DIO.
-
objectName
errorhandler ?value
?
Return the current errorhandler value. If
value
is specified, it
sets a new value for errorhandler.
-
objectName
fetch key
arrayName
Fetch the specified key
from the database and store it as an array in
arrayName
.
The default of this method is to call the DIO object's fetch command.
This method can be overridden.
-
objectName
field fieldName
(-arg | arg
...)
Create a new field object and add it to the display.
When a field is added to the display, a new object
of the DIODisplayField class is created with its
values. See [FIXME - LINK] DIO Display Fields for
options and values.
-
objectName
fields ?value
?
Return the current fields value. If
value
is
specified, it sets a new value for fields.
-
Return the current form value. If
value
is
specified, it sets a new value for form.
-
objectName
function functionName
Add a new function to the list of possible
functions. The display object will only execute
methods and procs which are defined as functions by
the object. This is to protect the program from
executing a different procedure other than what is
allowed. The function command
adds a new function to the list of allowable
functions.
-
objectName
functions ?value
?
Return the current functions value. If
value
is
specified, it sets a new value for functions. See
[FIXME - LINK DIO Display Functions] for a list of
default functions.
-
objectName
pagesize ?value
?
Return the current form pagesize. If
value
is
specified, it sets a new value for pagesize.
-
objectName
rowfields ?value
?
Return the current form rowfields. If
value
is
specified, it sets a new value for rowfields.
-
Output the footer of a list of rows to the web page.
This method can be overridden.
-
objectName
rowfunctions ?value
?
Return the current rowfunctions value. If
value
is
specified, it sets a new value for rowfunctions.
-
Output the header of a list of rows to the web page.
By default, this is an HTML table with a top row
listing the fields in the table.
This method can be overridden.
-
objectName
searchfields ?value
?
Return the current searchfields value. If
value
is
specified, it sets a new value for searchfields.
-
Show the display object.
This is the main method of the display class. It
looks for a variable called mode
to be passed in through a form response and uses
that mode to execute the appropriate function. If
mode is not given, the Main
function is called.
This function should be called for every page.
-
Display the form of the object.
This method displays the form for this display
object. It is used in the Add
and Edit methods but can be
called separately if needed.
This method can be overridden if the default look of
a form needs to be changed. By default, the form
displayed is simply the fields in a table, in order.
-
objectName
showrow arrayName
Display a single row of a resulting list or search.
This method is used to display a single row while
displaying the result of a list or search.
arrayName
is a fetched array of the record.
This method can be overriden if the default look of
a row needs to be changed. By default, each row is
output as a table row with each field as a table
data cell.
-
Display the view of the object.
This method displays the view for this display
object. It is used in the
Details methods but can be
called separately if needed.
This method can be overridden if the default look of
a view needs to be changed. By default, the view
displayed is simply the fields in a table, in order.
-
objectName
store arrayName
Store the specified
arrayName
in the database.
The default of this method is to call the DIO
object's store command. This method can be
overridden.
-
Return the current text value. If
value
is
specified, it sets a new value for text.
-
Return the current title value. If
value
is
specified, it sets a new value for title.
-
Return the current type value. If
value
is
specified, it sets a new value for type.
-
Return the current value value. If
value
is
specified, it sets a new value for value.
DIO Display Functions
These functions are called from the
show method when a form response
variable called mode
is set. If no
mode has been set, the default mode is
Main. The show method will handle
the necessary switching of functions. The show method
also handles checking to make sure the function given is a
true function. If not, an error message is displayed.
New functions can be added as methods or by use of the
function command, and any of the
default functions can be overridden with new methods to
create an entirely new class. These are the default
functions provided.
- Add
Show a form that allows the user to add a new entry
to the database. This function calls
showform to display the form
for adding the entry.
- Cancel
The Cancel function does nothing
but redirect back to the Main
function. This is handy for forms which have a
cancel button to point to.
- Delete
If confirmdelete
is true (the
default), the Delete function
will ask the user if they're sure they want to
delete the record from the database. If
confirmdelete
is false, or if the
user confirms they wish to delete, this function
calls the DoDelete function to do
the actual deletion of a record.
- Details
Display the view of a single record from the database. This function calls
the showview method to display a single record from the database.
- DoDelete
This function actually deletes a record from the
database. Once it has deleted the record, it
redirects the user back to the
Main function.
- Edit
Show a form that allows the user to edit an existing
entry to the database. This function calls
showform to display the form for
editing the entry and fills in the fields with the
values retrieved from the database.
- List
This function lists the entires contents of the
database. Each record is output in a row using the
showrow method.
- Main
This function is the main function of the display
object. If there is no mode, or once most commands
complete, the user will be redirected to this
function. The default Main
function displays a list of functions the user can
execute, a list of searchfields the user can search
on, and a query field. This query field is used by
all of the other functions to determine what the
user is trying to find.
In the case of a search, query
specifies what string the user is looking for in the
specified search field. In the case of
delete,
details or
edit, the query specifies the
database key to access.
- Save
This function saves any data passed to using the
store method. This is primarily
used by the add and
edit commands to store the
results of the form the user has filled out.
- Search
This function searches the database for any row
whose searchBy
field matches
query
. Once any number of records
are found, Search displays the
results in rows.
DIO Display Fields
Display fields are created with the
field command of the DIODisplay object.
Each field is created as a new DIODisplayField object or
as a subclass of DIODisplayField. The standard form
fields use the standard field class, while specialized
field types use a class with different options but still
supports all of the same commands and values a generic
field does.
displayObject
field fieldname
(-option | option
...)
These are the standard options supported by field types:
-
When a field is created, any argument which is not a
standard option is assumed to be an argument passed
to the form object when the field is shown in a
form. These arguments are all appended to the
formargs
variable. You can use
this option to override or add options after the
initial creation of an object
-
If readonly
is set to true, the
field will not display a form entry when displaying
in a form.
-
The text displayed next to the form or view field.
By default, DIODisplay tries to figure out a pretty
way to display the field name. This text will
override that default and display whatever is
specified.
-
The type of field this is. This type is used when
creating the field in the form object.
fieldType
can be any of the accepted form field types. See
[FIXME - LINK DIO Field Types] for a list of types
available.
All other arguments, unless specified in an individual
field type, are passed directly to the form object when
the field is created. So, you can pass
-size or -maxsize to
specify the length and maximum length of the field entry.
Or, if type were textarea, you could define
-rows and -cols to
specify its row and column count.
DIO Display Field Types
The following is a list of recognized field types by
DIODisplay. Some are standard HTML form fields, and
others are DIODisplay fields which execute special actions
and functions.