Etc pagination - Pagination plugin for Textpattern CMS.

Overview

etc_pagination

Download | Packagist

This Textpattern plugin creates a paginated navigation bar on listings. It has a wide variety of attributes – so you are able to customise it until you drop! It can be used alone for <txp:article /> and <txp:article_custom /> pagination, but it also has the ability to paginate any list, with a little help from etc_query.

Please report bugs and problems with this plugin at the GitHub project’s issues page.

Note that this plugin creates a list that is meant to be styled by you using CSS.

Installing

Using Composer:

$ composer require etc-plugins/etc_pagination:*

Or download the latest version of the plugin from the GitHub project page, paste the code into the Textpattern Plugins administration panel, install and enable the plugin. Visit the forum thread for more info or to report on the success or otherwise of the plugin.

Requirements

  • Textpattern 4.5.0 or newer.

Tags

etc_pagination tag

<txp:etc_pagination />

The etc_pagination tag is a single or a container tag that renders the pagination widget HTML structure.

If used as a container, it must be specified as an opening and closing pair of tags, like this:

<txp:etc_pagination>
    ...contained statements...
</txp:etc_pagination>

Attributes

  • atts="value"
    Additional attributes to apply to the wraptag attribute value.
  • break="value"
    Where value is an HTML element, specified without brackets (e.g., break="li") to separate list items.
  • class="class name"
    HTML class to apply to the wraptag attribute value.
  • current="text"
    A text active on the current tab.
  • delimiter="value"
    A string to use as delimiter in general,current link pairs, see below. Default: , (a comma).
  • first="text"
    Enables you to alter the text inside the ‘first’ link.
  • gap="text"
    One or two delimiter-separated symbols that state that there are more tabs before or after the ones currently viewable. Default: .
  • html_id="id"
    The HTML id attribute assigned to the wraptag attribute value.
  • last="text"
    Enables you to alter the text inside the ‘last’ link.
  • link="text"
    Enables you to alter the text in the titles of the page tabs. If two delimiter-separated strings are given, then the first one will be used on general pages, and the second one on the current page. Default: {*}, where {*} will be replaced by appropriate tab numbers, see ‘Replacements’ section below.
  • mask="value"
    If set, the whole output will be constructed by replacing the patterns {links}, {first}, {last}, {prev}, {next}, {<+} (gap before) and {+>} (gap after) by corresponding strings. Default: unset.
  • next="text"
    Enables you to alter the text inside the ‘next’ link.
  • offset="number"
    Page number offset. Default: 0.
  • page="number"
    An integer to be considered as default page (typically 1).
  • pages="value"
    The total number of pages, or a range start..end, or a delimiter-separated list of page[::title] items. Not needed when paginating <txp:article /> tag (default value).
  • pgcounter="value"
    The URL parameter to drive the navigation. Not needed when paginating <txp:article /> tag. Default: pg.
  • prev="text"
    Enables you to alter the text inside the ‘previous’ link.
  • query="a&b=c"
    A &-separated list of GET parameters to be unset/modified in root.
  • range="number"
    The maximum number of left/right neighbours (including gaps) to display. If negative (default), all pages will be displayed. The plugin tries to avoid ‘nonsense’ gaps like 1 … 3 4 and adjust the output so that the number of displayed tabs is 2*range+1.
  • reversenumberorder="number"
    Makes it possible to reverse the numbers in the tabs. Setting to value to 0 (default) renders 1,2,3,..., setting value to 1 reverses the link numbers, 2 reverses theirs hrefs, and 3 reverses both numbers and hrefs.
  • root="URL"
    The URL to be used as base for navigation, defaults to the current page URL.
  • scale="1"
    An integer to be used as grid for ‘gap’ links.
  • wraptag="element"
    HTML element to wrap (markup) block, specified without brackets (e.g., wraptag="ul").

Replacements

