Flourish PHP Unframework

fPagination

class, v1.0.0b2

Prints pagination links for fRecordSet or other paginated records

Changes:
1.0.0b2Improved the determination of what pages to show with with_first_last templates 9/16/12
1.0.0bAdded the prev_disabled and next_disabled pieces 9/6/11

Static Methods

::defineTemplate() public

Defines a new template to use with the paginator

The $pieces array must contain the following array keys:

  • info: the template to use when calling the printInfo() method
  • start: the template to start the page list with
  • prev: the template for the previous link
  • prev_disabled: the template for the previous link, when disabled
  • page: the template for a single page link
  • separator: the template for the separator to use when the type is with_first_last
  • next: the template for the next link
  • next_disabled: the template for the next link, when disabled
  • end: the template to end the page list with

There are various pre-defined variables available for use in the template pieces. These variables are printed by using the syntax {{ variable }}.

The info, start and end pieces may use the following variables:

  • page: the page of records being shown
  • total_pages: the total number of pages of records
  • first_record: the record number of the first record being shown
  • last_record: the record number of the last record being shown
  • total_records: the total number of records being paginated

The prev and next pieces may use the following variables:

  • page: the page number of the page of results being linked to
  • url: the URL of the page being linked to

The page piece may use the following variables:

  • page: the page number of the page being linked to
  • url: the URL of the page being linked to
  • first: the string "first" if the link is to the first page
  • last: the string "last" if the link is to the last page
  • current: the string "current" if the link is to the current page

The separator piece does not have access to any pre-defined variables.

In addition to the pre-defined variables, it is possible to add any other variables to be used in any of the pieces by calling the instance method set().

It is possible to use variable filters on a variable to modify it. The most common variable to filter would be name. To filter a variable, add a | and the filter name after the variable name, in the form {{ variable|filter }}. The following filters are available:

  • inflect: if the total number of records is not 1, pluralize the variable - this only works for nouns
  • lower: converts the contents of the variable to lower case
  • url_encode: encode the value for inclusion in a URL
  • humanize: converts a underscore_notation or CamelCase string to a string with spaces between words and in Title Caps

Filters can be combined, in which case they are list one after the other in the form {{ variable|filter_1|filter_2 }}.

Signature

void defineTemplate( string $name, string $type, integer $size, array $pieces )

Parameters

string $name The name of the template
string $type The type of pagination: without_first_last or with_first_last - with_first_last always includes links to the first and last pages
integer $size The number of pages to show on either side of the current page
array $pieces The chunks of HTML to create the paginator from - see method description for details

::extend() public

Adds the methods printInfo() and showLinks() to fRecordSet

Signature

void extend( )

::printRecordSetInfo() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Handles the printInfo() method for fRecordSet

Signature

void printRecordSetInfo( fRecordSet $object, string|array $class, array &$records, string $method_name, array $parameters )

Parameters

fRecordSet $object The record set
string|array $class The class(es) contained in the record set
array &$records The records
string $method_name The method that was called
array $parameters The parameters passed to the method

::reset() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Resets the configuration of the class

Signature

void reset( )

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Handles the showLinks() method for fRecordSet

Signature

boolean showRecordSetLinks( fRecordSet $object, string|array $class, array &$records, string $method_name, array $parameters )

Parameters

fRecordSet $object The record set
string|array $class The class(es) contained in the record set
array &$records The records
string $method_name The method that was called
array $parameters The parameters passed to the method

Returns

If the links were shown

Methods

->__construct() public

Accepts the record information necessary for printing pagination

Signatures

fPaginator __construct( integer $records, integer $per_page, integer $page )

fPaginator __construct( fRecordSet $records )

Parameters

integer $records The total number of records
integer $per_page The number of records per page
integer $page The page number

Throws

fNoRemainingException
When there are not records for the specified $page and $page is greater than 1
fValidationException
When the $page is less than 1 or not an integer

->printInfo() public

Prints which records are showing on the current page

Signature

void printInfo( string $template='default' )

Parameters

string $template The template to use

->set() public

Sets data to be available to the templates

Signatures

void set( string $key, mixed $value )

void set( array $data )

Parameters

string $key The key to set
mixed $value The value to set
array $data An associative array of keys and values

Shows links to other pages when more than one page of records exists

Signature

boolean showLinks( string $template='default' )

Parameters

string $template The template to use

Returns

If link were printed