README.txt in Pagerer 7

Pagerer
=======

Pagerer is a module providing a collection of pager themes to enhance Drupal
and Views standard pagers.

Administrators or site builders can preset multiple pager configurations. Each
'preset' allows a pager to be made up of three 'panes': left, center, and
right. Each pane can contain (or not) a pager theme. In this way there is
plenty of possibilities to combine different elements to satisfy complex
requirements.

Pagerer allows to override Drupal's core pager with any of the preset
configurations. Also, a built-in pager plugin for Views allows to use any of
the preset pagers within any view.

Pagerer uses standard Drupal pager classes to render the pagers, so styling
is preserved.

Module developers can also make direct calls to the themes, thus allowing
even more complex scenarios.

Features:
---------
- multi-pane pager
- Views pager plugin
- control whether to display links to pages, to items, or to item ranges
- direct input of the page to go to through an input widget
- selection of the page to go to through a jQuery UI slider
- selection of the page to go to through a client-side scrolling pager
- links to progressively more distant pages (like +10, + 20, +100, +200)
- adaptive logic links
- specify text to be used to render page separators (like a vertical bar)
  and page breakers (like an ellipsis)
- supports Views' AJAX enabled pager

Themes:
-------
pagerer_standard - alike standard Drupal pager theme
pagerer_progressive - provides links to pages progressively more distant
                      from current
pagerer_adaptive - provides links to pages following an adaptive logic
pagerer_mini - minimal pager, providing direct page entry
               (requires jQuery Update module)
pagerer_scrollpane - provides page navigation through a scrolling pager
                     (requires jQuery Update module)
pagerer_slider - provides page navigation through a jQuery UI slider
                 (requires jQuery Update module)
pagerer - a multi-pane (left, center, and right) pager theme, enabling
          each pane to contain one of the themes above

Requirements:
-------------
- Drupal 7
- the Views pager plugin integrates with Views 3
- jQuery update module (for pagerer_mini, pagerer_scrollpane and pagerer_slider
  themes)
- for Microsoft Internet Explorer browsers, the pagerer_slider and
  pagerer_scrollpane themes require IE 9+

Instructions:
-------------
- Install and enable the module.
- Check the Configuration page to setup.
- Create and configure any number of 'preset' pagers.
- Select a preset to use as a general replacement of Drupal core pager, or
  use a preset as a pager in Views.

Views pager plugin:
-------------------
The pager plugin for Views introduces a new 'Paged output, Pagerer' option in
the list of possible pagers to be used for a view.
It behaves like a 'full pager', with the additional option to select the
Pagerer preset to be used for rendering the pager - so that every view could
use a different preset, but also many views could use the same preset.

Credits:
--------
- The 'pagerer_mini' theme concept and javascript code are to a large
  extent the same of the 'Minimax pager' module for Drupal 6 (i.e. proudly
  copied, thanks mattyoung).
- The animated preloader icon for the jQuery slider widget in timelapse mode
  was generated by http://preloaders.net.
- The use of jQuery queuing for the scrollpane animation was inspired by Ben
  Nadel's blog post http://www.bennadel.com/blog/1864-Experimenting-With-jQuery-s-Queue-And-Dequeue-Methods.htm



Themes
======

----------------------
theme_pagerer_standard
----------------------
This theme is alike standard Drupal pager theme.

Provides links to the 'neigborhood' of current page, plus
first/previous/next/last page. Extended control on the pager is available
through Pagerer's specific variables.

-------------------------
theme_pagerer_progressive
-------------------------
This theme provides links to pages progressively more distant from current.

Besides links to the 'neigborhood' of current page, creates a list of
links which are progressively more distant from current page, displaying
either a page number or an offset from current page.

This is controlled via the 'progr_links' theme variable, which can take
a value either 'absolute' or 'relative'.

Examples:

