DBIx::Frame::CGI - tools for web-based use of DBIx::Frame databases
use DBIx::Frame::CGI;
DBIx::Frame->init('server', 'dbtype') || exit(0);
my $DB = DBIx::Frame->new('database', 'user', 'pass')
or die("Couldn't connect to database: ", DBIx->errstr);
my $CGI = new CGI || die "Couldn't open CGI";
my $params = {};
foreach ($cgi->param) { $$params{$_} = $cgi->param($_); }
my $action = $cgi->param('action') || "";
my $table = $cgi->param('table') || "";
print $cgi->header(), $cgi->start_html(-title => "YOUR TITLE");
print $DB->make_html( $action, $table, $params, {} )
or die "Couldn't run script";
print $cgi->end_html();
exit(0);
More functions, and detailed descriptions, are below.
DBIx::Frame::CGI is an extension of the DBIx::Frame module to allow for web use and administration of DBIx::Frame databases. It provides a common set of HTML functions for creating, modifying, viewing, and deleting entries in the database. These tools allow for simple administration scripts, as well as a decent API for creating more complex user scripts.
All of these functions must be invoked on a fully created DBIx::Frame object, as discussed in its manual page.
There are four type of functions in this package - Full-Layout, HTML Form Layout, and Actions.
Note that these layout functions are fairly specific - they will make fully laid out HTML, based on the design goals of the author. These goals may not mesh exactly with what you want to do; if this is so, then it should be a fairly simple matter to write new functions based on these for your own CGI scripts.
Specifically, each of these can be overridden by adding a section to your .cgi files that looks like this:
package YOUR::PACKAGE;
sub html_menu {
# insert your own code here
}
Then, when you're using your own package, it will use this version of html_menu() (or any other piece of code) instead of the system-default code. You can therefore use this as a template to make your own web designs.
The defaults, though, are actually fairly decent, or at least a fair bit of effort has been put into helping them be that way. Suggestions are, as always, encouraged.
Returns a whole formatted HTML page, using the subfunctions from the package, based on the input from ACTION. At the bottom of the page is a centered html_menu(). The page still needs headers and footers. TABLE, PARAMS, OPTIONS, and OTHER are passed into the sub- functions as appropriate.
Default ACTIONs (case-insensitive):
ACTION Called Function Function Type [none] html_actions() Full-Layout Options create html_create() HTML Form Layout list html_list() HTML Form Layout search html_search() HTML Form Layout edit html_edit() HTML Form Layout view html_view() HTML Form Layout delete html_delete() HTML Form Layout + Actions update html_update() Actions insert html_insert() Actions
More actions can be added with actions(), and actions can be removed with remove_action(). All actions are invoked with the following parameters:
C<TABLE>, C<PARAMS>, C<OPTIONS>, C<OTHER>
Valid OPTIONS:
nomenu If set, don't include the bottom menu C<html_menu()>
quiet If set, print as little information as possible with the
HTML tables; not yet fully implemented
Returns a table of table/action pairs available to the user. Gets the information from tables() and @DBIx::Frame::ACTIONS. Each column of the table is a different action; each row is a table.
Returns a menu in HTML to navigate the various tables and actions available to the user. Gets the information from tables() and @DBIx::Frame::ACTIONS. The menu is an HTML form that reinvokes the calling program, using the fields 'action' and 'table'.
The HTML Form Layout functions are generally based around each table's html() function, which is defined in its class. Note that this function must be properly created if you expect these functions to actually do anything.
Returns an HTML form containing the code necessary to insert an item into the database. Submitting the form should invoke html_insert().
Returns an HTML table containing data selected with PARAMS, using make_list(). (Note that this does not use the html() function.) The table also includes links to a perform more actions on the items - by default, it's 'view', but 'edit' and 'delete' can be added.
Valid options for OPTIONS:
nodetail Doesn't offer 'view' action
admin Offers 'edit' and 'delete' action
count Total entries to print. Defaults to 50.
first First entry to print. Defaults to 0.
last Last entry to print. Defaults to (first + count)
nocount Don't offer 'next' and 'last' options, offer a
search dialogue instead (if necessary to narrow
the search)
nodelsearch Don't include the html_search() dialogue box if no
matches are found.
tdopts The options to use for each of the <td> tags in the
table. Defaults to 'align=center'.
useropts See below.
The trickiest of the above options is 'useropts'. This must be an array reference; it contains a list of additional actions to offer for each item. Each array item must be either the name of the function you want to invoke (see actions() for information on how to add these), or another array reference; this reference must contain first the name of the function you want to invoke, and then a list of tables that it affects.
html_list_banner() is the same as html_list(), except that it returns a small banner at the top. html_list() is therefore more easily embedded in other code.
html_list_nosearch() actually does the work of html_list() using an array of selected datahashes (ENTRIES). It may be invoked by other programs that want to select based on their own criteria.
Returns an HTML form containing the code necessary to search the database. Submitting the form should invoke html_list().
Valid options for OPTIONS:
nosearchname Don't include the 'search TABLE' bit at the top
of the search
Returns an HTML form containing the code necessary to edit a database entry. Submitting the form should invoke html_update().
Returns an HTML form containing the code necessary to view an item in without the formatting of the form - thus making it printable. Relies on HTML::FormRemove.
Offer a method of deleting items from the database. Operates on two levels: either returns an HTML form containing the code necessary to delete an item from the database, or actually does the work and returns some basic searching information.
The difference between the two actions is the value of the 'CONFIRM' parameter. If it's set, then delete, otherwise return message asking whether you want to continue.
(Note that this is the least tested part of the code.)
Actions actually do work on the database
Updates the items selected with PARAMS. The original items are selected with "Old.FIELD" fields in PARAMS. Returns an html_list() of the appropriate values.
Adds an item into TABLE based on PARAMS. Returns an html_create() of the same values, allowing you to add more entries easily.
One of the main goals of this module is to allow for programmers to manipulate the behaviours of these HTML forms fairly easily. This is primarily taken care of through the use of the PARAMS and OPTIONS hash references, which are referenced throughout the code.
There are also a few functions to help manipulate the behaviour of the code:
This function handles the list of actions available within make_html(). The actions are contained by a private hash, where the keys are the action names and the values are the code references to make the HTML and/or perform the actions.
If ACTION is not offered, returns undef. If it doesn't exist, and no CODEREF is offered, returns an empty string. If CODEREF is offered, sets the code refence value to CODEREF (regardless of whether the action previously existed). Regardless, returns the new code reference.
Note, all code references should take the standard parameters:
CODEREF($self, $table, $params, $options, @other);
Removes ACTION from the list of actions. If multiple ACTIONs are offered, removes them all. Returns the number of successful removals.
The following data structions are considered public, and may be modified by the running program as appropriate.
Determines which actions should be offered in html_actions().
None of these items do any work to determine whether the user is allowed to perform the actions that he's trying to do - this should be taken care of when writing the CGI scripts and choosing which user can connect.
Good class design is also important. The KEY values that you use must guarantee that each item is unique! If this is not done, then functions like html_delete() can wreak havoc on your tables.
Perl 5 or better, DBIx::Frame, and HTML::FormRemove.
DBI, DBIx::Frame, HTML::FormRemove.
Fixing up the HTML::FormRemove thing would be nice, or else doing something else with html_view() (which I'm not altogether happy with).
Written by Tim Skirvin <tskirvin@ks.uiuc.edu>.
http://www.ks.uiuc.edu/Development/MDTools/dbixframe/
This code is distributed under the University of Illinois Open Source License. See http://www.ks.uiuc.edu/Development/MDTools/dbixframe/license.html for details.
Copyright 2000-2004 by the University of Illinois Board of Trustees and Tim Skirvin <tskirvin@ks.uiuc.edu>.
