/ 
Data-Pageset-Render-0.12
River stage zero No dependents
/ Data::Pageset::Render

NAME

Data::Pageset::Render - Subclass of Data::Pageset that generates html, text, etc. for page navigation

SYNOPSIS

### In the Controller part of you MVC
# Create the pager as you would normally with Data::Pageset
use Data::Pageset::Render;
my $pager = Data::Pageset::Render->new( {
      total_entries    => 100,
      entries_per_page => 10,
      current_page     => 1,
      pages_per_set    => 5,
      mode             => 'slider',
} );

### In the view part of your MVC
# Basic usage:
my $text = $pager->html( '<a href="q?page=%p">%a</a>' );
# $text is html "<< 1 ... 3 4 5 6 7 ... 10 >>" with appropriate links
# A bit more control over the appearence of the current page:
my $text = $pager->html( '<a href="q?page=%p">%a</a>', '[%a]' );
# $text is html "<< 1 ... 3 4 [5] 6 7 ... 10 >>" with appropriate links

### As part of larger framework
# In a TT template:
[% pager.html( '<a href="q?page=%p">%a</a>' ) %]
# In a Mason template:
<% $pager->html( '<a href="q?page=%p">%a</a>' ) %>

DESCRIPTION

METHODS

Data::Pageset::Render add the following method to Data::Pageset. The constructor and all of Data::Pagesets methods continue to function as normal.

html( $link_format, $current_page_format )
my $text = $pager->html( '<a href="q?page=%p">%a</a>' );
my $text = $pager->html( '<a href="q?page=%p">%a</a>', '[%a]' );

Produces the text necessary to implement page navigation. Most often this will be used to create a links to pages within your web app. The two special character codes %p and %a will be substituted with the page number and the link text, respectively. %a will usually also be the page number, but sometimes it could be "<<", ">>", or "...".

Rather than code this in TT or Mason or (even worse) by hand, Data::Pageset::Render replaces all of this:

## TT template:
[% IF pager.current_page > 1 %]
    <a href="display?page=[% pager.current_page - 1 %]">&lt;&lt;</a>
[% END %]
[% FOREACH num = [pager.first_page .. pager.last_page] %]
[% IF num == pager.current_page %][[% num %]]
[% ELSE %]<a href="display?page=[% num %]">[[% num %]]</a>[% END %]
[% END %]
[% IF pager.current_page < pager.last_page %]
    <a href="display?page=[% pager.last_page %]">&gt;&gt;</a>
[% END %]

with this:

[% pager.html( '<a href="display?page=%p">%a</a>', '[%a]' ) %]

And you get even more goodness from Data::Pageset limiting the pages displayed to something reasonable if you are dealing with a large number of pages.

TODO

In this release, there is limited ability to customize the page navigation. I plan to add the ability to customize the following:

  • Option to not display the first/last pages if they aren't part of current page set

  • Option to not display the link to the prior/next page set (assuming it exists)

  • Ability to customize the look of "move back/forward" links (currently only << and >> are supported) or turn them off completely

  • Ability to customize the look of the prior/next page sets (currently only "..." is supported)

  • Ability to specify the separators between links (ie, enable "1 | 2 | 3 | 4" type pagers)

This module is a work in progress and suggestions are welcome.

SEE ALSO

Data::Pageset, Class::DBI::Pageset, Data::Page

BUGS

Please report any bugs or suggestions at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Pageset-HTML

AUTHOR

Mark Grimes, <mgrimes@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Mark Grimes

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.