page 9 out of 212, progr_links 'absolute', display 'pages':
-------------------------------------------------------------------
1 . 4 . 7 8 [9] 10 11 . 14 . 19 . 59 . 109 . 212
-------------------------------------------------------------------

page 9 out of 212, progr_links 'relative', display 'pages':
-------------------------------------------------------------------
1 . -5 . 7 8 [9] 10 11 . +5 . +10 . +50 . +100 . 212
-------------------------------------------------------------------

The 'factors' theme variable controls the quantity of progressive links
generated. Each value in the comma delimited string will be used as a
scale factor for a progressive series of pow(10, n).

Examples: 'factors' => '10' will generate links for page offsets

  ..., -1000, -100, -10, 10, 100, 1000, ....

'factors' => '5,10' will generate links for page offsets

  ..., -1000, -500, -100, -50, -10, -5, 5, 10, 50, 100, 500, 1000, ....

etc.

----------------------
theme_pagerer_adaptive
----------------------
This theme provides links to pages following an adaptive logic.

Besides links to the 'neigborhood' of current page, creates page links
which are adaptively getting closer to a target page, through subsequent
calls to the links themselves. More or less, the principle is the same
as of the binary search in an ordered list.

On a first call, the theme creates links to a list of pages in the
neighborood of first page, plus a link to last page, plus links to 2
pages in the space between first and last page:
- one to the middle,
- one to the middle of the space between the first page and the one above

Example - current page in square brackets:

page 1 out of 252:
-------------------------------------------------------------------
[1] 2 3 4 5 . +62 . +125 . 252
-------------------------------------------------------------------

On subsequent calls, if a link outside of the neighborhood (nicknamed
'adaptive link') is called, then we will assume that the 'target' page
looked for is comprised within the interval between the pages to the
left and to the right of the link invoked. So, the theme will restrict
the range of the pages to be presented in the pager by setting these
pages as the min and max boundaries (plus first and last page, which are
always displayed to 'release' the restriction), and recalculating the
middle and middle-of-the-middle to present the new links.

Example (following on from above):

click on +62, go to page 63 and lock page 5 (represented as -58 from 63)
and 126 (represented as +63 from 63) as new boundaries:
-------------------------------------------------------------------
1 . -58 . -31 . -15 . 61 62 [63] 64 65 . +15 . +31 . +63 . 252
-------------------------------------------------------------------
note how also the space on the left is filled in with links having same
absolute offset as the ones to the right.

and so on, click on -15, go to page 48 and lock page 32 (represented as
-16 from 48) and 61 (represented as +13 from 48):
-------------------------------------------------------------------
1 . -16 . -8 . -4 . 46 47 [48] 49 50 . +4 . +8 . +13 . 252
-------------------------------------------------------------------

Like for the 'pagerer_progressive' theme, links are displayed either as
a page number or as an offset from current page. This is controlled via
the 'progr_links' theme variable, which can take a value either
'absolute' or 'relative'.

------------------
theme_pagerer_mini
------------------
This theme displays current page (or item), and provides a direct page
entry widget to allow navigating to another page.

Examples:

page 9 out of 955, display 'pages':
-----------------------
<< < Page 9 of 955 > >>
-----------------------

page 9 out of 955, total items = 47731, limit = 50, display = 'items':
---------------------------
<< < Item 401 of 47731 > >>
---------------------------

------------------------
theme_pagerer_scrollpane
------------------------
This theme displays a standard pager that is scrollable on the browser
through navigation buttons. Users can get to any page link without having
to send request to the server.

--------------------
theme_pagerer_slider
--------------------
This theme displays a jQuery slider. Page navigation is managed via
javascript.


pagerer_xxxx themes' variables
==============================

Pagerer themes' variables array differs, to some extent, from standard
Drupal core pager theme variables.

- tags: an associative array of tags to be used to render the pager, see
  details in section below (note: this is different from Drupal 'tags'
  variable in the pager theme!)
- element: same as Drupal, an optional integer to distinguish between
  multiple pagers on one page.
