NAME

Template::Magic::Pager - HTML Pager for Template::Magic

VERSION 1.15

Included in Template-Magic-Pager 1.15 distribution.

The latest versions changes are reported in the Changes file in this distribution.

The distribution includes:

• Template::Magic::Pager

  HTML Pager for Template::Magic

• Template::Magic::Slicer

  Deprecated module

INSTALLATION

Prerequisites

Perl version    >= 5.6.1
Template::Magic >= 1.2
OOTools         >= 1.71

Standard installation

From the directory where this file is located, type:

perl Makefile.PL
make
make test
make install

SYNOPSIS

use Template::Magic::Pager ;

# 1st way (useful when you have big number of results)
$pager = Template::Magic::Pager->new
         ( total_results   => $results         # integer
         , page_rows       => $rows            # ARRAY ref
         , page_number     => $page_number     # integer
         , rows_per_page   => $rows_per_page   # integer
         , pages_per_index => $pages_per_index # integer
         ) ;

# 2nd way (useful when you have all the result in an ARRAY)
# total_results is an ARRAY ref and page_rows is ommitted
$pager = Template::Magic::Pager->new
         ( total_results   => $results         # ARRAY ref
         , page_number     => $page_number     # integer
         , rows_per_page   => $rows_per_page   # integer
         , pages_per_index => $pages_per_index # integer
         ) ;

and inside the 'pager' block in your template file you will have availables a complete set of "Labels and Blocks".

DESCRIPTION

This module make it very simple to split an array of results into pages, and use your own totally customizable Template-Magic file to display each page; it is fully integrated with CGI::Builder::Magic and its handlers (such as TableTiler), and it can be used efficiently with any DB.

Using it is very simple: you have just to create an object in your code and define a block in your template and Template::Magic will do the rest. Inside the block you will have available a complete set of magic labels to define the result headers, dynamic index navigation bars Goooogle style and more. (see "Labels and Blocks")

You can use this module in two different situations:

1. When you have big number of results coming from a DB query. In this situation you don't need to retrieve them all in order to initialize the object: you just need to pass the total number of results as the total_results and the slice of the page_rows to display in the page.

2. When you already have all the results in memory, and you want to display just one slice of them. In order to do so you need just to pass the reference to the whole ARRAY of results as the total_results and the object will set the page_rows to the correct slice of results.

Useful links

• A simple and useful navigation system between my modules is available at this URL: http://perl.4pro.net

• More practical topics are discussed in the mailing list at this URL: http://lists.sourceforge.net/lists/listinfo/template-magic-users

METHODS

new( arguments )

This method returns the new object reference ONLY if there are results to display (see total_results below). It accepts the following arguments:

• total_results

  Mandatory argument. It may be an integer value of the total number of results you want to split into pages (not to be confused with the results of one page), or it may be a reference to the whole array of results; in this case you should omit the page_rows argument. (see SYNOPSIS to see the two ways to use the new() method)

  If the passed value is not true (0 or undef), then the new() method will return the undef value instead of the object, thus allowing you to define a NOT_pager block that will be printed when no result has been found.

• page_rows

  Mandatory argument only if the total_result argument is an integer. It expect a reference to an ARRAY containing the slice of results of the current page (or a reference to a sub returning the reference to the ARRAY).

• page_number

  It expects an integer value representing the page to display. Default is 1 (i.e. if no value is passed then the page number 1 will be displayed).

• rows_per_page

  Optional argument. This is the number of results that will be displayed for each page. Default 10.

• pages_per_index

  Optional argument. This is the number of pages (or items) that will build the index bar. Default 10. (see also index)

Other Methods

Since all the magics of this module is done automatically by Template::Magic, usually you will explicitly use just the new() method. Anyway, each "Labels and Blocks" listed below is referring to an object method that returns the indicated value. The Block methods -those indicated with "(block)"- are just boolean methods that check some conditions and return a reference to an empty array when the condition is true, or undef when it is false.

Labels and Blocks

These are the labels and blocks available inside the pager block:

• start_result

  The number of the result which starts the current page.

• end_result

  The number of the result which ends the current page.

