DIODisplay - Database Interface Objects Display Class

## DIODisplay - Database Interface Objects Display Class

### 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

-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.

DIO |  | DIODisplay