- parameters: same as Drupal, an associative array of query string
  parameters to append to the pager links.
- quantity: the number of pages in the list of the 'neighborhood' of the
  current page. For pagerer_slider theme, it serves to approximate the witdh
  of the jQuery slider.
- display_restriction: it allows to restrict showing the pager based on the
  actual number of pages in the result set. It can take the values "default"
  (pager is shown if the result set is made of at least two pages), "one_above"
  (pager is shown also if the result set is made of one page only), "none"
  (pager is shown also if the result set is empty).
- display: can take the values 'pages', 'items', 'item_ranges'. Determines
  whether to display pages, or items, or item ranges.
- label_display: Determines whether and where to render a text "label"
  element (e.g. "Page:"). Options are "none" (not displayed),
  "before_current" (in front of current page), "first" (at the beginning),
  "last" (at the end).
- current_display: Determines how the current page is rendered in the pager.
  Options are "none" (not displayed), "normal" (as a text), "widget" (an active
  input box from where users can enter directly a page to go to), "slider"
  (as a slider), "scrollpane" (as a scrolling pane embedding a full pager).
- total_display: Determines whether and where to render a text element
  indicating the total pages (or items). Options are "none" (not
  displayed), "after_current" (just after current page), "first" (at the
  beginning), "last" (at the end).
- first_link: Determines when to render a link to the first page (e.g.
  "<< first"). Options are "never" (not displayed), "not_on_first"
  (not displayed if current page is the first), "always" (always displayed).
- previous_link: Determines when to render a link to the previous page
  (e.g. "<< previous"). Options are "never" (not displayed), "not_on_first"
  (not displayed if current page is the first), "always" (always displayed).
- next_link: Determines when to render a link to the next page (e.g.
  "next >"). Options are "never" (not displayed), "not_on_last" (not
  displayed if current page is the last), "always" (always displayed).
- last_link: Determines when to render a link to the last page (e.g.
  "last >>"). Options are "never" (not displayed), "not_on_last" (not displayed
  if current page is the last), "always" (always displayed).
- progr_links: pagerer_progressive and pagerer_adaptive themes only. These
  pagers render links to pages far from the current. Select whether to render
  these links as "absolute" page numbers (or items/item ranges) or as
  "relative" offsets from current (e.g. "+10 +100 +1000").
- factors: pagerer_progressive theme only. Comma delimited string of factors
  to use to determine progressive links.
- pager_breaker: Text to render a break in the page sequence.
- pager_separator: Text to fill between contiguous pages. If 'none', no
  separators are rendered.
- range_separator: Text to place between first and last item in a range.
- fl_breakers: (internal) Determine if breakers (...) need to be rendered
  between the first/previous/next/last links and the sequence of page numbers
  that build the pager.

Advanced:
- widget_resize: Determines if the widget width should be calculated
  dynamically based on the width of the string of the last page/item number.
  Set to 'false' to keep a fixed width as set by styling. Default: 'true'.
- slider_action: Determines how the page relocation should be triggered after
  it has been selected through the jQuery slider. Options are: "tickmark"
  (page relocation only occurs after user clicks a tickmark on the slider
  handle), "timelapse" (page relocation occurs after a grace time has elapsed),
  "auto" (the timelapse method is automatically selected based on the accuracy
  of the slider).
- slider_action_timelapse: The grace time (in milliseconds) to wait before the
  page is relocated, in case "timelapse" slider_action method is selected for
  the jQuery slider. "0" will trigger relocation immediately.
- slider_navigation_icons: Determines whether to display +/- navigation icons
  on the sides of the jQuery slider. Options are "yes", "no", "auto" (the icons
  are automatically displayed based on the accuracy of the slider).

pagerer theme variables
=======================

The 'pagerer' theme itself is more a container of individual
pagerer_xxxx themes. The theme to be used in each pane (left, center,
and right) and its variables are either retrieved from a defined preset
through the 'preset' variable, or passed to a {position}_pane variable
of the pagerer theme.

