The Last of the Pods Basics: Pagination and Sorting

The Series on Pods has been quite a success so far. I’ve had some back and forth with lots of new people who were itching to give Pods a try, and the series has been quite a bit of help to newcomers. I’m super happy about that, and I’d like to close out the initial push on the series with what I’ll call The Last of the Pods Basics. That is to say, I’d like to go over the last few bits that will really get you up and running with Pods in such a way that you can do even more with both your data as well as your user experience.

As a quick recap, if you haven’t read the first five articles in The Series, you will probably find this article a bit confusing. That said, please make sure you’ve read: An Overview of and Introduction to Pods CMS for WordPress, Pods Basics: Installation and Setup, Pods Basics: Pulling Pods Data to your Theme, Pods UI: The Latest and Greatest Addition to Pods, and How to use Pick Columns (Relationships) in Pods. Being up to speed is essential with this article, as it’s going to build on the system we’ve put in place using the previously published articles. You won’t need to recreate the structure set up in the earlier walk throughs, but knowing the existing implementation will help these instructions remain clear.

Paginated content in Pods

Pods comes with pagination built right in, it’s just a matter of getting it to work the way you want. We’ll begin by flooding the Team Pod we set up previously with a large group of entries. In addition to the Pod setup, I also added Pods UI to help manage the content.

If we were to check out our Team page now, we’d see that the listing has been limited to the default 15 records:

Also by default, Pods doesn’t include any sort of warning that content wasn’t listed. It shouldn’t do that, because Pods does what you tell it to do. You have a few options here. The first would be to change the way we pull the original data. As it stands, we’re using:

<?php
  $team = new Pod('team');
  $team->findRecords('name ASC');
?>

As it turns out, findRecords has more parameters to work with, one of which is the LIMIT we want to use. You can change the default of 15 by defining the $rows_per_page parameter:

<?php
  $team = new Pod('team');
  $team->findRecords('name ASC', 20);
?>

If we were to make that change, we’d see all 16 records we have entered, but would also have the same problem once we breached the new limit of 20. A better solution is to include pagination. We’ll revert back to the default limit of 15, and include our pagination links below the Team listing. It’s even easier than it sounds. After you’ve defined your Pod, you can fire the following anywhere:

<?php echo $team->getPagination(); ?>

getPagnination() basically takes care of everything, and will include the pagination controls where echo‘d:

Here’s the best part, that’s all you’ve got to do. Clicking the second page appends a couple of $_GET variables, reloads the page, and shows you all of your new data. You’re done. There are a few more details concerning getPagination() which will be covered in a subsequent article.

Sorting Pods entries

I’m really excited that the Pods developers are taking so much care with Pods UI. Beyond the inherent user experience improvements it makes, they’re adding features that you can’t even find in WordPress yet. One of my most welcomed additions as of late with Pods UI is the inclusion of drag and drop sorting of Pods entries. Before the functionality was implemented, you had to make a number column in your Pod, and instruct users to use that field to manually order the Pods entries. It was a replication of the limited functionality WordPress offers with Pages. The Pods developers did one better and included such functionality in Pods UI. As with every other aspect of Pods, it’s super easy to integrate, we’ll walk through it quickly.

The first step carries over from the old way of doing things, you’ll need to add a number column to your Pod. We’ll continue working with our Team Pod:

Once the column is added, we’re going to need to modify our theme template to ORDER BY that column as opposed to the name column it’s currently using:

<?php
  $team = new Pod('team');
  $team->findRecords('displayorder ASC');
  $total_members = $team->getTotalRows();
?>

Easy enough. You could actually leave things as is, and your user could manually edit each of the displayorder columns for each Pod entry, but Pods UI makes that so much easier. We’ll need to modify our custom UI plugin and include a few choice flags that will tell Pods UI the details it needs to enable drag and drop sorting. Our revised plugin is as follows:

<?php
/*
Plugin Name: Team Pods UI
Plugin URI: http://example.com/
Description: Customized Pods UI
Version: 0.1
Author: Jonathan Christopher
Author URI: http://jchristopher.me/
*/

function pods_ui_team()
{
  $icon = '';
  add_object_page('Team', 'Team', 'read', 'team', '', $icon);
  add_submenu_page('team', 'Team', 'Team', 'read', 'team', 'team_page');
}

function team_page()
{
  $object = new Pod('team');
  $add_fields = $edit_fields = array(
        'name',
        'position',
        'photo',
        'bio',
        'permalink',
        'eom');
  $object->ui = array(
        'title'   => 'Team',
        'reorder' => 'displayorder',
        'reorder_columns' => array(
             'name'      => 'Name',
             'position'  => 'Position'),
        'columns' => array(
             'name'      => 'Name',
             'position'  => 'Position',
             'created'   => 'Date Created',
             'modified'  => 'Last Modified'
             ),
        'add_fields'  => $add_fields,
        'edit_fields' => $edit_fields
		);
  pods_ui_manage($object);
}

add_action('admin_menu','pods_ui_team');

?>

While it looks very similar to the Pods UI plugin we developed earlier, you’ll want to note the subtle difference:

'reorder' => 'displayorder',
'reorder_columns' => array(
     'name'      => 'Name',
     'position'  => 'Position'),

These new entries are very important, as they enable the sorting itself, as well as tell Pods which column to use when applying the new sort order. When you break it down it’s quite simple. You define reorder with the number column you set up and would like to use to control the sort order, and reorder_columns are the table columns that appear on the reorder page in the WordPress admin. After modifying your plugin with the following, a new element will be included on the listing page:

Clicking that button will reload the page and bring the user to a page dedicated to managing the order of the Pods entries:

Beautiful! Our user can drag and drop to reorder their entries on the fly, click Update Order at the bottom, and everything is taken care of for us.

Pods never disappoints

I hope that these last couple basic features give you enough information to really get started working with Pods. The developers have really put a lot of time, effort, love, and thought into the implementation and I can’t thank them enough. If you’ve found yourself embracing Pods, please take a moment and donate to the project as I know for a fact they’re working night and day to make Pods that much better with every release.

The Pods CMS Series on MBN

This article is the sixth in a series for Monday By Noon dedicated to Pods CMS.

1. An Overview of and Introduction to Pods CMS for WordPress
2. Pods Basics: Installation and Setup
3. Pods Basics: Pulling Pods Data to your Theme
4. Pods UI: The Latest and Greatest Addition to Pods
5. How to use Pick Columns (Relationships) in Pods
6. The Last of the Pods Basics: Pagination and Sorting