DIODisplay

DIODisplay
	DIODisplay - Database Interface Objects Display Class

Name

DIODisplay — Database Interface Objects Display Class

Synopsis

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

-DIO dioObject: The DIO object to be used in conjunction with this display object. This is a required field.
-cleanup (1 | 0): 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.
-confirmdelete (1 | 0): 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.
-errorhandler procName: 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.
-fields fieldList: 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.
-form formObject: 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.
-functions functionList: A list of functions to be displayed in the main menu. This is a list of functions the user is allowed to execute.
-pagesize pageSize: How many records to show per page on a search or list. Default is 25.
-rowfields fieldList: 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.
-searchfields fieldList: 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.
-title title: 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.
objectName delete key: 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.
objectName destroy: Destroy the diodisplay object.
objectName DIO ?value?: 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.
objectName form ?value?: 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.
objectName rowfooter: 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.
objectName rowheader: 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.
objectName show: 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.
objectName showform: 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.
objectName showview: 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.
objectName text ?value?: Return the current text value. If value is specified, it sets a new value for text.
objectName title ?value?: Return the current title value. If value is specified, it sets a new value for title.
objectName type ?value?: Return the current type value. If value is specified, it sets a new value for type.
objectName value ?value?: 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:

-formargs arguments: 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
-readonly (1 | 0): If readonly is set to true, the field will not display a form entry when displaying in a form.
-text text: 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.
-type fieldType: 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.


DIODisplay - Database Interface Objects Display Class		Session Package