- element: same as Drupal, an optional integer to distinguish between
  multiple pagers on one page.
- parameters: same as Drupal, an associative array of query string parameters
  to append to the pager links.
- preset: (optional) specifies the preset pager configuration, created through
  Pagerer's admin UI, to be used to render the pager. If not specified,
  {position}_pane variables are to be passed. Also, any {position}_pane
  variables will override the preset configuration, if specified along the
  preset variable.
- {position}_pane: where {position} is 'left'|'center'|'right', an associative
  array of
    - theme_name: 'pagerer_standard' | 'pagerer_progressive' |
      'pagerer_scrollpane' | 'pagerer_adaptive' | 'pagerer_mini' |
      'pagerer_slider' | 'none'
    - theme_variables: the $variables associative array for the theme passed
      in 'theme_name'


The 'tags' variable in Pagerer
==============================

The 'tags' variable in pagerer_xxxx themes is an associative array of
tags to be used to render any of the textual elements of the pager. It
differs from Drupal core pager 'tags' variable, which is a simple array.
Any of the textual elements specified can contain a '@number' and/or a
'@total' placeholder that at runtime will be replaced respectively with
the target page and the total number of pages in the pager. If the pager
is set to display 'items' or 'item ranges', the replacement will be with
the corresponding element.

- page: Text to use to render the target page/item/item range. Defaults
  to: '@number'.
- first: Text to use to render the link to the first page (e.g. "<<
  first").
- previous: Text to use to render the link to the previous page
  (e.g. "< previous").
- next: Text to use to render the link to the next page (e.g. "next >").
- last: Text to use to render the link to the last page (e.g. "last >>").
- previous_progr: pagerer_progressive and pagerer_adaptive themes only.
  Text to use to render the link to a previous page outside of the
  neighborhood (e.g. "-100"). Defaults to: '-@number'.
- next_progr: pagerer_progressive and pagerer_adaptive themes only. Text
  to use to render the link to a next page outside of the neighborhood
  (e.g. "+100"). Defaults to: '+@number'.
- total: Text to use to render the total pages/items on the pager. Defaults
  to: 'of @total'.

- page_label: Text to use to render a 'page' label. Defaults to: 'Page'.
- item_label: Text to use to render a 'item' label. Defaults to: 'Item'.
- item_range_label: Text to use to render a 'items range' label. Defaults
  to: 'Items'.

- pageset_empty: Text to use to render the current page in the pager in case
  there are no items in the pageset (e.g. 'No pages to display').

- page_title: Help text used when hovering a page link (e.g. 'Go to page
  @number').
- first_title: Help text used when hovering a first page link (e.g. 'Go to
  first page').
- previous_title: Help text used when hovering a previous page link (e.g.
  'Go to previous page').
- next_title: Help text used when hovering a next page link (e.g. 'Go to
  next page').
- last_title: Help text used when hovering a last page link (e.g. 'Go to
  last page').

- widget_title: Help text used when hovering the direct input widget (e.g.
  'Enter page, then press Return.').
- slider_title: Help text used when hovering the slider (e.g. 'Drag the handle
  to the page required.').
- slider_tickmark_title: Help text appended to the slider help when user is
  expected to click on the tickmark to start page relocation. Defaults to:
  'Then, click on the tickmark.'.


An example for overriding 'tags' at a theme's level
===================================================

Themers can override pager text elements by implementing in the theme's
template.php a hook_preprocess_pagerer_xxxx() function to set the 'tags'
values needed. xxxx should be replaced with the specific pagerer theme
you want to address.

Example:

function mytheme_preprocess_pagerer_mini(&$variables) {
  $variables['tags']['first'] = t('<< foo');
  $variables['tags']['previous'] = t('< bar');
  $variables['tags']['next'] = t('baz >');
  $variables['tags']['last'] = t('qux >>');
}