Textpattern CMS support forum

You are not logged in. Register | Login | Help

#1 2010-05-04 11:00:47

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 8,611
Website

List pagination

TXP has <txp:newer> and <txp:older> tags to step through pages of results in sequence (article lists, category lists, search results, image galleries, etc) but this — at least to me — still feels inherently blogish.

What if there was a lightweight, flexible Textpattern core tag that allowed you to build direct navigation for your lists and allowed you to display page information such as result counts, number of pages, etc? Would that be useful, or is it bloat and should be plugin territory?

I’ve written what I consider a small and pretty lightweight solution (~70 lines of code). You can try it out if you like. Just paste that code into your publish/taghandlers.php file (above the function newer is a good spot) and upload it.

[EDIT: functionality altered to take account of jsoo’s comments

If you then wanted to display, for example:

Results: 38. Page 5 of 8
2 · 3 · 4 · 5 · 6 · 7 · 8

You can write this:

Results: <txp:paging item="result_total" />.
Page <txp:paging item="page, pages" break=" of " link="0" />
<txp:paging item="prev, page, next" break=" &middot; "
     wraptag="div" class="direct_nav" range="3" />

Each page number is linked to its direct page of results. Note that on page 5 here, you can see 3 ‘pages’ before and after the current one — as governed by the range attribute.

How about this kind of thing:

First « 3 4 5 6 7 8 » Last 

You can get a bit more clever here:

<p class="direct_nav">
<txp:paging item="first" linktext="First" />
<txp:newer showalways="1">&laquo;</txp:newer>
<txp:paging item="prev" break="&nbsp;" range="2" />
<txp:paging item="page" link="0" />
<txp:paging item="next" break="&nbsp;" range="3" />
<txp:older showalways="1">&raquo;</txp:older>
<txp:paging item="last" linktext="Last" />
</p>

That will render all items (except the current page 5) with links to the direct results page. Notice this time we’ve used prev and next separately and set independent ranges so you only see two pages before and three after the current page.

With this tag you have the flexibility to slice and dice the page info any way you see fit. Here’s the attribute list to save you having to grok the code:

  • item : one or more of the following:
    • page the current page number
    • pages the total number of pages in the result set
    • result_total the number of results (articles, images, search results, etc) in the set, taking any offset into account
    • grand_total the absolute total number of items in the set (excluding offset)
    • first first page number
    • last last page number
    • prev list of page numbers before the current page
    • next list of page numbers after the current page
  • link whether to link (add an anchor to) the items in the type list. Default: 1
  • linktext the text to use for the item(s) in the type list. Default: the item itself
  • url whether to display the URL of any link instead of a formatted anchor. Useful if making your own anchors. Default: 0
  • range the number of pages to show in prev / next. Default: 2
  • wraptag / class / break / html_id / escape have their usual connotations. Note that ‘break’ is also applied between items in prev and next

At the moment, the default type is page, although there may be something better to use as a default.

So, what do you say? Is this small enough and TXPish enough to be in the core? Is paging the right name for the tag? Should any changes be made to its functionality? For those that try it out, does it work as advertised? Who can create the funkiest pagination system with it? Or should I make it into a tiny pagination plugin to (probably) succeed ob1_pagination?

Last edited by Bloke (2010-05-10 23:41:45)


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

#2 2010-05-04 11:38:47

Dragondz
Moderator
From: Algérie
Registered: 2005-06-12
Posts: 1,303
Website

Re: List pagination

Hi Bloke

Good job, I think it s important to have a pagination intem into core.

Question : is the pagination work also with article_custom?

Cheers

Last edited by Dragondz (2010-05-04 11:39:04)

Offline

#3 2010-05-04 12:03:11

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 8,611
Website

Re: List pagination

Dragondz wrote:

is the pagination work also with article_custom?

No :-( TXP itself disallows pagination inside article_custom.

From a (site) developer’s perspective, article_custom just returns a fixed list of ‘stuff’ (articles) based on your selection criteria. That tag iterates over your list to display content so in theory it can iterate over it in batches. The only reason I can think of for the restriction is that if you mix and match article and article_custom tags on a single page (which is pretty common) then your pagination would break as it wouldn’t know which page you were referring to when you navigate the lists.

This is an inherent inflexibility in TXP’s paging system which only has one URL variable available to the whole page: pg. Perhaps if this was lifted so that each item could register its interest to be paginated in a unique way (some reference to the tag or a dedicated paging variable per tag) then the problem goes away.

fwiw, I solved this conundrum in smd_gallery but it’s not easily applicable here.

Last edited by Bloke (2010-05-04 12:16:00)


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

#4 2010-05-04 12:44:55

Dragondz
Moderator
From: Algérie
Registered: 2005-06-12
Posts: 1,303
Website

Re: List pagination

Dont worry Stef,

When I have this kind of prblem (paginating article_custom), i use a custom solution (txp:variable with adi_calc), but should be great if this can be done directly using core tag.

But if only fiew people are intersted by that feature, dont care about, i can deal with.

Good job man, keep coding.

Offline

#5 2010-05-04 14:23:48

thebombsite
Plugin Author
From: Exmouth, England
Registered: 2004-08-24
Posts: 3,251
Website

Re: List pagination

Nice one Stef. I’m using Jeff Soo’s soo_page_numbers plugin a heck of a lot these days with my WP ports. WP has this kind of paging built-in already so I’m all for having something similar in Txp.

What with the new image tags that will be 2 plugins I won’t require any more. :)

Last edited by thebombsite (2010-05-04 14:24:53)


Stuart – The BombsiteProText ThemesTextgarden

In a Time of Universal Deceit
Telling the Truth is Revolutionary.

Offline

#6 2010-05-04 17:40:41

THE BLUE DRAGON
Member
From: Israel
Registered: 2007-11-16
Posts: 558
Website

Re: List pagination

Bloke wrote:

:-(

+1 !
I use rss_suparchive for paging lists.
And for the paging status+page-numbers I use soo_page_numbers
But I will tray your new codes in my next site.
is it requires PHP5 ? (like soo_page_numbers)

Offline

#7 2010-05-04 19:50:29

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 8,611
Website

Re: List pagination

THE BLUE DRAGON wrote:

is it requires PHP5 ? (like soo_page_numbers)

Nope. Runs on a stock TXP with PHP4.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

#8 2010-05-04 19:55:51

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,781
Website

Re: List pagination

I’m all for including better pagination in core (and Gil, Stef’s code is PHP4 compatible) and this is a great start. A few observations:

Terminology could be terser. Call it paging or pagination instead of paging_info. (More accurate, I think, as well as shorter.) Use first and last instead of first_page and last_page. (Maybe use next and prev instead of next_pages and prev_pages.) Leave off category and section as those already have their own tags.

I’d make link enabled by default.

I’m not crazy about the name offset here. limit, maybe.


Code is topiary

Offline

#9 2010-05-05 07:58:58

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 8,611
Website

Re: List pagination

jsoo wrote:

Terminology could be terser.

All good points, thanks. I did consider calling it pagination at first but since it can also return article counts and such like I wasn’t sure if it was misleading. Maybe not. First/last/next/prev make sense, so I’ll do that.

I only included ctype/category/section because they happened to be in $thispage. If you’re inside a list context of some description (an image_list, for example) then I can’t remember if category is set to the category of the context or the URL context (I suspect the latter — will check). And of course, section doesn’t make sense unless you’re building your own URLs. I think you’re right so I’ll drop those two (three?) unless anyone can come up with a convincing argument why they should stay.

I also spent a while deciding over making link on by default or not. My only reason for leaving it off was because the default value I chose for type was grand_total which doesn’t make sense to have a link made out of it. If the default type was changed to something else then I guess link should be on as well. I guess it depends if you’re primarily going to be using it for displaying “Page N of M / R Results” displays, or nav stuff. If it’s on by default it annoys one camp to have to turn it off every time, and vice versa. Unless the logic inside the function can be improved such that you can’t make a link out of something other than a page number?

And finally, offset. I know what you mean, it’s not quite ‘right’ to call it an offset even though it’s an offset either side of the current page. limit too has other connotations but it’s perhaps a better fit. width might also be a contender but that could be confusing. I notice you use window_size in soo_page_numbers. In this case the ‘width’ of the nav is really +/- a set amount from the central point and I couldn’t find a current attribute that fitted any better than offset; nor could I think of a new one that accurately described what the attribute did. Anybody have any bright ideas here?


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

#10 2010-05-05 10:35:41

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 8,611
Website

Re: List pagination

I’ve updated the tag in light of (most of) jsoo’s comments. Please re-download it from the first post (might have to force-refresh your browser). The inital post has been altered to note the changes made. Here’s a brief rundown:

  • tag now called <txp:paging />
  • type attribute is now called item
  • these items have been renamed:
    • first_page => first
    • last_page => last
    • prev_pages => prev
    • next_pages => next
  • items section, category and ctype have been removed
  • default item is now page
  • link is now on by default
  • link only takes effect on things that link to page numbers (i.e. page_results and grand_total cannot be linked)
  • html_id attribute added
  • fixed a small bug in the ctype rendering of links

The offset attribute remains until we can come up with some better name / functionality for it.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

Board footer

Powered by FluxBB