How to use Pick Columns (Relationships) in Pods

NOTE: This tutorial series is extremely out of date, please see http://pods.io/tutorials/

In this edition of the Pods CMS Series, we’re going to cover Pick Columns. If you haven’t read the first articles in the series, I would highly recommend it as this article assumes basic knowledge of the workings of Pods. Please make sure you’ve read Pods Basics: Installation and Setup, Pods Basics: Pulling Pods Data to your Theme, and Pods UI: The Latest and Greatest Addition to Pods before continuing.

As defined by the Pods developers:

A relationship column is essentially a select list containing items from the related type. If you create a column in one pod that relates to another pod, “event”, then in the edit form you’ll see a select list with all “event” items.

This is really great for us, because it means that any Pod can effectively make use of another Pod or WordPress resource such as a Page. It opens the doors to quite a few things that were more difficult to achieve using a combination of standalone WordPress plugins.

When would you want to use relationships?

When it comes to learning, I always find it better to explore by example. If a technology is applied to a real-life situation (or something very close to that) I find it much easier to fully understand.

Perhaps the most basic use of a Pick column would be to make a link between a Pod entry and a WordPress Page. One example of a situation in which this makes sense is a promotional area. Using Pods, you could set up an area to manage any number of promotions, and have them link directly to a specific WordPress Page.

How to implement a Pick Column

We’ll continue with our Promotions example and create a quick Pod to handle the data. We’ll set it up like this:

With our Promotions Pod set up, let’s add a sample entry to see how the Pick column works:

It’s as easy as that! Pods will automatically pull the active list of WordPress pages, so you don’t have to worry about anything being out of date or inaccurate when it comes to pulling the needed permalink on the front end. Once we’ve saved the Pod entry, let’s go ahead and integrate it into our sidebar. For the demo, I’m just going to work within the default WordPress theme. In sidebar.php:

<?php
  $promos = new Pod('promotion');
  $promos->findRecords(null, 1);       
  $total_promos = $promos->getTotalRows();
?>

<?php if( $total_promos > 0 ) : ?>
    
  <?php while ( $promos->fetchRecord() ) : ?>

    <?php
      // set our variables
      $promo_name = $promos->get_field('name');
      $promo_copy = $promos->get_field('copy');
      $promo_link = $promos->get_field('link');
           
      $promo_link = get_permalink($promo_link[0]['ID']);
    ?>
        
    <div id="promo">
      <h4><?php echo $promo_name; ?></h4>
      <p><?php echo $promo_copy; ?></p>
      <p><a href="<?php echo $promo_link; ?>">Find out more!</a></p>
    </div>
    <!-- /promo -->

  <?php endwhile ?>
    
<?php endif ?>

What we’re doing here is first pulling our Pod data. If a record is found, we’re going to process it. Everything is standard practice until it comes to our Pick column. Since we chose the relationship to be a WordPress page, Pods is going to give us an array with which to work. What’s great is that the array consists of variables we’re already familiar with by working with WordPress pages. We’re provided the entire set of data we expect:

Array
(
    [0] => Array
        (
            [ID] => 29
            [post_author] => 1
            [post_date] => 2010-01-01 00:00:00
            [post_date_gmt] => 2010-01-01 00:00:00
            [post_content] => 
            [post_title] => Package 3
            [post_excerpt] => 
            [post_status] => publish
            [comment_status] => open
            [ping_status] => open
            [post_password] => 
            [post_name] => package-3
            [to_ping] => 
            [pinged] => 
            [post_modified] => 2010-01-01 00:00:00
            [post_modified_gmt] => 2010-01-01 00:00:00
            [post_content_filtered] => 
            [post_parent] => 23
            [guid] => http://localhost/wp/?page_id=29
            [menu_order] => 0
            [post_type] => page
            [post_mime_type] => 
            [comment_count] => 0
        )

)

Nice, right? Using that data we can completely integrate the Promotion copy to include a link directly to the page selected in the Pick column. Done, and done:

By all means, that’s the most basic way to implement the promotion, you can provide additional fields that allow the user to define the promo link text and more.

Creating relationships with other Pods

Being able to make a connection with a WordPress Page is awesome, you can also establish these relationships with WordPress Posts, WordPress Users, and even WordPress Categories. Pods also lets you link your Pods to one another. Let’s continue with our Promotion example.

