CGI::Widget::DBI::Search - Database search widget

NAME
SYNOPSIS
DESCRIPTION
CONSTRUCTOR
PRIVATE METHODS
METHODS
AUTHOR
COPYRIGHT
COPYLEFT (LICENSE)
LAST MODIFIED

NAME

SYNOPSIS

  use CGI;
  use CGI::Widget::DBI::Search;

  my $q = CGI->new;
  my $ws = CGI::Widget::DBI::Search->new(q => $q);

  # database connection info
  $ws->{-dbi_connect_dsn} = 'DBI:Pg:dbname=my_pg_database;host=localhost';
  $ws->{-dbi_user} = 'pguser';
  $ws->{-dbi_pass} = 'pgpass';

  # what table to use in the SQL query FROM clause
  $ws->{-sql_table} = 'table1 t1 inner join table2 t2 using (key_col)';

  # optional WHERE clause
  $ws->{-where_clause} = 'WHERE t1.filter = ? OR t2.filter != ?';
  # bind params needed for WHERE clause
  $ws->{-bind_params} = [ $filter, $inverse_filter ];

  # what columns to retrieve from query
  $ws->{-sql_retrieve_columns} =
    [ qw/t1.id t1.name t2.long_description/, '(t1.price + t2.price) AS total_price'];
  # what columns to display in search results (with header name)
  $ws->{-display_columns} =
    { id => "ID", name => "Name", long_description => "Description", total_price => "Price" };

  $ws->{-numeric_columns} = { id => 1 };
  $ws->{-currency_columns} = { total_price => 1 };

  $ws->{-show_total_numresults} = 1;

  # execute database search
  $ws->search();

  # output search results to browser
  print $q->header;
  print $q->start_html;

  # show search results as HTML
  print $ws->display_results();

  print $q->end_html;

DESCRIPTION

Encapsulates a DBI search in a Perl class, including all SQL statements required for performing the search, query results, HTML display methods, and multi-column, sortable result set displayed page-by-page (using HTML navigation links).

CONSTRUCTOR

new(@config_options): Creates and initializes a new CGI::Widget::DBI::Search object. Possible configuration options:

PRIVATE METHODS

_set_defaults(): Sets necessary object variables from defaults in package constants, if not already set. Called from search() method.
_set_display_defaults(): Sets object variables for displaying search results. Called from display_results() method.

METHODS

default_fetchrow_closure(): This is the default -fetchrow_closure that will be called for each row returned by a search. It can be called by an overridden -fetchrow_closure to selectively modify desired fields.
search([ $where_clause, $bind_params, $clobber ]): Perform the search: runs the database query, and stores the matched results in an object variable: 'results'.; Optional parameters $where_clause and $bind_params will override object variables -where_clause and -bind_params. If $clobber is true, search results from a previous execution will be deleted before running new search.
get_num_results(): Executes a SELECT COUNT() query with the current search parameters and stores result in object variable: 'numresults'. Has no effect unless -show_total_numresults object variable is true. Th is used for displaying total number of results found, and is necessary to provide a last-page link to skip to the end of the search results.
pagesort_results($col, $reverse): Sorts a single page of results by column $col. Reorders object variable 'results' based on sort column $col and boolean $reverse parameters.; (note: method currently unused)
display_results([ $disp_cols ]): Displays an HTML table of data values stored in object variable 'results' (retrieved from the most recent call to search() method). Optional variable $disp_cols overrides object variable -display_columns.
generate_nav_links(): Returns four URIs for navigating through search results: $prevlink, $nextlink, $firstlink, $lastlink
display_pager_links($startat, $pagetotal, $maxpagesize, $searchtotal, $prevlink, $nextlink, $firstlink, $lastlink, $showtotal): Returns an HTML table containing navigation links for first, previous, next, and last pages of result set. This method is called from display_results() and should be treated as a protected method.; parameters: $startat page of results on which to start $pagetotal number of items on *this* page $maxpagesize size of page: maximum number of items to show per page $searchtotal total number of items returned by search $prevlink HTML href link to previous page of results $nextlink HTML href link to next page of results $firstlink HTML href link to first page of results $lastlink HTML href link to last page of results $showtotal boolean to toggle whether to show total number of results along with range on current page

AUTHOR

Adi Fairbank <adi@adiraj.org>

COPYRIGHT

This software, the CGI::Widget::DBI::Search Perl module, is copyright Adi Fairbank.

COPYLEFT (LICENSE)

This module is free software; you can redistribute it and/or modify it under the terms of either:

  a) the GNU General Public License as published by the Free Software
     Foundation; either version 1, or (at your option) any later version,

or

  b) the "Artistic License" which comes with this module.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC; if not, the following URL references a copy of it (as of June 8, 2003):

  http://www.perl.com/language/misc/Artistic.html

You should have received a copy of the GNU General Public License along with this program, in the file GPL; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA; or try the following URL which references a copy of it (as of June 8, 2003):

  http://www.fsf.org/licenses/gpl.html

LAST MODIFIED

Jan 31, 2008