List pagination

Bloke · 2010-05-04 11:00:47

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)

Dragondz · 2010-05-04 11:38:47

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)

Bloke · 2010-05-04 12:03:11

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)

Dragondz · 2010-05-04 12:44:55

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.

thebombsite · 2010-05-04 14:23:48

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)

THE BLUE DRAGON · 2010-05-04 17:40:41

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)

Bloke · 2010-05-04 19:50:29

THE BLUE DRAGON wrote:

is it requires PHP5 ? (like soo_page_numbers)

Nope. Runs on a stock TXP with PHP4.

jsoo · 2010-05-04 19:55:51

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.

Bloke · 2010-05-05 07:58:58

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?

Bloke · 2010-05-05 10:35:41

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.

Gocom · 2010-05-05 11:53:42

Looks cool. I’m not really sure about the error supression tho. Isset check? It might be slower tho and works differently with NULL, right?

As I said, and I say again, it’s cool. Bit differently from most TXP tags. There is no loop with globals, and functions returning the global.

What about if_first/last?

function if_paging_last($atts,$thing) {
	global $thispage;
	/*
		Context check here?
	*/
	return parse(EvalElse($thing,(
		$thispage['pg'] <= $thispage['numPages']
	)));
}
function if_paging_first($atts,$thing) {
	global $thispage;
	return parse(EvalElse($thing,(
		!$thispage['pg'] or $thispage['pg'] == 1
	)));
}

And like for the actual pagination too. Wouldn’t require more than some global lifting to the loop and those function code. I’m not really sure if that code is helpful, like first and last page, but that for the pagination would. Same tags could be used too.

Something like:

$thispage['pg'] = $theItem;

To the loop or something and it kinda starts to work.

Last edited by Gocom (2010-05-05 12:05:48)

jsoo · 2010-05-05 12:41:51

Bloke wrote:

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?

window_size is simply a holdover from the old rsx_ plugin on which I initially based mine; I don’t suggest using it here. width, size, or range are the best short choices I can think of at the moment.

Textpattern CMS

Textpattern CMS support forum

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

List pagination

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

Re: List pagination

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

Re: List pagination

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

Re: List pagination

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

Re: List pagination

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

Re: List pagination

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

Re: List pagination

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

Re: List pagination

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

Re: List pagination

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

Re: List pagination

#11 2010-05-05 11:53:42

Re: List pagination

#12 2010-05-05 12:41:51

Re: List pagination

Board footer