Welcome to the fourth part of our series on writing Views query plugins! I hadn't planned on writing a fourth installment, but after a couple of people asked to see how pagers could be implemented, I couldn't resist putting an example together. As a reminder, we have been building a query plugin to interact with Flickr groups. You can read the first, second, and third installments in the series and find the code on GitHub.
Before we start
There are three pieces of data you need in order to implement a pager:
- The number of items to display per page
- The total number of items available
- What page of items you are currently displaying
Most modern APIs support paginated queries, and in general this shouldn't be a problem. If the API you are working with does not support paging, it's possible to retrieve the full set of results and handle paging yourself in the plugin. That approach takes a lot more work, and careful implementation to avoid performance problems: Building the pager that way is outside the scope of this article.
Thankfully, the Flickr API which we have been working with supports paging. We are good to go!
Implementing the pager
Once you know that your API supports paging, adding the code to your query plugin is surprisingly easy. You need to implement the following steps:
- Initialize the pager
- Retrieve the settings for items per page and current page
- Perform your query
- Save the total number of results back to the pager
Here is how it looks in our plugin
// Setup pager
$view->init_pager();
$flickr = flickrapi_phpFlickr();
$photos = $flickr->groups_pools_getPhotos($this->options['group_id'], NULL, NULL, NULL, NULL, $this->pager->options['items_per_page'], $this->pager->current_page + 1);
$this->pager->total_items = $photos['photos']['total'];
$this->pager->update_page_info();
The first thing we do is call init_pager() on our view. This not only does setup work on our pager, but gives us a copy of it in our query plugin at $this->pager.
Now that the pager is setup, we can use its settings in our query. In the Flickr API call for groups.pools.getPhotos, the sixth and seventh parameters are the number of items per page and the current page. So for those parameters we have specified $this->pager->options['items_per_page'] and $this->pager->current_page + 1. Note that +1 for the current page, we need that because Drupal's pages are zero-based but Flickr's are not.
Once this query is executed, we can retrieve the total number of items from the result and save that back to the pager by setting the total_items property and calling update_page_info().
Amazingly, that is all you have to do! You should now have a nice pager when you view your results.
As an added bonus, back in Part 3 of the series, we implemented a configuration option which controls how many photos are displayed. Now that we have the pager setup, we can remove that configuration option, because the pager option "Display a specified number of items" will handle that for us.
Gotcha
I know what some of you are saying. "What about the offset option?" Unfortunately the Flickr API does not support this option. If I really wanted to, I could override the existing pager plugins and remove the option from the form so that users would not be confused by it. However, I will leave that as an exercise for the reader. In the meantime, any entry of an offset will simply be ignored.
Looking for more?
What else would you like to see implemented in our query plugin? Let me know, and maybe the series will continue!