|
|
| |
Pager(3) |
User Contributed Perl Documentation |
Pager(3) |
HTML::Pager - Perl module to handle CGI HTML paging of arbitary data
use HTML::Pager;
use CGI;
# get CGI query object
my $query = CGI->new();
# create a callback subroutine to generate the data to be paged
my $get_data_sub = sub {
my ($offset, $rows) = @_;
my @return_array;
for (my $x = 0; $x < $rows; $x++) {
push(@return_array, [ time() ]);
}
return \@return_array;
}
# create a Pager object
my $pager = HTML::Pager->new(
# required parameters
query => $query,
get_data_callback => $get_data_sub,
rows => 100,
page_size => 10,
# some optional parameters
persist_vars => ['myformvar1',
'myformvar2',
'myformvar3'],
cell_space_color => '#000000',
cell_background_color => '#ffffff',
nav_background_color => '#dddddd',
javascript_presubmit => 'last_minute_javascript()',
debug => 1,
);
# make it go - send the results to the browser.
print $pager->output;
This module handles the paging of data coming from an arbitrary source and being
displayed using HTML::Template and CGI.pm. It provides an interface to pages
of data similar to many well-known sites, like altavista.digital.com or
www.google.com.
This module uses HTML::Template to do all its HTML generation.
While it is possible to use this module without directly using
HTML::Template, it's not very useful. Modification of the look-and-feel as
well as the functionality of the resulting HTML should all be done through
HTML::Template objects. Take a look at HTML::Template for more info.
The new() method creates a new Pager object and prepares the data for
"output()".
"new()" requires several
options, see above for syntax:
- query - this is the CGI.pm query object for this run. Pager will remove
it's state-maintaining parameters from the query. They all begin with
PAGER_, so just be careful not to use that prefix.
- rows - this is the total number of rows in your dataset. This is needed to
provide the next-button, prev-button and page-jump functionality.
- page_size - the number of rows to display at one time.
- get_data_callback - this is a callback that you provide to get the pages
of data. It is passed two arguements - the offset and the number of rows
in the page. You return an array ref containing array refs of row data.
For you DBI-heads, this is very similar to selectall_arrayref() -
so similar that for very simple cases you can just pass the result
through. Example - this is a sub that returns data from an in-memory array
of hash refs.
my @data = (
{ name => sam, age => 10 },
{ name => saa, age => 11 },
{ name => sad, age => 12 },
{ name => sac, age => 13 },
{ name => sab, age => 14 },
# ...
);
my $get_data_sub = sub {
my ($offset, $rows) = @_;
my @return_array;
for (my $x = 0; $x < $rows; $x++) {
push(@return_array, [ $data[$offset + $x]{name},
$data[$offset + $x]{age}
]
);
}
return \@return_array;
}
my $pager = HTML::Pager->new(query => $query,
get_data_callback => $get_data_sub,
rows => 100,
page_size => 10
);
You can also specify arguements to be passed to your callback
function. To do this, call new like:
HTML::Pager->new(query => $query,
get_data_callback => [$get_data_sub, $arg, $arg],
rows => 100,
page_size => 10
);
If you want to use named, rather than numeric TMPL_VARs in
your Pager template you can return a ref to an array of hashes rather
than arrays. This array of hashes will be passed directly to
HTML::Template to fill in the loop data for your paging area.
"new()" supports several
optional arguements:
- debug - if set to 1, debugging information is warn()'d during the
program run. Defaults to 0.
- template - this is an HTML::Template object to use instead of the
auto-generated HTML::Template used in Pager output. It must define the
following TMPL_LOOPs and TMPL_VARs. Here's what the default template looks
like, to give you an idea of how to change it to suite your purposes:
<TMPL_VAR NAME="PAGER_JAVASCRIPT">
<FORM>
<TABLE BORDER=0 BGCOLOR=#000000 WIDTH=100%>
<TR><TD><TABLE BORDER=0 WIDTH=100%>
<TMPL_LOOP NAME="PAGER_DATA_LIST">
<TR>
<TD BGCOLOR=#ffffff><TMPL_VAR NAME="PAGER_DATA_COL_0"></TD>
<TD BGCOLOR=#ffffff><TMPL_VAR NAME="PAGER_DATA_COL_1"></TD>
<TD BGCOLOR=#ffffff><TMPL_VAR NAME="PAGER_DATA_COL_2"></TD>
<!--- depends on number of rows in data - so should your replacement! -->
</TR>
</TMPL_LOOP>
<TR><TD BGCOLOR=#DDDDDD COLSPAN=3 ALIGN=CENTER>
<TMPL_VAR NAME="PAGER_PREV">
<TMPL_VAR NAME="PAGER_JUMP">
<TMPL_VAR NAME="PAGER_NEXT">
</TD></TR>
</TABLE>
</TABLE>
<TMPL_VAR NAME="PAGER_HIDDEN">
</FORM>
Make sure you include all the TMPL_LOOPs and TMPL_VARs
included above. If you get HTML::Template errors about trying to set bad
param 'PAGER_BLAH', that probably means you didn't put the 'PAGER_BLAH'
variable in your template. You can put extra state-maintaining
<INPUT> fields in the paging form - in fact, I think that this is
probably required for most real-world uses.
Optionally you can use named parameters inside
PAGER_DATA_LIST, and return an array of hashes to fill them in from
get_data_callback. If you did that your template might look like:
...
<TMPL_LOOP NAME="PAGER_DATA_LIST">
<TR>
<TD BGCOLOR=#ffffff><TMPL_VAR NAME="NUMBER"></TD>
<TD BGCOLOR=#ffffff><TMPL_VAR NAME="FIRST_NAME"></TD>
<TD BGCOLOR=#ffffff><TMPL_VAR NAME="LAST_NAME"></TD>
</TR>
</TMPL_LOOP>
...
- persist_vars - Pass a ref to an array of the names of the CGI form
parameters you want to store into this fuction, and they will be included
in the hidden form data of the pager form.
This method allows you to have hidden form variables which
persist from page to page. This is useful when connecting your pager to
some other function (such as a search form) which needs to keep some
data around for later use.
The old
$pager->persist_vars() syntax still
works but is deprecated.
- column_names - should be set to an array ref containing the names of the
columns - this will be used to create column headers. Without this
arguement, the columns will have no headers. This option is only useful in
very simple cases where all the data is actually in use as columns.
Example:
my $pager = HTML::Pager->new( column_names => [ 'one', 'two' ]);
- cell_space_color - this specifies the color of the lines separating the
cells. If the default template is mostly OK, except for the color scheme,
this will provide a middle ground between the necessity of creating your
own Pager template and suffering with bad colors. Example:
my $pager = HTML::Pager->new( cell_space_color => '#222244' );
- cell_background_color - this specifies the background color of each data
cell. If the default template is mostly OK, except for the color scheme,
this will provide a middle ground between the necessity of creating your
own Pager template and suffering with bad colors. Example:
my $pager = HTML::Pager->new( cell_background_color => '#000000' );
- nav_background_color - this specifies the background color of the bottom
navigation bar. If the default template is mostly OK, except for the color
scheme, this will provide a middle ground between the necessity of
creating your own Pager template and suffering with bad colors. Example:
my $pager = HTML::Pager->new( nav_background_color => '#222244' );
- javascript_presubmit - this optional parameter allows you to specify a
Javascript function which will be called when a user clicks on one of the
Pager navigation buttons, prior to submitting the form. Only if this
function returns 'true' will the form be submitted.
The Pager navigation calls its
'PAGER_set_offset_and_submit()' javascript function when a user
clicks the "Next", "Previous" or other page buttons.
This normally precludes calling your own javascript submit functions to
perform some task.
Through this hook, you can perform client-side functions, such
as form validation, which can modify the form or actually prevent the
user from going to the next page. This is particularly useful for
enabling some kind of work-flow involving form validation.
Constructor Example:
my $pager = HTML::Pager->new(
javascript_presubmit => 'last_minute_javascript()'
);
HTML Example:
<script language=Javascript>
function last_minute_javascript() {
return confirm("Are you sure you want to leave this page?");
}
</script>
This method returns the HTML <FORM> and <TABLE> to create the paging
list-view. If you used the template option to new() this will output
the entire template.
Sometimes you'll want to be able to allow the user to leave your paging list and
be able to come back to where they were without requiring that they use the
Back button. To do this all you have to do is arrange to save the state of the
PAGER_offset parameter, and pass it back to the paging-list CGI.
This module was created for Vanguard Media and I'd like to thank my boss, Jesse
Erlbaum, for allowing me to release it to the public. He also added the
persist_vars functionality, the background colors option and the
javascript_presubmit option.
Sam Tregar, sam@tregar.com
HTML::Template : A Perl module to handle CGI HTML paging of arbitary data
Copyright (C) 1999 Sam Tregar (sam@tregar.com)
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
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 the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Hey! The above document had some coding errors, which are explained
below:
- Around line 152:
- =back doesn't take any parameters, but you said =back 4
- Around line 305:
- =back doesn't take any parameters, but you said =back 4
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |