NAME
HTML::SearchPage - Generic framework for building web-based search pages
SYNOPSIS
Please refer to HTML::SearchPage::Tutorial for a tutorial on using HTML::SearchPage & HTML::SearchPage::Param.
DESCRIPTION
This module provides a generic framework for building web-based search pages.
USAGE
Please refer to HTML::SearchPage::Tutorial for a tutorial on using HTML::SearchPage & HTML::SearchPage::Param.
QUICK REFERENCE
All the parameters listed below have a get/set method. However, the set functionality of the params in the 3rd group is not intended to be utilized except for development.
Group 1 - Parameters required by the constructor
The following parameters are required by the constructor.
Parameter Description Format
--------- ----------- ------
db_access_params Database access parameters [$datasource, $user,
$password]
temp_dir Temporary directory to store images scalar scalar
and session files
temp_dir_eq URL-equivalent to access files in temp_dir scalar
base_sql_table Base SQL table (or table join) to build final scalar
SQL queries
base_sql_fields Fields that will be retrieved by the SQL arrayref
statement
base_output_headers Headers output in results arrayref
base_identifier Unique identifier column used by display_info scalar
method (* required only when display_info
method is used)Group 2 - Optional parameters
The following parameters are optional.
Parameter Description Format Default
--------- ----------- ------ -------
page_title Page title scalar 'Search
Page'
header HTML header in views scalar(i) ''
footer HTML footer in views scalar(i) ''
cookie Name of cookie scalar html-searchpage
cookie_expires_in_min Expiration tim eof cookie scalar 30
(number)
css CSS for views scalar(i) ''
instructions Instructions for views scalar(i) ''
distinct Make SQL query "distinct" 0|1 0
no_reset No reset button 0|1 0
new_search Place a new search button, 0|<URL> 0
(implies no_reset)
group_by Group by statement scalar ''
(exclude
GROUP BY)
sort_fields Number of sort fields scalar 0
(number)
sort_defaults Default sort options arrayref(ii) []
method HTML form method to use GET|POST GET
action HTML URL to script scalar $ENV{SCRIPT_NAME}
page_size Number of records per scalar 50
result page (number)
show_search_url Whether to display a
self-referencing search URL 0|1 0
debug_level Level of debug information: 0|1|2(iii) 0
go_to_results If set, a click on the page 0|1 1
will take the display to the
beginning of the results
on the subsequent page
modifier The page modifier object ref undef
external_where_clauses External where clauses arrayref []
Notes:
(i) The parameter provided here can be of the following types, specified by the preceding keyword:
- FILE:<something> : Contents of file <something> is retrieved
- EXEC:<something> : <something> is executed and its STDOUT is retrieved
- GET:<something> : URL <something> is retrieved by LWP
- <something> : <something> is used as it is
(ii) Format for sort defaults:
["(asc|desc) <field>", "(asc|desc) <field>", "(asc|desc) <field>"]
(iii) Debug levels:
- 0: No debug information
- 1: Time, URL, version information of critical code components, generated SQL statements
- 2: In addition to (1), environment variablesGroup 3 - Internal methods
The following parameters are set automatically but they can be get/set after object instantiation.
Parameter Description Format
--------- ----------- ------
cgi CGI object CGI ref
cgi_params CGI params hashref
count Retrieved data count scalar
count_sql_statement Generated SQL statement for scalar
retrieving count of results
data Retrieved data arrayref (each element is
an arrayref of a row)
debug_info HTML code for retrieved debug scalar
info based on debug level
db_display Display name for the database scalar
in effect
dbh Database handle DBI ref
db_selected Database specified using the scalar
database param in the URL
formatted_data HTML code or text for of data scalar
formatted based on output
format
modifications Scheduled modifications arrayref
param_fields Stored HTML::SearchPage::Param hashref
objects
query_sql_statement Generated SQL statement for scalar
retrieving results
search_form HTML code for generated search scalar
form
session Session object CGI::Session ref
session_id Session id scalar
super_output_headers Headers and super hashref
headersOTHER
"db_access_params" can be specified in two forms:
The following format is used when there is only one database that the page will be running on.
db_access_params => [$datasource, $username, $password];Alternatively, a set of databases can be specified and can be addressed by "database=<alias>" URL parameter.
db_access_params => {
database => [
{
alias => $alias,
display => 'Database 1',
datasource => $datasource2,
username => $username2,
password => $password2,
},
{
alias => $alias,
display => 'Database 2',
datasource => $datasource2,
username => $username2,
password => $password2,
},
],
}When multiple databases are provided, database selection is persistent between pages that use HTML::SearchPage. This feature requires cookies to be enabled.
AUTHOR
Payan Canaran <pcanaran@cpan.org>
BUGS
VERSION
Version 0.05
ACKNOWLEDGEMENTS
This module has been initially written for implementing search pages for displaying maize diversity data on Panzea (www.panzea.org), the public web site of the "Molecular and Functional Diversity of the Maize Genome" project. Thanks to project members for their feedback on user features and help in testing the web displays.
COPYRIGHT & LICENSE
Copyright (c) 2005-2007 Cold Spring Harbor Laboratory
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.