NAME

DBIx::glueHTML - Class for creating a CGI interface to a database

SYNOPSIS

 use CGI;
 use DBI;
 use DBIx::glueHTML;

 $cgi                   = new CGI;
 $dbh                   = DBI->connect("DBI:mysql:[DATABASE]:[HOSTNAME]","[USERNAME]","[PASSWORD]") );
 $DBinterface   = new DBIx::glueHTML ($cgi, $dbh, "[INFOTABLE NAME]");

 # Below here is only executed if a glueHTML action was not taken, so print a menu

 print $cgi->header;
 print "<A HREF=" . $cgi->url . "?glueHTML-table=[TABLENAME]&glueHTML-action=add>Add</A>\n<BR>";
 print "<A HREF=" . $cgi->url . "?glueHTML-table=[TABLENAME]&glueHTML-action=search>Search</A>\n";

DESCRIPTION

The DBIx::glueHTML class allows a CGI interface to a database. It enables a CGI interface to a database to be created, supporting record addition, modification, deletion and searching. It provides a user friendly interface with descriptions of fields provided. The field descriptions along with information on whether the field is visible, hidden or excluded are extracted from a table, allowing easy modification and addition of fields and tables without having to edit code.

Features

Simple database administration: Forms are created automatically on demand, SQL statements are generated as needed and processed. The module contains enough autonomy to potentially run with only wrapper perl code placed around it.
Full form configuration: Forms can be modified to add descriptions and extra information to fields, making it easy to change output without having to edit code.
Control: Extensive callback procedures and configuration options allow output, password protection and logging to be configured as desired.
Full HTML customisation: HTML output and table formats can be customised easily by the user.

METHODS

Main Methods

$DBinterface = new DBIx::glueHTML (CGI DBI Infotable Name [Suppress paramcheck]);

Constructs a new DBIx::glueHTML object. You must pass a reference to a CGI object which will be used to get the script's parameters and a database handle (Returned from a DBI->connect function) which will be used to communicate with the database. The third parameter defines the name of the info table which is used to determine hidden/excluded fields, field names and descriptions as described below in INFOTABLE FORMAT. After initialisation, the CGI object is checked for a 'glueHTML-action' parameter. If this is present, control is taken from the script and the specified action is performed on the specified table. This parameter is set when an action which requires further processing is in progress.

The final parameter, suppress paramcheck, is optional and when set to 1 will cause the script NOT to perform the parameter check. You MUST then call the check_params function in your code or forms will not work. Overriding the script in this way is not recommended unless necessary for error handler or security check handler setting.

Optional Methods

Optional methods which can be called to directly jump to a script function, for example to directly initiate a delete or modify on a record.

check_params ();

  # Check form parameters
  $DBinterface->check_params;

Causes the glueHTML-action parameter to be rechecked. If it contains the value 'add','modify','delete' or 'search', the respective function will be called ('exec_add','exec_modify','exec_delete' or 'exec_search'). this function is essential to the correct functioning of the interfaces with two and three part forms, and is called automatically when a glueHTML object is created, unless the 'suppress paramcheck' parameter is set to 1.

exec_search ();

  # Now set the 'glueHTML-table' parameter so the script knows 
  # what table to deal with
  $cgi->param(-name=>'glueHTML-table',-value=>'mytable');

  # Now call the function 
  $DBinterface->exec_search;

Searches the table named in the CGI parameter 'glueHTML-table'. The user will be presented with a blank form with the fields of the table. They press submit to search the table (Wildcards can be used). They are then returned a table with a modify and delete button and the fields for each record found.

exec_modify ();

  # Assume $cgi->param has been set to indicate the primary keys
  # for the table being modified, i.e 'Primary Key Name' = 'Primary
  # Key Value'

  # Now set the 'glueHTML-table' parameter so the script knows 
  # what table to deal with
  $cgi->param(-name=>'glueHTML-table',-value=>'mytable');

  # Now call the function 
  $DBinterface->exec_modify;

Modifies a record from the table named in the CGI parameter 'glueHTML-table' where the CGI parameters which have the same name as a table column. For example for a table called 'data' with an 'ID' column containing the primary keys for that table, set the 'glueHTML-table' parameter to 'data' and set the 'ID' parameter to the ID number of the record you want to modify. The user will then be presented with a form containing the data in the table for them to modify. They then press submit to commit the data

exec_add ();

  # Now set the 'glueHTML-table' parameter so the script knows 
  # what table to deal with
  $cgi->param(-name=>'glueHTML-table',-value=>'mytable');

  # Now call the function 
  $DBinterface->exec_add;

Adds a record to the table named in the CGI parameter 'glueHTML-table'. The user will be presented with a empty form containing just the defaults for the values of that table (Defined in the SQL). They then press submit to commit the data to the table.

exec_delete ();

  # Assume $cgi->param has been set to indicate the primary keys
  # for the table being modified, i.e 'Primary Key Name' = 'Primary
  # Key Value'

  # Now set the 'glueHTML-table' parameter so the script knows 
  # what table to deal with
  $cgi->param(-name=>'glueHTML-table',-value=>'mytable');

  # Now call the function 
  $DBinterface->exec_delete;

Deletes a record from the table named in the CGI parameter 'glueHTML-table' where the CGI parameters which have the same name as a table column. For example for a table called 'data' with an 'ID' column containing the primary keys for that table, set the 'glueHTML-table' parameter to 'data' and set the 'ID' parameter to the ID number of the record you want to delete.

This function will output a confirmation page requiring users to confirm the delete or press their browser's back button to cancel. To skip confirmation, set the 'confirm' parameter to 'Y'.

Optional Customisation Methods

Optional methods which can be called to alter the behaviour of the script or enable features such as logging.

set_logcallback (Callback function address);

  sub log_callback {
      my $description = shift;
      my $sql         = shift;

      open (LOG,">>$logfile")
      print LOG "$description (Executing $sql)";
      close(LOG);
  }
  $DBinterface = new DBIx::glueHTML ($cgi, $dbh, $table, 1);
  $DBinterface->set_logcallback(\&log_callback);
  $DBinterface->check_params();

Enables logging of SQL changes to the database via the user defined routine. The first parameter passed is a description, such as 'Record added to mytable' and the second parameter is the SQL statement which was used.