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: 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'. - 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 >>'); }