# Blosxom3 Plugin: Paginate
# Author: Bernie Simon
# Version: 2004-02-14
# More notes at the bottom of this file or type: perldoc Paginate

package Blosxom::Plugin::Paginate;

#----------------------------------------------------------------------
# Configuration Section

# The paramter that indicates where to start in the list
use constant PAGINATE_PARAM => 'start';

# The text string used in the link to the previous page
use constant PREVIOUS_TEXT => 'newer';

# The text string used in the link to the next page
use constant NEXT_TEXT => 'older';

# String added at the very start of the pagination links
use constant BEFORE_FIRST => '';

# String added at the very end of the pagination links
use constant AFTER_LAST => '';

# String added before each link
use constant BEFORE_EACH => '';

# String added after each link
use constant AFTER_EACH => '';

# String added between each link
use constant BETWEEN_EACH => ' | ';

#----------------------------------------------------------------------
# call from handlers.entry

sub run {
    my $self = shift;
	
    my $start = $self->{cgi}->param (PAGINATE_PARAM);
    my $entry_number = ++ $self->{state}->{current_entry_number};

    if ($entry_number < $start) {
	$self->{state}->{Plugin}->{Paginate}->{previous} = 1;
	$self->{state}->{stop}->{handlers}->{entry} ++;

    } elsif ($entry_number == ($start + $self->{settings}->{max_entries})) {
	$self->{state}->{stop}->{handlers}->{entry} ++;

    } elsif ($entry_number > ($start + $self->{settings}->{max_entries})) {
	$self->{state}->{Plugin}->{Paginate}->{next} = 1;
	$self->{state}->{stop}->{handlers}->{entry} ++;
	$self->{state}->{stop}->{entries} ++;
    }

    return 1;
}

#----------------------------------------------------------------------
# call from handlers.flow

sub links {
    my $self = shift;
    
    my $links = '';
    if ($self->{state}->{Plugin}->{Paginate}->{next} ||
	$self->{state}->{Plugin}->{Paginate}->{previous}) {

	my @links;
	my $start = $self->{cgi}->param (PAGINATE_PARAM);

	if ($self->{state}->{Plugin}->{Paginate}->{next}) {
	    my $old_start = $start + $self->{settings}->{max_entries};
	    $self->{cgi}->param (PAGINATE_PARAM, $old_start);

	    my $url = $self->{cgi}->self_url;
	    push (@links, "<a href=\"$url\">" . NEXT_TEXT . "</a>");

	} else {
	    push (@links, NEXT_TEXT);
	}

	if ($self->{state}->{Plugin}->{Paginate}->{previous}) {
	    my $new_start = $start - $self->{settings}->{max_entries};
	    $new_start = 0 if $new_start < 0;
	    $self->{cgi}->param (PAGINATE_PARAM, $new_start);

	    my $url = $self->{cgi}->self_url;
	    push (@links, "<a href=\"$url\">" . PREVIOUS_TEXT . "</a>");

	} else {
	    push (@links, PREVIOUS_TEXT);
	}

	$self->{cgi}->param (PAGINATE_PARAM, $start);

	my $before = BEFORE_FIRST . BEFORE_EACH;
	my $after = AFTER_EACH . AFTER_LAST;
	my $between = AFTER_EACH . BETWEEN_EACH . BEFORE_EACH;

	$links = $before . join ($between, @links) . $after;

    }

    $self->{state}->{current_entry}->{Plugin}->{Paginate}->{Links} = $links;
    return 1;
}

1;

__END__

=head1 NAME

Paginate.pm

=head1 SYNOPSIS

Display entries a page at a time

=head1 DESCRIPTION

Blosxom normally displays N entries in the rendered page. N is set by
the value of the variable max_entries. This module looks for a
parameter appended to Blosxom's url. This parameter is named "start"
by default. If it finds this parameter, it skip all entries until the
count reaches the value of that parameter and then displays the next
set of entries up to a count of max_entries. This module also creates
links to the next page of entries and to the previous page of
entries. By clicking on these links one can page through all the
entries on the site in either direction.

=head1 CONFIGURABLE VARIABLES

The configuarion variables control the parameter used to control the
pagination and the look of the set of links to next and previous
pages.

=over 4

=item PAGINATE_PARAM

The name of the parameter that indicates the first entry displayed in
the rendered page. The number of entries dispayed is controlled by the
variable max_entries, located in the .settings/settings file or the
default value in the Blosxom.pm file.

=item  PREVIOUS_TEXT

The text string used in the link to the previous page

=item  NEXT_TEXT

The text string used in the link to the next page

=item BEFORE_FIRST

A string that is placed at the very beginning of the set of pagination
links.

=item AFTER_LAST

A string that is placed at the very end of the set of pagination
links.

=item BEFORE_EACH

A string that is placed before each pagination link

=item AFTER_EACH

A string that is placed after each pagination link

=item BETWEEN_EACH

A string that is placed between each pagination link

=back

=head1 INSTALLATION

Place this file in the plugins directory. Replace the line

    Blosxom::shortcut_max_entries

in the .settings/handlers.entry file with the line

    Blosxom::Plugin::Paginate::run

and add the line 

    Blosxom::Plugin::Paginate::links

to the .settings/handlers.flow file after Blosxom::run_entries and
before Blosxom::render_response.

Customize the constants at the top of the file to produce a set of
links that look the way you want. Add the variable

    $Plugin::Paginate::Links

to the head.html or foot.html template to create links to the next and
previous page of links.

=head1 BUGS

Because the version of Blosxom 3 that is currently being distributed
ignores the handlers.flow file, you need to first install a patch to
Blosxom 3 to fix this problem, such as the one distributed on my site
in order for the changes to the handlers.flow file to be recognized.

=head1 AUTHOR

Bernie Simon (http://carelesshand.net)

=head1 LICENSE

Copyright Bernard Simon, 2005. You may use this file as you wish as
long as this copyright notice is maintained.