Perhaps the website you’re building out has a lot of promotions. So many that you’d like to randomly pull a promotion from a group of promotions at any given time. With Pick columns we can make that happen. The first thing we’ll do is set up a Promotion Categories Pod. All we need is the most basic structure to work with:

Then we’ll add a couple categories, one of which can be Winter Specials:

Once our categories are added, we’ll need to add another Pick column to our original Promotions Pod:

The last step on the setup side of things will be to add a few promos and categorize them:

Once we have our new categorized library of promotions, we can go ahead and revise our sidebar to include only those categorized as being for the winter. To do so, we’re going to use a specific SQL syntax provided by Pods:

<?php
  $promos = new Pod('promotion');
  $promos->findRecords('rand()', 1, 'category.name = "Winter Specials"');       
  $total_promos = $promos->getTotalRows();
?>

<?php if( $total_promos > 0 ) : ?>
    
  <?php while ( $promos->fetchRecord() ) : ?>
  
    <?php
      // set our variables
      $promo_name = $promos->get_field('name');
      $promo_copy = $promos->get_field('copy');
      $promo_link = $promos->get_field('link');
      
      $promo_link = get_permalink($promo_link[0]['ID']);
    ?>
    
    <div id="promo">
      <h4><?php echo $promo_name; ?></h4>
      <p><?php echo $promo_copy; ?></p>
      <p><a href="<?php echo $promo_link; ?>">Find out more!</a></p>
    </div>
    <!-- /promo -->
  
  <?php endwhile ?>
    
<?php endif ?>

The change to notice here is the WHERE bit we’ve added to the findRecords() function call. That statement restricts the results to have a chosen category of Winter Specials in our Pick column. Tied in with the ORDER BY rand() snippet, we have a rotating, random, categorized set of promotions from which to pull.

Again, this is just a most basic implementation of relating one Pod to another, but it really opens up the door for lots of options when it comes to content management!

Integration with Pods UI

When writing Pods UI: The Latest and Greatest Addition to Pods I did my best to convey how helpful Pods UI is when it comes to presenting Pods to actual users. Your Pods are presented in such a way that the user recognizes the structure you’ve set up even quicker than before, and you’re able to better organize that presentation. Pick columns raise that bar even higher.

Before Pods UI, it was a bit cumbersome to explain how one Pod was related to another when Pick columns were involved. Now, with Pods UI, you can group related Pods into the same section in the navigation, providing a visual link between the two (or more) for the user. Circling back to our promotions example, we can now group the Promotions Pod itself alongside the Promotion Categories for easy maintenance:

To get this listing, simply install Pods UI, and create your own separate plugin file:

<?php
/*
Plugin Name: Promotions 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_promos()
{
  $icon = '';
  add_object_page('Promos', 'Promos', 'read', 'promos', '', $icon);
  add_submenu_page('promos', 'Promos', 'Promos', 'read', 'promos', 'promos_page');
  add_submenu_page('promos', 'Categories', 'Categories', 'read', 'categories', 'categories_page');
}

function promos_page()
{
  $object = new Pod('promotion');
  $add_fields = $edit_fields = array(
                    'name',
                    'slug',
                    'copy',
                    'link',
                    'category');
  $object->ui = array(
                    'title'   => 'Promotion',
                    'columns' => array(
                              'name'      => 'Name',
                              'category'  => 'Category',
                              'created'   => 'Date Created',
                              'modified'  => 'Last Modified'
                              ),
                    'add_fields'  => $add_fields,
                    'edit_fields' => $edit_fields
					);
  pods_ui_manage($object);
}

function categories_page()
{
  $object = new Pod('promotion_category');
  $add_fields = $edit_fields = array(
                    'name',
                    'slug');
  $object->ui = array(
                    'title'   => 'Category',
                    'columns' => array(
                              'name'      => 'Name',
                              'created'   => 'Date Created',
                              'modified'  => 'Last Modified'
                              ),
                    'add_fields'  => $add_fields,
                    'edit_fields' => $edit_fields
					);
  pods_ui_manage($object);
}

add_action('admin_menu','pods_ui_promos');

?>

Again, grouping related Pods can help exponentially when it comes to showing this new system to actual users. It reduces the learning curve quite a bit, and really helps people hit the ground running.

This is just the beginning when it comes to Pick columns, in future articles I’ll cover the more advanced attributes of this feature, but understanding these fundamentals will help you get started.

The Pods CMS Series on MBN

This article is the fifth 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