If you are not happy with the default <a> links, use <etc_pagination /> as container to construct your own links. The following replacement tokens are available inside etc_pagination:

  • {$}
    The absolute page number.
  • {#}
    The displayed page number.
  • {*}
    The page title.
  • {current}
    The text given by current attribute, enabled only on the current tab.
  • {href}
    The page URL.
  • {link}
    The text given by link attribute, replaced by first, prev, etc when necessary.
  • {pages}
    The total pages number.
  • {rel}
    The page relation (next, prev).

For example, the following (container tag) will generate a <select> pagination list:

<txp:etc_pagination link="Page {*}" current="selected" wraptag="select" atts='name="pg"'>
    <option value="{*}" {current}>{link}</option>
</txp:etc_pagination

Examples

Example 1
<txp:etc_pagination range="2" prev="Previous" next="Next"  wraptag="ul" break="li" />

This example outputs, if there are ten pages and we are on the third one, like so:

<ul>
    <li>
        <a href="https://example.com/blog/?pg=2" rel="prev">Previous</a>
    </li>
    <li>
        <a href="https://example.com/blog/">1</a>
    </li>
    <li>
        <a href="https://example.com/blog/?pg=2">2</a>
    </li>
    <li>
        <span data-rel="current">3</span>
    </li>
    <li>
        <span data-rel="gap">…</span>
    </li>
    <li>
        <a href="https://example.com/blog/?pg=10">10</a>
    </li>
    <li>
        <a href="https://example.com/blog/?pg=4" rel="next">Next</a>
    </li>
</ul>

The <a> and <span> tags linking to first, prev, current, next, last, gap pages, will be given the corresponding value of rel or data-rel attributes.

Example 2
<txp:etc_pagination range="0">
    <p>Page {*} of {pages}</p>
</txp:etc_pagination>

This example outputs, if there are eight pages and we are on the sixth one, like so:

<p>Page 6 of 8</p>
Example 3
<txp:etc_pagination wraptag="nav" class="paginator" range="3" atts='aria-label="Blog navigation"'
    prev='<a class="prev" rel="prev" href="https://example.com{href}" title="Go to previous page" aria-label="Go to previous page">Prev</a>,
          <span class="prev disabled" aria-label="This is the first page">Prev</span>'
    next='<a class="next" rel="next" href="https://example.com{href}" title="Go to next page" aria-label="Go to next page">Next</a>,
          <span class="next disabled" aria-label="This is the last page">Next</span>'
    link='<li><a href="https://example.com{href}" title="Go to page {*}" aria-label="Go to page {*}">{*}</a></li>,
          <li class="current"><b title="Current page" aria-label="Current page">{*}</b></li>'
    gap='<li><span title="More pages" aria-label="More pages">…</span></li>'
    mask='{prev}{next}
    <ul class="pagination">
        {first}{<+}{links}{+>}{last}
    </ul>'
    />

Fully customised HTML solutions can be achieved – this example outputs, if there are eleven pages and we are on the fifth one, like so:

<nav class="paginator" aria-label="Blog navigation">
    <a class="prev" rel="prev" href="https://example.com/blog/?pg=4" title="Go to previous page" aria-label="Go to previous page">Prev</a>
    <a class="next" rel="next" href="https://example.com/blog/?pg=6" title="Go to next page" aria-label="Go to next page">Next</a>
    <ul class="pagination">
        <li>
            <a href="https://example.com/blog/" title="Go to page 1" aria-label="Go to page 1">1</a>
        </li>
        <li>
            <span title="More pages" aria-label="More pages">…</span>
        </li>
        <li>
            <a href="https://example.com/blog/?pg=4" title="Go to page 4" aria-label="Go to page 4">4</a>
        </li>
        <li class="current">
            <b title="Current page" aria-label="Current page">5</b>
        </li>
        <li>
            <a href="https://example.com/blog/?pg=6" title="Go to page 6" aria-label="Go to page 6">6</a>
        </li>
        <li>
            <span title="More pages" aria-label="More pages">…</span>
        </li>
        <li>
            <a href="https://example.com/blog/?pg=11" title="Go to page 11" aria-label="Go to page 11">11</a>
        </li>
    </ul>
</nav>

etc_numpages tag

<txp:etc_numpages />

The etc_numpages tag is a single helper tag that counts the number of pages in various lists (articles, images, links, …).

This tag is typically used as a pages attribute value, passed to etc_pagination, like this:

<txp:etc_pagination pages='<txp:numpages section="example" />' />

Attributes

Most attributes come from <txp:article /> and other Textpattern list tags:

  • limit="10"
    The default value of pageby, see below.
  • offset="0"
    The number of items to exclude from the beginning of the list.
  • pageby="number"
    The maximum number of items per page.
  • table="txp_table"
    A name of Textpattern database table from which the list will be extracted. Default: textpattern (articles).
  • total="number"
    An optional list length, if known.
  • author, category, excerpted, exclude, expired, id, include, keywords, month, realname, section, status, time
    These attributes have the same function as in txp:article_custom and other list tags.

Examples

Example 1
<txp:if_individual_article>
    <txp:etc_pagination pgcounter="page" pages='<txp:etc_numpages section="news" />' />
</txp:if_individual_article>

This example shows pagination on individual article pages within the news section (i.e., not on an article list context page).

etc_offset tag

<txp:article_custom offset='<txp:etc_offset pgcounter="page" pageby="5" />' limit="5" />

Used as helper tag to calculate the offset of article|image|… listing tags. The example above sets the offset to 15 on a page with ...&page=4 URL, so <txp:article_custom /> will display the fourth page of 5 articles.

Attributes

  • pageby="10"
    The number of items per page.
  • pgcounter="pg"
    The URL variable to be considered as page number.
  • offset="0"
    An optional page offset.
  • type="value|page|start|end"
    Outputs either the raw (escaped) value of pgcounter, or the calculated page number, or the start page item number, or the end page item number.

Examples

Example 1
Showing articles <txp:etc_offset type="start" /> to <txp:etc_offset type="end" />

Outputs Showing articles 21 to 30 on the third page of the standard <txp:article /> list.

Authors/credits

Written by Oleg Loukianov and inspired by ob1_pagination. Many thanks to all additional contributors.

You might also like...
Rah backup - Takes backups from Textpattern CMS installations

rah_backup Packagist | Twitter | Donate Rah_backup keeps your important site safe from disastrous events. Rah_backup is an admin-side backup utility p

Rah sitemap - XML sitemap generator for Textpattern CMS

rah_sitemap Packagist | Issues | Donate Sitemap plugin for Textpattern CMS. Generates Sitemaps.org XML sitemaps for your site, which help Google and o

Rah memcached - Store parts of Textpattern CMS templates in Memcached

rah_memcached Packagist | Issues | Donate A plugin for Textpattern CMS that stores parts of your templates in Memcached, a distributed in-memory key-v

Oui player - Manage configurable media players in @Textpattern CMS

oui_player Introduction An extendable plugin to easily embed customized audio and video players. . This plugin does not use oembed, it builds iframe e

Rah comments - Paginated article comments list for Textpattern CMS

rah_comments Download | Packagist | Issues | Support forum | Donate Rah_comments lets you to paginate Textpattern CMS’ comment lists, splitting the lo

Rah privileges - Configure Textpattern CMS' user-group privileges through Preferences panel

rah_privileges Packagist | Donate Configure admin-side user-group permissions from Textpattern CMS’ preferences panel. Install Using Composer: $ compo

Pat eu cookies law - 🌝 EU Cookie Law Compliance: A Textpattern plugin (or standalone script) for Third-Party Cookies (RGPD compliance)
Pat eu cookies law - 🌝 EU Cookie Law Compliance: A Textpattern plugin (or standalone script) for Third-Party Cookies (RGPD compliance)

pat_eu_cookies_law EU Cookie Law Compliance: A Textpattern plugin (or a standalone script) for Third-Party Cookies. A simple solution that respects th

Pat if amp - ⚡ A Textpattern Conditional Plugin for Google's Accelerated Mobile Pages Project (AMP)
Pat if amp - ⚡ A Textpattern Conditional Plugin for Google's Accelerated Mobile Pages Project (AMP)

pat_if_amp Download | Packagist AMP pages for Textpattern CMS. This conditional tag examines the URL of the current page and determines if the URL end

Oui cookie - Cookie management plugin for @Textpattern

oui_cookie Introduction Set, check, read, reset or delete cookies manually or through GET/POST parameters. . According to the EU legislation, some coo

Comments
  • offset error

    offset error

    Hi Oleg I tryed your last version of etc-pagination using the example given in your website but got this error on firdst page and lats page: (I used the plugin from your website not github 0.4.5)

    Erreur de balise : <txp:etc_pagination range="2" prev="Prec." next="Suiv." wraptag="ul" break="li" class="pagination text-center" pages='<txp:variable name="numPages" />' pgcounter="page" /> -> Notice: Undefined offset: -1 lors du traitement du module “Aucun” dans le gabarit “2016”

    below the code i used:

    <txp:etc_pagination range="2" prev="Prec." next="Suiv." wraptag="ul" break="li" class="pagination text-center" pages='<txp:variable name="numPages" />' pgcounter="page" />

    <txp:article_custom category='<txp:variable name="cat" />' wilaya='<txp:variable name="wilaya" />' limit="10" sort="custom_5 desc, Title asc" form="search1" offset='<txp:etc_offset pgcounter="page" pageby="10" />' />

    <txp:variable name="numPages"><txp:etc_numpages category='<txp:variable name="cat" />' wilaya='<txp:variable name="wilaya" />' pageby="10" /></txp:variable>

    I tryed to fix it myself but havent succeeded. (txp 4.5.7)

    Cheers.

    opened by dragondz 2
  • Notice and error: Undefined index: url while_parsing_page_form

    Notice and error: Undefined index: url while_parsing_page_form

    Using v0.5 of etc_pagination with PHP 7+ (tested with 7.0 and 7.3) and the current 4.8 dev (24 July 2019) version I get the following notice in debug mode.

    Notice: Undefined index: url while_parsing_page_form: default, pagenav_article_list

    It seems like it's not processing this line: https://github.com/etc-plugins/etc_pagination/blob/master/etc_pagination.php#L87 or perhaps not even the callback to the function https://github.com/etc-plugins/etc_pagination/blob/master/etc_pagination.php#L82.

    dmp-ing the output produces nothing.

    If I shift the definition of $etc_pagination['url'] to the top of function etc_pagination after the global statement, the error is dismissed and dmp produces the correct context-specific url for the pagination links.

    Long shot: might this have something to do with the new /textpattern/plugins directory? You mentioned some plugins might be affected.

    opened by jools-r 1
Releases(0.5.0)
Owner
null
Textpattern-for-Panic-Coda - A Textpattern CMS mode for Panic Coda

Textpattern elements for Panic Coda 2 Handy elements for use with Panic Coda 2 on a Mac when authoring files for the Textpattern CMS. This repository

Phil Wareham 8 Jun 26, 2017
Textpattern-installer - Textpattern plugin and theme installer for Composer

Textpattern Installer for Composer Package directory | Issues Install plugins and themes to Textpattern CMS with Composer. $ composer require rah/rah_

Jukka Svahn 7 Apr 14, 2022
Ied plugin composer - Inspired Plugin Composer: Create, publish and edit plugins from within Textpattern CMS.

ied_plugin_composer Create, publish and edit plugins from within Textpattern CMS. Creates a new page under the Extensions tab where you can edit and e

Stef Dawson 8 Oct 3, 2020
MassPlugCompiler - Textpattern CMS plugin compiler

mtxpc mtxpc compiles Textpattern CMS plugin sources into installer packages. Supports multi-file structure and a JSON manifest file. Install Using Com

Jukka Svahn 5 Apr 15, 2022
Rah cache minify - HTML compressor module for rah cache Textpattern CMS plugin

Minify module for rah_cache This is a minify module for rah_cache, a full-page caching solution for Textpattern CMS. Rah_cache_minify will minify HTML

Jukka Svahn 1 Feb 13, 2014
Smd imagery - A Textpattern CMS plugin for managing images in the Write panel.

smd_imagery Insert images into your Write panel. Very handy for people who run photoblog or image-heavy sites, or those who categorise images for incl

Stef Dawson 5 Nov 15, 2022
Zem contact reborn - An extensible HTML form mailer plugin for Textpattern CMS.

com_connect Contents Introduction Installing and upgrading Migrating from zem_contact_reborn Usage Tags com_connect tag com_connect_text tag com_conne

Textpattern CMS 23 Dec 8, 2021
Smd tags - A Textpattern CMS plugin for unlimited, structured taxonomy across content types.

smd_tags Tag articles, images, files and links with stuff, then use the public-side tags to display the lists, filter or find related content. Feature

Stef Dawson 4 Dec 26, 2022
Rah comment spam - Comment anti-spam plugin for Textpattern CMS

rah_comment_spam Packagist | Issues | Donate Rah_comment_spam provides customizable anti-spam tools for Textpattern CMS’ comment system. Set minimum a

Jukka Svahn 2 Apr 24, 2022
Tom image grid - Plugin for Textpattern CMS : An optionnal grid display for images tab

tom_image_grid tom_image_grid is a plugin for Textpattern CMS. It allows a more compact display (as a grid) of the images list. The plugin adds two bu

Thomas Jund 5 Jun 30, 2019