Pods Basics: Pulling Pods Data to your Theme

Published 6 years 6 months ago on January 4, 2010 — 13 min read

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

If you haven’t had a chance to read the first two articles in the series, I would definitely suggest taking a few minutes to read both An Overview of and Introduction to Pods CMS for WordPress as well as Pods Basics: Installation and Setup. There are details discussed in each article explaining how we’ve worked our way to this stage, pulling data from Pods into our theme.

Pods Pages

Pods comes standard with a feature called Pods Pages baked right in. There is a ton of documentation available in the User Guide, and an entire section set up in the Pods admin screens:

Pods Pages in the Pods admin

While I’m really impressed with the Pods Pages implementation, I actually prefer not to use it. Instead, I like to integrate Pods itself into my theme files. I like to work with my hands a bit dirty when it comes to plugins, and would rather work with PHP itself in my favorite text editor the way I normally would when developing a WordPress theme. Thankfully, Pods has done a fantastic job with supporting developers like me. For the time being, we’re going to skip the Pages section of the Pods admin, and crack open our template files themselves.

Setting up our Team page

For the purposes of this example, I’m going to work with the default WordPress theme that ships with every download. I’m going to create a really generic template that we can work with:

<?php

/* Template Name: Team */

get_header(); ?>

  <div id="content" class="narrowcolumn" role="main">

    <?php if (have_posts()) : while (have_posts()) : the_post(); ?>
    <div class="post" id="post-<?php the_ID(); ?>">
    <h2><?php the_title(); ?></h2>
      <div class="entry">
        
        <?php the_content(); ?>
        
        <h2>Our Team</h2>
        
        <?php
          $team = new Pod('team');
          $team->findRecords('name ASC');       
          $total_members = $team->getTotalRows();
        ?>
        
        <?php if( $total_members>0 ) : ?>
          <?php while ( $team->fetchRecord() ) : ?>
            
            <?php
              // set our variables
              $member_id        = $team->get_field('id');
              $member_name      = $team->get_field('name');
              $member_position  = $team->get_field('position');
              $member_photo     = $team->get_field('photo');
              $member_bio       = $team->get_field('bio');
              $member_eom       = $team->get_field('eom');

              // data cleanup
              $member_bio       = wpautop( $member_bio );
              $member_photo     = $member_photo[0]['guid'];
            ?>
            
            <div class="member" id="member<?php echo $member_id; ?>">
              <h3><?php echo $member_name; ?></h3>
              <h4><?php echo $member_position; ?></h4>
              <?php if( !empty( $member_photo ) ) : ?>
                <img src="<?php echo $member_photo; ?>" alt="Photo of <?php echo $member_name; ?>" />
              <?php endif ?>
              <?php echo $member_bio; ?>
            </div>
            <!-- /member -->
            
          <?php endwhile ?>
        <?php endif ?>
          
      </div>
    </div>
    <?php endwhile; endif; ?>
  
  </div>

<?php get_sidebar(); ?>

<?php get_footer(); ?>

At first glance, it may look like there is a ton going on here but once we break it down, you won’t be very intimidated, I promise!

From a really high level, we’re working with a very basic WordPress template file here. The interesting bits begin with:

$team = new Pod('team');

This is huge! What we’re doing here is defining $team as a Pods object, ready to interact with the data we’ve entered. When we fire:

$team->findRecords('name ASC');

We’re calling a Pods function that lets us directly work with the existing data. If you check out the User Guide for findRecords you’ll discover the various parameters available to us. We can control the order in which the data is returned, the number of records per page, limit the returned data based on certain criteria, and even use our own SQL to pull the data. In this example, the only parameter we’re passing orders the returned data by our name column. A ton of power lies in findRecords, and subsequent articles will cover much of what you can do when pulling your Pods data.

When we fire:

$total_members = $team->getTotalRows();

We’re giving ourselves a reference to check against that tells us just how many records are in the current Pod. This allows us to run a conditional to check whether we even need to continue any further:

if( $total_members>0 )
{
	// work with our data
}

Once we’ve established that we do indeed have data with which to work, we get to the other really exciting part of Pods:

