etc_pagination

29 January 2013, 12:51

Keywords: paginate, navigation, bar, link, page

Based on the orphaned ob1_pagination plugin, etc_pagination inherits most of its features and adds wraptag, break and some other attributes. 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.

Paginating <txp:article /> is as straightforward as <txp:etc_pagination />. To illustrate more features, we will go with <txp:article_custom category="tips" /> sorted by Title. The goal is to paginate records by 3 and obtain a navigation bar. Below is the desired result:

to

Now let us see the solution.

Counting pages

First of all, we need to know the total number of pages. This is often the trickiest part, but <txp:etc_numpages /> makes it easier since it has the same attributes that <txp:article_custom />:

<txp:variable name="numPages" value='<txp:etc_numpages category="tips" pageby="3" />' />

will return the number of (published, not yet expired) live articles from “tips” category, paged by 3 articles.

Pagination bar

We pass this number to etc_pagination, that is customizable enough to produce any type of navigation bar:

<txp:etc_pagination pages='<txp:variable name="numPages" />' pgcounter="page"
	range="3" link="Page {*}" prev="Prev" next="Next" break=" | " />

<txp:etc_pagination pages='<txp:variable name="numPages" />' pgcounter="page" range="0">
	You are on the page {*} out of {pages}. Showing articles <txp:etc_offset pgcounter="page" pageby="3" type="start" /> to <txp:etc_offset pgcounter="page" pageby="3" type="end" />.
</txp:etc_pagination>

Final step

Now the navigation bar is ready, but we still have to display the records corresponding to the url page parameter. This is usually done by setting limit and offset attributes of txp tags:

<txp:article_custom category="tips" sort="Title" form="article_listing"
	limit="3" offset='<txp:etc_offset pgcounter="page" pageby="3" />' />

Customize the output

If you prefer a select combo instead of links, that’s easy too:

<txp:etc_pagination pages='<txp:variable name="numPages" />' pgcounter="page"
	link="Page {*}" current="selected"
	wraptag="select" atts="name='page'"
>
	<option value="{*}" {current}>{link}</option>
</txp:etc_pagination>

Customize even more

The pages attribute accepts a list of links[::titles] to be used in the construction:

<txp:etc_pagination pgcounter="month" break=" | " root=""
	pages="2012,2013,2014" page="2013" />

will produce

2012 | 2013 | 2014

You can also produce ranges of links and redirect pagination to any page:

<txp:etc_pagination pages="A..Z" pgcounter="alpha" break=" | " range="5"
	page="" root="http://www.iut-fbleau.fr/projet/etc/index.php?id=30" />

Test cases

<txp:etc_pagination pages="1789" pgcounter="page" range="3"
	prev="Prev,Prev" next="Next,Next" scale="10" break=" | " />
| 1 | | 406 | 407 | 408 | | 1789 | 
<txp:etc_pagination pages="10" pgcounter="page" range="3"
	prev="Prev,Prev" next="Next,Next" break=" | " reversenumberorder="1" />
<txp:etc_pagination pages="Z..A" pgcounter="page" range="5"
	page="A" first="" last="" break=" | " />
<txp:etc_pagination
	pages='<txp:article_custom break=",">
		<txp:article_id />::<txp:title />
	</txp:article_custom>'
	pgcounter="id" range="3" wraptag="ul" break="li" />

File(s)