• total_results

  The number of the total results (same number passed as the total_results argument: see new()).

• page_rows (block)

  This block will be automatically used by Template::Magic to generate the printing loop with the slice of results of the current page.

• page_number

  The current page number (same number passed as the page_number argument: see new())

• total_pages

  The total number of pages that have been produced by splitting the results.

• previous (block)

  This block will be printed when the current page has a previous page, if there is no previous page (i.e. when the current page is the first page), then the content of this block will be wiped out. If you need to print somethingjust when the current page has no previous page (e.g. a dimmed 'Previous' link or image), then you should define a NOT_previous block: it will be printed automatically when the previous block is not printed.

• previous_page

  The number of the page previous to the current page. Undefined if there are no previous pages (i.e. when the current page is the first page).

• next (block)

  This block will be printed when the current page has a next page, if there is no next page (i.e. when the current page is the last page), then the content of this block will be wiped out. If you need to print something just when the current page has no next page (e.g. a dimmed 'Next' link or image), then you just need to define a NOT_next block: it will be printed automatically when the next block is not printed.

• next_page

  The number of the page next to the current page. Undefined if there are no next pages (i.e. the current page is the last page).

• index (block)

  This block defines the index bar loop: each item of the loop has its own set of values defining the page_number, start_result and end_result of each index item. Nested inside the index block you should define a couple of other blocks: the current_page and the linked_page blocks.

  current_page (block)

  This block will be printed only when the index item refers to the current page, thus allowing you to print this item in a different way from the others items.

  linked_page (block)

  This block will be printed for all the index items unless the item is referring to the current page.

EXAMPLE

This is a complete example with results coming from a DB query. In this case you don't want to retrieve the whole results that would be probably huge, but just the results in the page to display:

use Template::Magic ;
use Template::Magic::Pager ;
use CGI;

my $cgi = CGI->new() ;
my $pages_per_index = 20 ;
my $rows_per_page   = $cgi->param('rows') ;                 # e.g. 20
my $page_number     = $cgi->param('page') ;                 # e.g. 3
my $offset          = $rows_per_page * ($page_number - 1) ; # e.g. 40

# this manages the page_rows template block (notice the 'our')
# (change the assignment with any real DB query)
my $page_rows  = ... SELECT ...
                     LIMIT $offset, $rows_per_page ... ;   # ARRAY ref
my $count      = ... SELECT FOUND_ROWS() ... ;             # integer e.g 526

# $pager whould be undef if $count is not true
our $pager = Template::Magic::Pager->new
             ( total_results   => $count           # (e.g 1526)
             , page_rows       => $page_rows       # (ARRAY ref)
             , page_number     => $page_number     # (3)
             , rows_per_page   => $rows_per_page   # (20)
             , pages_per_index => $pages_per_index # (20)
             ) ; 

Template::Magic::HTML->new->print('/path/to/template') ;

In this example $main::page_rows contains the array of results to display for the current page, and it will be used automagically by Template::Magic to fill the page_rows template block.

Note: To be sure the object is syncronized with the retrived DB query, you must use the correct offset and rows_per_page in both DB retrieving and object initialization. To do so you should use this simple algorithm:

my $offset = $rows_per_page * ($page_number - 1) ;

More examples

You can find a little example (complete of templates) in the examples dir included in this distribution.

Note: While you are experimenting with this module, you are probably creating examples that could be useful to other users. Please submit them to theTemplate::Magic mailing list, and I will add them to the next release, giving you the credit of your code. Thank you in advance for your collaboration.

SUPPORT

Support for all the modules of the Template Magic System is via the mailing list. The list is used for general support on the use of the Template::Magic, announcements, bug reports, patches, suggestions for improvements or new features. The API to the Magic Template System is stable, but if you use it in a production environment, it's probably a good idea to keep a watch on the list.

You can join the Template Magic System mailing list at this url:

http://lists.sourceforge.net/lists/listinfo/template-magic-users

AUTHOR and COPYRIGHT

© 2004 by Domizio Demichelis (http://perl.4pro.net)

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

cpanm Template::Magic::Pager

perl -MCPAN -e shell
install Template::Magic::Pager