<?php while ( $team->fetchRecord() ) : ?>
            
  <?php
    // set our variables
    $member_id        = $team->get_field('id');
    $member_name      = $team->get_field('name');
    $member_position  = $team->get_field('position');
    $member_photo     = $team->get_field('photo');
    $member_bio       = $team->get_field('bio');
    $member_eom       = $team->get_field('eom');
  
    // data cleanup
    $member_bio       = wpautop( $member_bio );
    $member_photo     = $member_photo[0]['guid'];
  ?>

<?php endwhile ?>

We’re running a couple of Pods-specific functions here that you’ll want to become familiar with:

fetchRecord
Retrieves the next record from our $team object
get_field
Retrieves the data for a specific column (referenced by its given name when the Pod was created)

So what we’re doing with this while is looping through all available records in our Team Pod. We’ve only hit this loop because of the preceding conditional that checked to make sure there was at least one record in the first place. Each field is assigned to a variable for future reference. We’re also able to format the data should the need arise. For example, when it comes to paragraph columns, I like to fire wpautop to ensure the markup is cleaned up a bit prior to my use.

Note: File upload columns return an array no matter what when get_field is fired. The array consists of a number of fields, guid being the actual location of the file, and more than likely the most common field you’ll be using.

As it stands, we’ve defined all the variables we’d like to work with, so it’s a matter of dumping them out as you would any other time:

<div class="member" id="member<?php echo $member_id; ?>">
  <h3><?php echo $member_name; ?></h3>
  <h4><?php echo $member_position; ?></h4>
  <?php if( !empty( $member_photo ) ) : ?>
    <img src="<?php echo $member_photo; ?>" alt="Photo of <?php echo $member_name; ?>" />
  <?php endif ?>
  <?php echo $member_bio; ?>
</div>
<!-- /member -->

Giving each Team member a dedicated page

While it’s great that we can pull all this data in any way we’d like, Pods lets us take things even further by taking advantage of the slug column we set up and implemented. First, you’ll need to confirm that you’ve properly set up your .htaccess file, and permalinks are working properly. This is essential. The next thing we’ll need to do is make a quick change to our (now) Team index page:

<?php

/* Template Name: Team */

get_header(); ?>

  <div id="content" class="narrowcolumn" role="main">

    <?php if (have_posts()) : while (have_posts()) : the_post(); ?>
    <div class="post" id="post-<?php the_ID(); ?>">
    <h2><?php the_title(); ?></h2>
      <div class="entry">

        <?php the_content(); ?>

        <h2>Our Team</h2>

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

        <?php if( $total_members>0 ) : ?>
          <ul>
            <?php while ( $team->fetchRecord() ) : ?>

              <?php
                // set our variables
                $member_id        = $team->get_field('id');
                $member_name      = $team->get_field('name');
                $member_position  = $team->get_field('position');
                $member_slug      = $team->get_field('permalink');
              ?>

              <li>
                <a href="<?php echo get_permalink(); ?><?php echo $member_slug; ?>/">
                  <?php echo $member_name; ?> - <?php echo $member_position; ?>
                </a>
              </li>

            <?php endwhile ?>
          </ul>
        <?php endif ?>

      </div>
    </div>
    <?php endwhile; endif; ?>

  </div>

<?php get_sidebar(); ?>

<?php get_footer(); ?>

Instead of looping through our data and dumping out everything on a single page, we’ll now have an unordered list including list items containing the team member name and position, linking to his unique URL by using the automatically generated slug Pods has provided. If you save this revised template, you’ll see that the team members are listed properly, but clicking his link results in a 404 page not found. That’s because we haven’t told Pods to take over when it comes to these links. This is where we’ll return to Pods Pages.

Click Pods in the left hand WordPress admin navigation, and select Pages from the top of the resulting page, we’re going to Add new page:

Adding a new Pods Page

