Forum OpenACS Development: ANN: tools::paginate

Posted by Jon Griffin on
I am releasing my new streamlined version of a paginator called: tools:paginate.

You can get it at

It fixes the non-scalabilty problem with my original and also fixes the lack of being able to do proper sorts with the ad_table/paginator combo.

It combines both and is super simple to use. It also is css aware (but does use tables for layout for now)

It is in production and has been fine. As always YMMV and I would appreciate any patches.

2: Re: ANN: tools::paginate (response to 1)
Posted by Matthew Walker on

this looks great. When I try to get the tcl procs files I get an internal server error for tools-procs.tcl and a page not found error for the db ones. I can get the db ones if I strip the .tcl extension from the filename but I suspect the tools-procs.tcl file is actually being evaluated and failing.


3: Re: ANN: tools::paginate (response to 1)
Posted by Jon Griffin on
Sorry about that, I had a typo in the urls.<p>
Try it again and I renamed the .tcl .tcl.txt.
4: Re: ANN: tools::paginate (response to 3)
Posted by Matthew Walker on
I've got it now, there's just one typo in your sample code on line 21 of the tcl script. There needs to be a backslash to escape the " after the href= I'm guessing this is why your linked sample isn't working either.
5: Re: ANN: tools::paginate (response to 1)
Posted by Jade Rubick on
Jon, what is a paginator? The web page does not make this clear. Perhaps it is something obvious, but for me it wasn't.
6: Re: ANN: tools::paginate (response to 1)
Posted by Jarkko Laine on

Paginating means that you show only a certain amount of entries from some list on a page and offer then links to next (and prev) page with another x entries, and so on.

One example of this is the user directory in

If I understood correctly, Lars' new list builder supports pagination, too. I don't know what is its relationship with Jon's widget, though.

7: Re: ANN: tools::paginate (response to 1)
Posted by Jon Griffin on
I don't know exactly what Lars added, but he did use the patches that I mentioned a while ago.

If Lars did use the existing template::paginate and ad_table then there is at least one serious limitation and that is that sorting only works on the returned result set not the whole data set.

My version is not only much simpler, it doesn't use caching and also sorts the whole result set before it is returned. It is also written from scratch. It is not a feature complete replacement yet, but it is good enough for everything I have come across and Brad Duell is also enhancing this with me for our project.

8: Re: ANN: tools::paginate (response to 1)
Posted by Jon Griffin on
Thanks to Brad Duell, many enhancements and cleanups have been performed.

You can now use bindvars in the querystring and he generalized the limits (get recnum 10 - 50) proc to use outside the paginate proc.

He also added exclude variables, extra vars, images for prev/next page, and extra code to be executed before the line of code is shown.

9: Re: ANN: tools::paginate (response to 1)
Posted by Robert Locke on
Jon, is there any reason not to include this in the main toolkit (if it hasn't already)?


10: Re: ANN: tools::paginate (response to 1)
Posted by Robert Locke on
Hi Jon,

Found time to experiment with your code today and found that I couldn't get it to work with OACS4.6.3/PG7.2.4 without making various changes (perhaps I picked up an old version from your web page?):

* In tools-procs.tcl, in the "::tools::paginate" proc, I had to alias the sub-selects in both "get_record_count" queries by adding "as x".  Otherwise, PG bombs.  I'm not sure if this breaks Oracle, but it certainly breaks our rule of not allowing queries in .tcl files. =)

* The "tools::paginate_sql.get_limit" PG query from tools-procs-postgresql.xql is broken.  It needs to alias the sub-select (using "as x") and it incorrectly uses the PG limit/offset clause.  I think it should read:

    select * from
    ($query) as x limit $max_display offset [expr $start -1]

* The "tools::paginate.get_context" PG query from the same file uses:
    substr(upper($context_field), 0, 1)
which by definition returns nothing in PG.  I'm assuming you wanted to return the 1st character or:
    substr(upper($context_field), 1, 1)
Also, it would be cool if you could pass in the number of letters for the context (for very large lists).

* The above fix produces a nifty alphabetical navigation bar, but clicking on the different letters doesn't do anything.  Should there be code in the sample ".tcl" file that uses "objects_context" to limit the query?  Or should that logic be added to "tools-procs.tcl"?

* In your sample ".tcl", you need to escape the double-quote at the beginning of \"edit-object...

* The sample ".xql" file does not use the "objects_orderby" clause and should probably read:

    select object_id,
    object_type,to_char(creation_date,'MM/DD/YYYY HH:MI') as creation_date
    from acs_objects a
    order by $objects_orderby

* Is reverse ordering supposed to work when clicking on a column header twice?

Other than those issues, the paginator is very cool and I would be willing to help out in any way.

Should I work on the above items and just send you a patch?

11: Re: ANN: tools::paginate (response to 1)
Posted by Jorge Garcia on
It's possible to use 'paginator' _without_ using tables?

We are triying to use 'divs' and not tables.

Anyone knows any mean to paginate with 'paginator', or another code, without using tables or ad_table?

Any thoughts?


12: Re: ANN: tools::paginate (response to 1)
Posted by Jon Griffin on
You can also return the values and it won't return tables. See the docs.
13: Re: ANN: tools::paginate (response to 1)
Posted by Jon Griffin on
I made the changes and pulled that query out of the .tcl (don't remember leaving that in there).
Thanks for your help and input. Let me know what you think and if you test it and it works I will put it in the OACS tree.
14: Re: ANN: tools::paginate (response to 13)
Posted by Robert Locke on
Hi Jon,

Thanks! I think we're almost there. I will send you my version via email which has a few changes:

  • The URLs for the context markers include the current page number. However, if you click on a context marker (say, the letter "C") and that context has fewer pages than your current page (in say the "ALL" context), you will get a blank list. So, for generating context markers, I changed the call to build_url to exclude the ${name}_page variable.
  • The "-query" parameter to "tools::paginate" wasn't working properly (-queryname works fine). The problem was it calls:
    uplevel ... [db_string get_record_count_dynamic { *SQL* }]}
    But, at the template parse level, get_record_count_dynamic doesn't exist in any *.xql files. So, I changed this to do a db_map and then pass the query string directly to the uplevel'ed db_string call.
  • Made minor changes to the tools-*.xql files in support of the above changes.
  • The offset in tools-postgresql.xql should be [expr $start - 1], not $start (eg, if $start is the 11th, then you want to set the offset to 10 so that PG skips the first 10 records).
  • Your sample "index.tcl" file includes a call to "lset" which I think is a Tcl proc. Perhaps change it to standard Tcl so folks don't trip on it and give up before they get to see how darn cool your paginator is. =)
  • Outstanding bug: If you click on a context marker, you lose all the other context markers. Here's an example from your sample page: Perhaps we should move the context logic into tools-procs.tcl? Will investigate.
  • I haven't tested anything under Oracle yet. Can you do that?
Your paginator rocks!

15: Re: ANN: tools::paginate (response to 1)
Posted by Jon Griffin on
I made yet another update, added Robert's patches and some other stuff to prepare for sorting ascending and descending.
Also took out the 2 inline queries and put them into .xql files like I should have originally but forgot.
Added a tarball option on the doc.