DBIx::HTML::PopupRadio - Convert sql into a popup menu or radio group.
use DBIx::HTML::PopupRadio;
my($popup_object) = DBIx::HTML::PopupRadio -> new
(
dbh => $dbh,
sql => 'select campus_id, campus_name from campus order by campus_name',
);
$popup_object -> set(default => '1');
my($popup_menu) = $popup_object -> popup_menu();
my($radio_group) = $popup_object -> radio_group();
print $popup_menu;
This module takes a db handle and an SQL statement, and builds a hash.
Then you ask for that hash in HTML, as a popup menu or as a radio group.
The reading of the db table is delayed until you actually call one of the methods 'popup_menu' or 'radio_group'. Even then, it is delayed until any parameters passed in to these 2 methods are processed.
After a call to one of these 2 methods, you can call the 'size' method if you need to check how many rows were returned by the SQL you used.
Neither the module CGI.pm, nor any of that kidney, are used by this module. We simply output pure HTML.
This module is available both as a Unix-style distro (*.tgz) and an ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file.
See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing each type of distro.
You create an object of the class by calling the constructor, 'new'.
You then call 'set', if you wish, to set any options.
Now call 'popup_menu' or 'radio_group' to get the HTML.
Lastly, display the HTML as part of a form.
The method names 'popup_menu' and 'radio_group' (and 'param') were chosen to be reminiscent of methods with the same names in the CGI.pm module. But let me repeat, my module does not use CGI.
Here, in alphabetical order, are the options accepted by the constructor, together with their default values.
This option is mandatory, in the call to new, set, popup_menu or radio_group. Ie By the time you call one of the latter 2 methods, dbh must be set.
If default is not given a value, the first menu item becomes the default.
See the discussion of the sql option for details about the menu items.
This option is not mandatory.
This option is not mandatory.
This option is not mandatory, since it has a default value. It could be unset and then reset, but must have a value by the time you call popup_menu or radio_group.
The value of this parameter is what you will pass into a CGI object when you
call its param() method to retrieve the user's selection.
Hence you would do something like:
my($name) = 'fancy_menu';
my($popup_object) = DBIx::HTML::PopupRadio -> new(name => $name, ...);
my($q) = CGI -> new();
my($id) = $q -> param($name) || '';
The string can contain a single quote but not a double quote.
This string will be both a visible menu item and the value returned to yoru CGI script if the user selects this menu item.
This option is not mandatory.
This option is mandatory, in the call to new, set, popup_menu or radio_group. Ie By the time you call one of the latter 2 methods, sql must be set.
The SQL must select 2 columns. The first will be used as the value returned by
a CGI object, for example, when you call its param() method. The second value
will be used as the visible selection offered to the user on the menu.
Of course, the 2 columns selected could be the same:
$obj -> set(sql => 'select campus_name, campus_name from campus order by campus_name');
But normally you would do this:
$obj -> set(sql => 'select campus_id, campus_name from campus order by campus_name');
This means that the second column is used to construct visible menu items, and when an item is selected by the user, the first column is what is returned to your CGI script.
The question remains: After you do something like this:
my($q) = CGI -> new();
my($id) = $q -> param('dbxi_menu') || '';
how do you convert the value, eg campus_id, back into the visible menu item, eg campus_name.
Simple: You call the param method of the DBIx::HTML::PopupRadio class:
my($name) = $popup_object -> param($id);
param returns the empty string if the value of $id is unknown.
In other words, convert the first column of the SQL into the second column.
popup_menu(%arg) takes the same parameters as new().
radio_group(%arg) takes the same parameters as new().
set(%arg) takes the same parameters as new().
It will tell you whether or not your menu is empty.
See examples/*.cgi for complete programs, both simple and complex.
You will need to run examples/bootstrap-menus.pl to load the 'test' database, 'campus' and 'unit' tables, with sample data.
You'll have to patch these 2 programs vis-a-vis the db vendor, username and password.
The sample data in bootstrap-menus.pl is simple, but is used by several modules, so don't be too keen on changing it :-).
CGI::Explorer
DBIx::HTML::ClientDB
DBIx::HTML::LinkedMenus
The latter 2 modules will be released after the current one.
DBIx::HTML::PopupRadio was written by Ron Savage <ron@savage.net.au> in 2002.
Home page: http://savage.net.au/index.html
Australian copyright (c) 2002, Ron Savage. All rights reserved.
All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License, a copy of which is available at:
http://www.opensource.org/licenses/index.html