Giving your Pods Page the proper name is essential, so mind your spelling, and make sure your page name is acceptable. Of particular note here is the /* portion of our Page name. Since team/ has already been claimed, we’re going to let WordPress have it. We only want to use this Pods Page when we’re trying to view a particular Team member page, hence the wildcard. When naming Pages with a wildcard, Pods will recognize that it should look for anything with team/ in the URL, followed by another URL segment.

Once you’ve created the team/* page, we’ll need to create a new WordPress template.

Alternative Pods Pages setup

In this case, I opted to set up the Team index page as a WordPress page. Alternatively, we could have set up a new Pods Page named team, defined our template file, and continued without problem. I sometimes prefer to add the ‘index’ type pages as WordPress pages depending on the client, as well as the other pages of the site. I’ll usually create an index page as a WordPress page so I can still make use of the user defined title and content, and dump out the Pods data after that. Sometimes, however, you won’t want the client adding their own content to the page. If that’s the case, it would make sense to create the index page as a Pods Page instead of a WordPress Page.

Setting up our Team member template

We’ve got our Team index template, but we haven’t yet told Pods which template to use for our team/* page. Let’s create it:

<?php

/* Template Name: Team - Member */

get_header(); ?>

  <?php

    $found_member = false;

    global $pods;
    $member_slug  = pods_url_variable(-1);
    $member       = new Pod('team', $member_slug);

    if( !empty( $member->data ) )
    {
      $found_member = true;

      // set our variables
      $member_id         = $member->get_field('id');
      $member_name       = $member->get_field('name');
      $member_position   = $member->get_field('position');
      $member_photo      = $member->get_field('photo');
      $member_bio        = $member->get_field('bio');
      $member_eom        = $member->get_field('eom');
      
      // data cleanup
      $member_bio        = wpautop( $member_bio );
      $member_photo      = $member_photo[0]['guid'];
    }
  ?>

  <div id="content" class="narrowcolumn" role="main">

    <?php if( $found_member ) : ?>

      <div class="post" id="post-<?php echo $member_id; ?>">
        <h2><?php echo $member_name; ?></h2>
        <div class="entry">
          <h4><?php echo $member_position; ?></h4>
          <?php if( !empty( $member_photo ) ) : ?>
            <img src="<?php echo $member_photo; ?>" alt="Photo of <?php echo $member_name; ?>" />
          <?php endif ?>
          <?php echo $member_bio; ?>
        </div>
      </div>

    <?php else: ?>
	
      <div class="post">
	    <h2>Team Member Not Found</h2>
	    <div class="entry">
	      <p>Sorry, that Team member could not be found!</p>
	    </div>
	  </div>
	
    <?php endif ?>
  
  </div>

<?php get_sidebar(); ?>

<?php get_footer(); ?>

Save this as a new template file. As a result of the AJAX nature of Pods, we’ll need to ‘cycle’ the Pods Pages page by hitting Pods in the sidebar, choosing Pages from the tabs up top, and choosing our newly created team/* from the dropdown. Our Page will load, and the field we’ll need to pay particular attention to is the -- Page Template -- dropdown in the lower right. Select our newly created Team - Member entry and click Save changes:

Adding a new Pods Page

You can now head back to our team index, hit a link in our Team list, and check out the new one-off page for each Team member!

A few new things are happening in this template. We’ll focus on the following snippet:

global $pods;
$member_slug  = pods_url_variable(-1);
$member       = new Pod('team', $member_slug);

First, we need to bring in the global $pods; variable; we’ll need it. Pods has a nice function available called pods_url_variable() that lets us pull URL segments and use them as variables. We know that the last segment on this page is going to be our Team member slug, so we’ll go ahead and set that.

When we fire:

global $pods;
$member_slug  = pods_url_variable(-1);
$member       = new Pod('team', $member_slug);

We’re passing that slug as a parameter when initially defining our Pods object. Under the hood, Pods is pulling a record from the database that has a permalink that matches the string we’re passing. Wicked handy. Since we’re basing our data on the passed slug, we’re going to need to consider the possibility of an invalid URL, we can use a quick conditional:

if( !empty( $member->data ) )
{
  // dump our data
}

There are a number of ways you can check to see if a record is returned, just make sure you have a fallback in place. Once we know that we have data to work with, we can fire get_field() and pull whatever we need. Easy peasy.

The Pods CMS Series on MBN

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

Copyright © 2006—2016 Jonathan Christopher