Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pager(3)	      User Contributed Perl Documentation	      Pager(3)

NAME
       HTML::Pager - Perl module to handle CGI HTML paging of arbitary data

SYNOPSIS
	 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;

DESCRIPTION
       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.

METHODS
   "new()"
       The new() method	creates	a new Pager object and prepares	the data for
       "output()".

       "new()" requires	several	options, see above for syntax:

       o   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.

       o   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.

       o   page_size - the number of rows to display at	one time.

       o   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:

       o   debug - if set to 1,	debugging information is warn()'d during the
	   program run.	 Defaults to 0.

       o   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>
	     ...

       o   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.

       o   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' ]);

       o   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' );

       o   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' );

       o   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' );

       o   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>

   "output()"
       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.

MAINTAINING PAGING STATE
       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.

CREDITS
       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.

AUTHOR
       Sam Tregar, sam@tregar.com

LICENSE
       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

SEE ALSO
       HTML::Template, CGI

POD ERRORS
       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

perl v5.24.1			  2000-04-14			      Pager(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | MAINTAINING PAGING STATE | CREDITS | AUTHOR | LICENSE | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::Pager&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help