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
- 
		objectNamecleanup  ?value?
 
- 
		  Return the current cleanup value.  If
		  - valueis
		  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
		  - valueis
		  specified, it sets a new value for DIO.
 
- 
		objectNameerrorhandler  ?value?
 
- 
		  Return the current errorhandler value.  If
		  - valueis specified, it
		  sets a new value for errorhandler.
 
- 
		objectNamefetchkeyarrayName
 
- 
		  Fetch the specified - keyfrom 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.
		 
- 
		objectNamefieldfieldName(-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.
		 
- 
		objectNamefields  ?value?
 
- 
		  Return the current fields value.  If
		  - valueis
		  specified, it sets a new value for fields.
 
- 
		
	      
- 
		  Return the current form value.  If
		  - valueis
		  specified, it sets a new value for form.
 
- 
		objectNamefunctionfunctionName
 
- 
		  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.
		 
- 
		 objectNamefunctions  ?value?
 
- 
		  Return the current functions value.  If
		  - valueis
		  specified, it sets a new value for functions.  See
		  [FIXME - LINK DIO Display Functions] for a list of
		  default functions.
 
- 
		objectNamepagesize  ?value?
 
- 
		  Return the current form pagesize.  If
		  - valueis
		  specified, it sets a new value for pagesize.
 
- 
		objectNamerowfields  ?value?
 
- 
		  Return the current form rowfields.  If
		  - valueis
		  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.
		 
- 
		objectNamerowfunctions  ?value?
 
- 
		  Return the current rowfunctions value.  If
		  - valueis
		  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.
		 
- 
		objectNamesearchfields  ?value?
 
- 
		  Return the current searchfields value.  If
		  - valueis
		  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 - modeto 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.
		 
- 
		objectNameshowrowarrayName
 
- 
		  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.
		  - arrayNameis 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.
		 
- 
		objectNamestorearrayName
 
- 
		  Store the specified
		  - arrayNamein 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
		  - valueis
		  specified, it sets a new value for text.
 
- 
		
	      
- 
		  Return the current title value.  If
		  - valueis
		  specified, it sets a new value for title.
 
- 
		
	      
- 
		  Return the current type value.  If
		  - valueis
		  specified, it sets a new value for type.
 
- 
		
	      
- 
		  Return the current value value.  If
		  - valueis
		  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 - confirmdeleteis true (the
		  default), the Delete function
		  will ask the user if they're sure they want to
		  delete the record from the database.  If- confirmdeleteis 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 - searchByfield 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
		  - formargsvariable.  You can use
		  this option to override or add options after the
		  initial creation of an object
 
- 
		
	      
- 
		  If - readonlyis 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.
		  - fieldTypecan 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.