How to use Pick Columns (Relationships) in Pods

Posted: January 11, 2010 Comments(21)

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:

Setting up our Pick column in Pods

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

Data entry for a Pick column

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:

Promotion on the front end

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:

Promotion Categories Pod setup

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

Adding a promo category

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

Revising our Promotions Pod

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

Adding a Winter Special

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:

Custom Pods UI for our promos

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

Get my newsletter

Receive periodic updates right in the mail!

  • This field is for validation purposes and should be left unchanged.

Comments

  1. Is there a way that I can create a new pod (lets say called expenses)
    That had a broken down list of expenses (say for food, lodging, misc)
    and have it total in my main pod, potentially giving them the option to drill down to see the actual expenses?

  2. The code in the sidebar is not working as written now. Perhaps with the plug-ins being update the default values have changed.

    ERROR
    $promos->findRecords(null, 1);

    WORKED
    $promos->findRecords();

    Thank you for the series, I had a lot of fun going through all of your articles.

  3. Is it possible to create new members of a Pod whilst creating another member? For example, we have Movies and Actors. Whilst creating a Movie, I would like to be able to create the Actors. As it stands, I have to create the Actors first to be able to add them to the Movie.

  4. Hi, thanks for all the useful information. I have a slight problem in that I want to use a variable in my Where clause but this is not working:

    $submenu->findRecords($orderby = ‘position ASC’, -1, ‘category.name = “$category_name”‘);

    There is a variable named category_name on the page and it works if I put a specific value in rather than the variable, so I am wondering why it would not work once I changed to the variable.

  5. Thanks Jonathan. Great article.

    Does it work on 3.1?

    I understand it has some advantages over WordPress inbuilt custom types but what worries me is the project stability and life. We all know WordPress plugins life cycle is generally limited.

  6. Yes, Pods works with WordPress 3.1. Pods is extremely active and will be getting even more active when 2.0 comes out, I wouldn’t worry about plugin life cycle at this point, Pods is just getting started.

  7. I’m trying to use a variable in the findRecords function and I can’t get it to work. I want to only show records that match a URL variable. So I pull that variable off of the URL, store it in $rider, and then I have findRecords(‘t.slug’=”%$rider%”‘). This won’t return any results, even though I echo the contents of $rider and it is storing information correctly. Can you not use variables in the findRecords function?

  8. Yes you can definitely use variables in findRecords, your issue is actually coming from the % occurrences in your query. If you take those out you should be good to go.

  9. How would the query in your example look like if we could select multiple categories?
    Example: one promotion belongs to several categories and I want to get all promotions from one category. What is the query?

Leave a Reply

Your email address will not be published. Required fields are marked *