In order to set up front end visible archive pages for Custom Taxonomies, everything begins with the rewrite slug attached to your Custom Taxonomy. This can be edited using the Custom Rewrite Slug field provided by Custom Post Type UI. Some planning is required on your part, but the plan must take into consideration the Page structure currently implemented.

So far, we’ve based our Cameras Custom Post Type on the slug of /cameras/. This works out well as our Custom Post Type houses information based on DSLR Cameras. We’ve set up an index-style page that sits at /cameras/, and our single pages are stored under /cameras/%postname%/. We’ve just now included a Custom Taxonomy, and we’d like to include that in the mix as well.

Out of the box taxonomy permalinks

By default, a Custom Taxonomy rewrite slug is based on the Taxonomy Name. Considering our Brands Custom Taxonomy, we might expect the Taxonomy listing would be made available at /cameras/brands/%taxonomyname%/; unfortunately that’s not the case. Given the Taxonomy being a default implementation, we’d actually find the listing at /brands/%taxonomyname%/. You’ll also note that any Cameras we’ve marked under a particular brand will show up in the listing. For example, if we navigated to http://wordpress/cpt/brands/canon/, we’d be faced with a page resembling:

This listing behaves just like a regular Posts archive page would, and that’s because it’s literally based on the archive.php template file of your theme. While it works, it’s not ideal. Thinking ahead, if you have multiple Custom Post Types along with WordPress posts, there isn’t much segmentation when it comes to actually viewing archive pages on the front end.

Take into consideration the possibility of us expanding our content by also including a Custom Post Type for Flashes. If we were to use a Custom Taxonomy for Flash Brands (as opposed to Camera Brands) with that Custom Post Type as well, we’d have overlapping entries and it would quickly become unorganized as results for both flashes and cameras would turn up when viewing http://wordpress/cpt/brands/canon/ which isn’t always desirable.

At this point it’s important to note the specificity of a Custom Post Type/Custom Taxonomy implementation. There is a strong possibility that you very well may want to merge Canon flashes and cameras in your archive pages, but you may not. For the purpose of example, we’re going to deem it necessary to segment the two. To accomplish that, you’ll need to beef up the rewrite slug for your Custom Taxonomies.

Customizing your Custom Taxonomy template

When dealing with taxonomies, WordPress looks for specific theme files. As with other theme files, templates for Custom Taxonomies can be based on the taxonomy name, in this case brands. Create a file called taxonomy-brands.php in your theme directory, WordPress checks for this file before hitting archive.php which can allow you to make the front end more custom. As an example, we’ll use the following for our taxonomy-brands.php:

<?php get_header(); ?>

  <?php $term = get_term_by( 'slug', get_query_var( 'term' ), get_query_var( 'taxonomy' ) ); ?>
  <div id="container">
    <div id="content" role="main">

      <h1 class="page-title"><?php echo $term->name; ?> Archives</h1>

      <?php if (have_posts()) : ?>
        <?php while (have_posts()) : the_post(); ?>

          <div class="post type-post hentry">
            <h2 class="entry-title">
              <a href="<?php echo get_permalink(); ?>" title="<?php the_title(); ?>" rel="bookmark">
                <?php the_title(); ?>
              </a>
            </h2>

            <div class="entry-meta">
              <span class="meta-prep meta-prep-author">Posted on</span>
              <a href="<?php echo get_permalink(); ?>" title="<?php the_time( 'g:i a' ); ?>" rel="bookmark">
              <span class="entry-date"><?php the_time( 'F j, Y' ); ?></span></a>
            </div><!-- .entry-meta -->

            <div class="entry-summary">
              <?php the_excerpt(); ?>
            </div><!-- .entry-summary -->
          </div>

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

    </div><!-- #content -->
  </div><!-- #container -->

  <?php get_sidebar(); ?>
<?php get_footer(); ?>

This file is based on category.php with a few modifications. First is the call to get_term_by() which uses get_query_var() to determine what Custom Taxonomy term we’re working with. From there, we carry on through The Loop as normal, outputting the information we’d like to use and where.

The only lasting problem here, is the fact that we’re still sitting at http://wordpress/cpt/brands/canon/. I’d much rather have this page available at http://wordpress/cpt/cameras/brands/canon/ as to differentiate it from other Custom Post Types and their Custom Taxonomies.

Correctly identifying your rewrite slug

Custom Post Type UI makes it really easy to modify our Custom Rewrite Slug, which controls this change entirely. As mentioned earlier, a rewrite slug, unless otherwise defined, is based on the Custom Taxonomy name itself, hence our current /brands/%taxonomyname%/ result. We simply need to change our Custom Rewrite Slug to include the URL structure we’re looking for, in this case cameras/brands:

Saving the change to our Custom Taxonomy rewrite slug will push the permalink change and we’ll finally be able to hit our more appropriate http://wordpress/cpt/cameras/brands/canon/ URL, right? Not quite. It turns out that if we hit http://wordpress/cpt/cameras/brands/canon/ WordPress thinks we’re trying to hit a single post from our Cameras Custom Post Type and redirects us to the closest match.

In order to get our final archives-style pages to load properly, we’re going to have to modify our Custom Post Type Custom Rewrite Slug to differentiate a request for a single post entry versus our archive-style pages. To do that, we’ll need to change the slug from cameras to something more appropriate like cameras/body which could signify that we’re viewing a camera body.

With that change in place, we’re in business! We’re now able to hit http://wordpress/cpt/cameras/brands/canon/ and view the Posts that have been marked as Canon Posts, using our custom permalink as well as our custom template file. You can repeat this process with additional taxonomies by creating appropriate rewrite slugs in conjunction with new taxonomy-%taxonomyname%.php template files.

Adding links to Taxonomy archives in the sidebar

Many of the WordPress-native functions can be adapted for use with Custom Post Types and Custom Taxonomies. To add links to your newly created Custom Taxonomy archive pages, you could add something like this snippet to your sidebar.php:

<li id="camera-brands" class="widget-container">
  <h3 class="widget-title">Camera Brands</h3>
  <?php $cam_brands = get_terms('brands', 'hide_empty=1'); ?>
  <ul>
    <?php foreach( $cam_brands as $brand ) : ?>
      <li>
        <a href="<?php echo get_term_link( $brand->slug, 'brands' ); ?>">
          <?php echo $brand->name; ?>
        </a>
        <ul>
          <?php
            $wpq = array( 'post_type' => 'cameras', 'taxonomy' => 'brands', 'term' => $brand->slug );
            $brand_posts = new WP_Query ($wpq);
          ?>
          <?php foreach( $brand_posts->posts as $post ) : ?>
            <li>
              <a href="<?php echo get_permalink( $post->ID ); ?>">
                <?php echo $post->post_title; ?>
              </a>
            </li>
          <?php endforeach ?>
        </ul>
      </li>
    <?php endforeach ?>
  </ul>
</li>

While a bit of the markup is specific to Twenty Ten’s sidebar.php we can dissect what’s going on here:

1. Pull our brands
2. Create a list item for our brand
3. Pull all posts that have been marked as being that brand (via the taxonomy and term arguments)
4. Loop through each post within that defined Custom Taxonomy entry and dump out what we’d like to use
5. Repeat until finished with all Custom Taxonomy entries

When incorporated into the sidebar, we’ll get something like this:

As you can imagine, that sidebar listing would quickly grow to an unmanageable size, but the example illustrates just what’s possible using a few WordPress native functions and your Custom Post Types/Custom Taxonomies.

Custom Post Types and Custom Taxonomies are powerful

These changes in WordPress 3.0 are more than welcome, as they’re going to set the stage for much more traditional CMS-like behavior. The implementation discussed in this short series of articles is quite specific but hopefully outlines one of the many ways to work with Custom Post Types and Custom Taxonomies, all the while keeping a prettier permalink structure throughout your sites.

Custom Post Types, for those not familiar, is basically a templated content type based at their core off of WordPress’ Posts. There are a number of optional fields you can include within a Custom Post Type, and you can also build in your own. It opens the door to building a refined UI for data storage within WordPress given custom circumstances.

That said, you may be curious how that effects other systems such as Pods. If you haven’t had a chance, I discussed WordPress 3.0 and Pods in detail and have concluded that Custom Post Types and Pods achieve different goals at this point, and working with Pods gives you a level of control Custom Post Types currently do not (and in part do not strive to) achieve.

As full disclosure, I’ve recently been accepted as a Pods Core Developer but hope to express that circumstance having no effect or any biased opinions toward Custom Post Types. The Pods team wouldn’t exist without WordPress, and we’re all super thrilled about the existence of Custom Post Types.

In this walkthrough, I’d like to cover a fully top-to-bottom implementation of Custom Post Types, specifically targeting the task of ensuring a pretty permalink structure for your single pages. A follow-up article will take into consideration custom taxonomies for archive-style pages.

Up and running with Custom Post Types

Perhaps the biggest outstanding learning curve with Custom Post Types is the implementation itself. While programmers will love it, less experienced theme developers are likely to become quickly frustrated with the initial setup of Custom Post Types. While there is a lot of information in the always useful Codex, Custom Post Types still require an understanding of WordPress established conventions for implementation.

I’m a stickler for understanding the ins and outs of a system in which you work professionally, but I also understand that WordPress is a fantastic platform for tinkering. That said, if you’re a professional you’re looking to save as much time as possible. If you’re a tinkerer you’re looking to get up and running as quickly as possible so (hopefully) you can dissect how it happened. Given that, a really nice way to rapidly set up your Custom Post Types is the Custom Post Type UI WordPress plugin. Custom Post Type UI completely removes the tediousness of setting up Custom Post Types by providing an interface within the WordPress admin to do so. I’ve been using it on all of my recent projects and it’s a huge time saver. I do recommend though, that prior to using the plugin, you take the time to really understand what Custom Post Types are and how they fit into the big picture.

For the purposes of this walkthrough, we’ll set up an informational DSLR site with some information about a few cameras. Using Custom Post Type UI, we’ll set up a Cameras Custom Post Type:

While you can create a Custom Post Type filling out just the fields above, we’re working for a full implementation here, so we’re going to fill in the Advanced Label Options too:

If these fields are not populated, defaults will be used based on the initial labels used to set up the Custom Post Type. In this particular case, using those defaults would have worked out just fine, but there will be circumstances where a revised nomenclature will be much more meaningful to clients. We’re also going to customize the Advanced Options offered by Custom Post Types/Custom Post Types UI:

Using these fields we’re able to further refine the attributes of our Custom Post Type. Many of these can be left as default, but we’ll pay particular attention to both the Custom Rewrite Slug as well as the Supports areas. Built-in Taxonomies are also important, but we’re going to revisit that later. The Custom Rewrite Slug is responsible for ensuring your permalink structure remains accurate and in tact. More on that during implementation. Now that our options are set, clicking Create Custom Post Type will add our Custom Post type to the admin UI:

Adding a new entry will provide a familiar, but customized content entry view:

Once we’ve added some entries, we’ll begin building our library of content:

With Custom Post Types comes all of the built in content management functionality of WordPress, but at this point, we’ve got nothing to show for it within our theme; these pages are nowhere in sight on the front end. Our first option could be to use WordPress 3.0 Menus and manually build out a navigation system with a series of Custom Links, but that would quickly become overbearing given the fact that we’re hoping to build a website with hundreds (or thousands) of content pages.

Structuring WordPress for Custom Post Types

Custom Post Types are just that, they’re a collection of content. For the sake of organization as well as user experience, there should be some sort of hierarchy that incorporates your Custom Post Types. Currently, if you were to hit one of our Camera pages using the Permalink outlined on the edit page, you’d see the content included in the post:

For the purpose of this example, the permalink we’re working with is http://wordpress/cpt/cameras/canon-7d/ which is just fine; I like the way it’s structured. The trouble creeps in when, by experience, we want to view an index page by stripping off the last URL segment and trying to hit http://wordpress/cpt/cameras/. Out of the box we’re slammed with a 404 error. As a fix, I’d suggest creating a WordPress Page called Cameras (with the proper slug) to ensure we no longer hit that 404.

This ties into my philosophy of structuring WordPress sites; WordPress Pages should dictate the overall structure (for both content and URLs) and be the foundation of everything built on top of it. To our benefit, Custom Post Types work within thsi philosophy.

With our http://wordpress/cpt/cameras/ URL now properly resolving, we could create a custom Page template to pull in all of our Cameras. There are two approaches here, you can either set the Page Template in the Page Attributes sidebar on the edit screen, or simply name your template file using the Page slug. We’ll take the latter approach and create a new file within our theme directory called page-cameras.php consisting of:

<?php

/* Template Name: Cameras index */

get_header(); ?>

  <div id="container">
    <div id="content" role="main">

      <?php
        query_posts( 'post_type=cameras' );
        get_template_part( 'loop' ); // looks for loop.php which is specific to Twenty Ten
        wp_reset_query();
      ?>

    </div><!-- #content -->
  </div><!-- #container -->

  <?php get_sidebar(); ?>

<?php get_footer(); ?>

Note: The call get_template_part() looks for loop.php, a template file specific to Twenty Ten, the stock theme that ships with WordPress 3.0

What we’re doing in this template is simply querying all posts for our cameras Custom Post Type and sending that data to The Loop. Last, we reset to the original query fired during page creation which will prevent any funkyness with sidebar and/or footer logic. What results is a page that mimics a default Posts entry view in Twenty Ten:

While the implementation so far is great for including the data stored in our Custom Post Type, it’s not very organized.

Organizing Custom Post Type data using a Custom Taxonomy

Closely related to Custom Post Types are Custom Taxonomies. To our benefit, the Custom Post Type UI plugin handles the creation and maintenance of Custom Taxonomies as well. We’re going to organize our Cameras Custom Post Type by attaching a few Taxonomies:

When creating them, we’ve attached the Taxonomies to our Custom Post Type, and they now show up as expected:

Out of the box, Custom Taxonomies behave like tags. Depending on how you’d like to use your Taxonomy, tags might be an applicable solution. In this case, however, I’d like to offer a choice-based system for my client. To do that, and therefore make your Taxonomy behave more like a WordPress Category, you’ll need to edit the Advanced Options of the Taxonomy:

By setting your Taxonomy to being hierarchical you’ll provide a listing of all existing entries as well as a check/uncheck interaction:

As with most things Custom Post Type, while you’re able to add/edit/remove the data, it doesn’t do much out of the box on the front end. Viewing the Canon 7D page we just edited on the front end results in no visible change. We’re going to use our Custom Taxonomy to provide category-style archive listings.

The end of the basics

This walkthrough sets the stage for the more difficult task of setting up Custom Taxonomy-based archive-style pages using appropriate permalinks. If you’d like to take the next step in pushing your Custom Taxonomies to the front end of your site check out WordPress Archive Pages Based on Custom Taxonomies.

In part 1 I examined the current WordPress cart plugin landscape and outlined a number of reasons I feel that PHPurchase is currently the leading solution for an e-commerce solution, especially with the arrival of Custom Post Types. I’d like to share how and why using Custom Post Types works so well for a WordPress shopping cart.

Setting up and prepping WordPress

The first step will be to get your WordPress 3.0+ install up and running. That’s the extent of detail we’ll cover there. The next step will be to obtain and install a copy of PHPurchase. There are a number of purchase options available, but this walkthrough will cover functionality available under all licenses of PHPurchase.

The installation of PHPurchase is as straightforward as any other plugin. Once you’ve uploaded the plugin files and activated the plugin, you’ll need to enter your PHPurchase order number on the Settings screen:

After validating your order number, the reminder to do so will disappear and you’ll be able to enter in your PayPal, Authorize.net, or Quantum Gateway payment settings. These details aren’t required at this point, but until that information is entered, the plugin won’t let you check out. For now, those are the only details we’ll cover as far as setup is concerned. Using the PHPurchase menu in the WordPress admin, you can begin adding products.

As it stands PHPurchase will automatically implement a number of system Pages it will use to handle the cart view and checkout process for purchases.

While these pages are an extremely important part of the overall e-commerce implementation, none of the products we just added are made available out of the box.

By editing the Store page, you can quickly add a number of products using the PHPurchase icon in the editor toolbar:

At this point, you can feel to proceed as normal. Using this Store page you could add every product you have available as well as apply some style and content using imagery, product copy, and links to relevant information. You could take it a step further and also create child pages with the Store as the parent and dedicate a product detail page to each of your products.

While helpful, you’ll quickly discover missing features that are very commonly found in other e-commerce platforms. Features such as browsing products by category and providing additional information about products in the form of multiple product shots and/or PDF downloads aren’t directly built into PHPurchase. The beauty lies in the fact that you can customize WordPress in all the usual ways to add these features as you see fit.

With the arrival of WordPress 3.0, however, there is an entire layer of additional functionality found in Custom Post Types that makes working with these features a breeze.

Using Custom Post Types for your PHPurchase Store

Custom Post Types are sometimes intimidating to more novice developers. Out of the box in WordPress 3.0 you need to manually register and set up your Custom Post Types. As with many developer-heavy tasks at hand, there is a plugin to make life easier when it comes to Custom Post Types; Custom Post Type UI.

Custom Post Type UI gives WordPress admins the ability to create, edit, and manage all of the Custom Post Types available within the WordPress Install:

Using the plugin you can easily create a Custom Post Type to handle all of your product pages in PHPurchase. You’re able to customize the phrasing used throughout and viewing the Advanced Label Options gives you even more to work with. On top of these Custom Post Type Settings, you can also set up custom taxonomies which can be used in this specific case for a set of categories limited to your store products and separate from your Post categories.

Once you’ve created your Custom Post Type, a new menu item will be made available in the main navigation:

Using the links available you can go ahead and set up your categories as well as add your products.

Once your products have been added to your Custom Post Type, you can view the page on the front end:

Integrating Custom Post Types into your Menu

Now that your products have been added, you’ll want to make browsing your products as easy as possible. There are a number of things you can do, the primary two being including links to your product pages within your site navigation and using your Custom Post Type taxonomy (product categories).

Menus were also a big addition to WordPress in 3.0 and the update comes in handy at this point in our PHPurchase setup. The Menus are smart enough to recognize your Product Pages and allow you to integrate them directly within your site navigation:

Using the Menus you’re able to mix and match your Product Pages, your Product Categories, as well as your WordPress Pages themselves. You can custom build any structure you wish using the menus and the available entries. By default, linking to a Product Category will direct readers to pages resembling those of your other category pages, likely using category.php from your theme. You can customize this to any degree as you would normally when developing your custom WordPress theme.

Integration with plugins

Another significant advantage to using Custom Post Types and PHPurchase to power your WordPress based e-commerce website is the direct integration with many of your favorite plugins. One of the downfalls to a number of other WordPress store plugins is a lack of attention to search engine optimization. When working with product pages powered by Custom Post Types you can continue to use the SEO plugin working to optimize the rest of your website.

Additionally, you’ll be able to use plugins that enhance your ability to make additional product assets available to readers. Plugins like Attachments will let you add multiple product images for use in a product image viewer, PDFs including additional product details, as well as any available product details that may exist.

This is just the beginning

These are just the basics of getting up and running with WordPress 3.0+, Custom Post Types, and PHPurchase in an effort to get the best possible e-commerce shop up and running quickly and easily. While it’s a bit more work to get a large volume of products added and available on your website, I really feel that PHPurchase is a great choice when considering available e-commerce solutions for WordPress.

The WordPress cart landscape

When it comes to WordPress, there are actually a number of shopping carts available. I think we can all cringe a bit when WP e-Commerce gets brought up. It’s arguably the oldest, most widely used e-commerce platform for WordPress today. I don’t have an official stance on the platform though. I’ve tried to install it a few times now and each time either not made it to, or not made it very far passed activation.

Not too long ago, a new kid showed up on the block: Shopp. I was really impressed from a ‘book cover’ stance and took the time to check it out. A few minutes into it I felt that the developers deserved some support for taking a WordPress e-commerce plugin seriously. I snagged myself a single site license and gave it a whirl. I really liked what I saw. The plugin did its part in mirroring design conventions established in WordPress itself, something I feel is very important to plugin development. On top of that, the bit I played around with it showed that it had a great balance of functionality and customization capability.

Shopp followed in WordPress’ footsteps by providing theme files and hooks to work with, something we all love about WordPress. The documentation looked to be actively defined and I was convinced I had my go-to plugin for e-commerce the next time it came up. I even pitched the plugin to a number of friends, some of which had cart projects on their plate and were in the market for a new plugin to check out.

I didn’t have any e-commerce plugins crop up over time, but I saw a few friends make a post here or there about some frustrations they were having with Shopp. To be as specific as I can without firsthand knowledge, it sounded like there may have been a few bugs to squash when it came to actual payment processing. Shortly after that, the Shopp team announced that the plugin was to undergo a full rewrite in an effort to stabilize the payment processing and other bugs that had been reported in the forums. As it stands, Shopp is in 1.1 beta and looks to be continuing progress.

As I was shopping alternative carts, a Google search brought me to another commercial e-commerce plugin I hadn’t heard of before: PHPurchase. It took all of two seconds for me to realize that something stood out about this plugin. Beyond it being hot off the press, it bragged of such features as PCI compliance and the ability to pass the McAfee Security Test. I liked that. As I dug deeper I took a few minutes to research PHPoet, the company behind PHPurchase and continued to find bits and pieces that I liked.

As I looked around further, I noticed that PHPurchase took a partially different approach to e-commerce in WordPress. Instead of auto-generating product grids and product detail pages, PHPurchase takes care of product entry and the other details surrounding the cart setup, and then leaves it up to you to populate your site.

To be more precise, PHPurchase lets you enter all of your payment gateway details, enter products into the products database, as well as customize a number of additional (and expected) options when it comes to e-commerce. It leaves it up to you, though, to populate the shopping area of your site. Instead of template-based shopping pages, PHPurchase offers a product entry button in the WYSIWYG editor that injects a shortcode which, when processed, outputs a price, quantity field, and a buy button. The rest is completely up to you.

It’s more work, but it’s more custom

That was the driving point for me with PHPurchase. Instead of accommodating a template structure of the cart plugin itself, I could go about my day and code a theme template file as though I were doing that for any other page on the site. On top of that, each and every other plugin I’ve come to know and love (e.g. All in One SEO Pack) would work like a charm, out of the box. PHPurchase was scoring major points the more I thought about it.

All of this took place as we were catching a more public wind about WordPress’ Custom Post Types. Custom Post Types are a flagship when it comes to evaluating WordPress as a CMS vs. a blogging engine. Here’s where my mind started racing. The combination of Custom Post Types and PHPurchase is game changing when it comes to WordPress based e-commerce.

Before Custom Post Types, product pages would be set up as any WordPress Page tree would. You’d create your Pages, populate your content, insert your shortcodes, and end up with a fully functioning e-commerce solution; fully integrated with your favorite plugins. Custom Post Types, though, give you the ability to custom tailor your data fields as well.

Custom Post Types allow you to populate your content as normal, but also give you the ability to set up custom taxonomies (e.g. product categories) as well as tags. You’re also able to custom code the theme file used for your Custom Post Types as though you were writing it for a built in WordPress Page. Instead of working with (or having to rewrite) product templates, you’re instead building your cart from the ground up with PHPurchase.

Without a doubt, it’s more work to get a populated cart up and running with PHPurchase compared to a templated e-commerce plugin. When I think about it though, I build WordPress themes from the ground up for every client (aside from a “new site” framework) and I do that because I believe in hand crafted websites. Why should a cart be any different? I think we’ve been in part complacent to the current cart solutions out there and I’m glad PHPurchase has changed the game for me. My clients will love it too.

Implementing PHPurchase with Custom Post Types

Part 2 of this two part series will consist of a walkthrough outlining how I work with WordPress, Custom Post Types, PHPurchase, and a number of plugins that will help make your cart stand out from the rest.

What are Custom Post Types?

First and foremost we need to understand what Custom Post Types are. I’ll try to do my best to sum them up as quickly and as easily as possible in my own words.

Custom Post Types defines our new ability to better organize more advanced content structures within our WordPress sites. That is to say, using Custom Post Types will allow us to create groups of content in addition to the stock Posts and Pages. Subsequently, we’re also able to define the data fields used in each group. Further, we’re able to take advantage of many standard features built into WordPress such as creating custom taxonomies (used for categorization among other things) and more.

If I had to label one final stake in the ground that WordPress is fantastically stating that it is no longer a “blogging” platform and instead a content platform, it would be Custom Post Types.

Custom Post Types have got a ton of attention lately, and as such deserves it. I can’t emphasize how much of a game changer this is on a platform level not only for WordPress developers, but for users as well. We’re going to see a lot of changes on the theme level which in turn will spread the word about WordPress’ adaptiveness.

Where does Pods fit in?

Custom Post Types sound great, but what about Pods? If you want the short version: I love Pods and I don’t see it going anywhere anytime soon as a result of Custom Post Types.

Now for the extended version.

Pods and Custom Post Types, although they have some overlapping functionality, don’t directly compete with one another top to bottom. Custom Post Types open a lot of doors, and I plan on using those doors as often as possible. Pods, however, is functionally superior to Custom Post Types in ways that I’ve been taking advantage of on nearly every project in recent memory.

The superiority lies in the fact that instead of being a new group of Custom Posts or Pages, Pods focuses on the relationship factor by keeping the doors wide open when it comes to how the data is displayed, how users interact with it, and how you use it. Additionally, the Pods developers are super focused on performance. That’s not to say that I’ve noticed a performance problem with WordPress, but it’s great to read that they’re focused on speed and integrity to the level of creating one-off database tables every time Pods needs one for your content types.

Pods takes a different approach entirely when it comes to the database level. WordPress Custom Post Types simply append your new content groups to the Posts table and under the hood are using Custom Fields to take care of your custom data. This is nowhere near magic to anyone who has written a plugin before that accomplishes the same thing. Attachments, for example, uses that philosophy to function.

Don’t take me wrong, I don’t think that’s wrong to do, not by any means. I always try to KISS and I think Custom Post Types do the same thing. I also appreciate, though, that Pods focuses on performance at its root.

Pods also offers more when it comes to functionality offered. Custom Post Types leave things pretty open-ended for you to get done what you’d like, but I’m not sure how easy it will be to relate one Post to another, or multiple for that matter in that group. What about relating that Post to a Post from a completely different group? What if you want to limit that list of available Posts to include a certain number of Posts from one group, and more from another? Pods has you covered out of the box.

I’ve also become addicted to the way Pods UI lets you present the Pods you’ve created. You’re able to organize and group your content types in such a way that it makes perfect sense when your client needs to hop in the driver’s seat. Pods UI is founded on built-in WordPress functions and I’m not sure to what extent it can be replicated with Custom Post Types at this stage, but I’m smitten with Pods UI and hopefully that functionality can eventually find its way to Custom Post Types.

I’ve become very comfortable with the advanced features offered by Pods, especially when Pods UI comes into play, and I won’t backtrack at this point just to take advantage of built-in functionality (my personal preference by default). I think Pods still stands on its own two feet by a long shot.

Will they blend?

That said, I plan on using a combination of Custom Post Types and Pods until a new catalyst enters which will cause me to reevaluate the situation at that point. I have a set of rules that help me build sites on top of WordPress and incorporate Pods all to make things as easy as possible for my clients to use and I will continue with that school of thought now that Custom Post Types are here.

I’ve got a lot to learn about Custom Post Types and what’s technically functional, possible, and stable. You can be sure I’ll be posting my findings along the way. I feel that Pods and Custom Post Types make a good team and will continue to do so beyond the launch of WordPress 3.0.

That’s one of the reasons I really like Pods. While one inescapable argument I’ve had with myself since discovering Pods is the fact that clients are very likely to become confused with the implementation at a certain point. Not by the fault of Pods itself, but the way it’s bound to be used. This is where the conversation bridges itself into the philosophy of combining Pods and WordPress for the benefit of your client; an up-and-coming article that isn’t ready quite yet. There’s just as much to be said about implementation as there is the tool, and I’m really looking forward to having that conversation with you soon enough. For the time being though, I digress.

Circling back to usability, out of the box Pods has a leg forward by simply being. It gives an interface consisting of elements strictly defined as being applicable when viewed. Awesome. While putting together a client site recently I couldn’t help but notice a usability issue I knew would come up sooner or later. For the sake of privacy, I’ll make the example a bit more generic, but equally applicable.

For example’s sake, we’ll say that I’m working on a photography history website. There is a section of the website consisting of famous photographers, a bit of information about the person, and of course some work examples. My plan is to have one Pod for the photographers, one Pod for the photographs, and use Pods UI to relate the two very easily.

The problem

With the game plan in place, we’ll first set up our two Pods:

Define the data columns:

When setting up the Photographs Pod, we’re going to set up a pick column to pull from our newly created Photographers Pod:

In particular, pay attention to the way the pick column is structured

The final Pod:

We can now begin populating some photographers:

Then we’ll add some photos:

Here’s where I discovered that a problem was a brewin’. As it stands, we’re using the name column alongside a first_name column therefore resulting in the last name controlling the slug. What happens when you add a second photographer with the same last name? You’ll be faced with a duplicate entry and your client will be left to guess, save, and check to make sure they guessed right. A possible solution would have been to re-structure the Pod from the start and use the name column for the photographer’s full name, but what if you wanted to pull data ordered by last name only?

Given the current situation, we might be in a bit of a pickle. Pods can help with that!

The solution

Input Helpers are quickly becoming a favorite feature of mine when it comes to Pods. As is the case with this particular situation, data columns aren’t quite cutting it, even when they’re as awesome as pick relationships.

The solution I cam up with to solve this problem of data integrity was to simply make the data itself that much more valuable. It would be great if we could simply append the first name alongside the last name to help decipher which dupe is which when choosing our photographer. Input Helpers to the rescue.

We’re going to write a quick Input Helper that expands upon the information originally available with a stock pick column. As it stands, when invoked, pick columns will display all of the (extremely valuable) associated data columns you already set up with your Pod. In the case of Photographers, we’re provided with the following:

• id
• first_name
• origin
• copy
• slug

All of the additional data that comes with an Input Helper is also available. What’s most interesting here is the fact that we can pull data from the Pod itself, specifically the first_name.

<select id="<?php echo $css_id; ?>" class="form pick1 <?php echo $name; ?> pods_field pods_field_<?php echo $name; ?> pods_coltype_pick">
  <option value="">-- Select One --</option>
  <?php if ( !empty( $value ) ) : ?>
    <?php foreach ($value as $key => $val) : ?>

      <?php
        // check to see if this is the chosen value
        $selected = empty($val['active']) ? '' : 'selected';

        // check to see if we have a full name
        $photog_name = $val['name'];
        if( !empty( $val['first_name'] ) )
        {
          $photog_name .= ', ' .  $val['first_name'];
        }
        ?>

      <option value="<?php echo $val['id']; ?>"<?php echo $selected; ?>><?php echo $photog_name; ?></option>
    <?php endforeach ?>
  <?php endif ?>
</select>

As with writing any Input Helper, we want to start by examining the markup provided by the original input field. That way we can replicate and elaborate upon what’s made available to our user.

The take home notes with this Input Helper revolve around the conditional that checks to see if we have a full name. We simply check to see if first_name has been defined, and if it has, we’ll append it to the last name and provide a much more straightforward experience for our user:

Not only does this help to prevent confusion when handing over the keys to your client, it really helps to polish the overall experience by being that much more straightforward and useful.

NicEdit was frustrating clients left and right, but TinyMCE wasn’t. Some time ago I wrote a plugin that is in dire need of an upgrade called Post Notes that appended any number of WYSIWYG editors for any Post or Page and let you reference them as you wished. I was hoping I could use the same passive method of including TinyMCE in Pods that I had used for Post Notes.

WordPress has come along nicely since I first wrote that plugin, and I’m happy to say that I’ve come up with a working solution to upgrading your NicEdit WYSIWYG columns in Pods to use TinyMCE by adding an Input Helper. Here she is:

TinyMCE for Paragraph Text

Input Helper explained

As a really brief walkthrough what the Input Helper does is modify the markup used to dump out the base textarea that holds our actual data. That’s the standard part. The exiting bit is contained in the conditional at the top of the Helper. The conditional basically checks to make sure that it’s not executed repeatedly for each Paragraph Text column used.

When the time is right the helper will fire wp_tiny_mce() which is a nearly undocumented WordPress function that resembles wp_enqueue_script() on steroids. It will pull in all the necessary scripts for TinyMCE as well as properly initialize them.

The first parameter dictates the TinyMCE theme to use. If set to true the full (advanced) theme will be used, setting it to false results in a stripped down (simple) theme which I prefer to use in this case. The array passed as the second parameter tells wp_tiny_mce() which class to hook, you do not need to edit it. The Package available for download includes both a simple and an advanced TinyMCE Input Helper.

The JavaScript segment of this helper actually hijacks Pods’ saveForm() function call as we need to force TinyMCE to fire triggerSave() which forces the TinyMCE content to be applied to our original textarea which is super important.

Installation

You can snag the TinyMCE Upgrade Input Helper Package from the Pods website. Once downloaded, go ahead and log into the WordPress admin and hit the Package Manager link under the Pods heading:

Then you can hit the Import tab since we’re not Exporting anything:

Just paste the Helper in the provided text box and click Proceed to Confirmation

After Pods validates the Helper you can go ahead and Finalize:

Pods will let you know it’s All done! Your Input Helper is ready to go. Now you can browse to the Paragraph Text Column you’d like to edit which used to look like this:

and update the Input Helper field for the applicable column by first clicking the Edit icon next to your column and then defining the Input Helper by choosing tinymce from the select. Be sure to click Save to ensure the Input Helper is properly defined:

When you go back to edit your Pod, you’ll see a brandy new instance of TinyMCE instead of NicEdit:

Please make sure you’re running the latest versions of both Pods and Pods UI before working with this Input Helper.

Known Issues

I’m currently trying to work with Scott Kingsley Clark on a few details but there may be some problems with using this Input Helper along with a publicForm. Please avoid using this Input Helper on any Pod you plan on using in conjunction with publicForm until it can be better tested. More info coming as soon as possible!

Update: As of March 31, 2010 I can confirm that there is a problem with the Helper if your Pod has not been made Top Level and you’re not using Pods UI for the Pod. If at all possible, making it either Top Level or using Pods UI should achieve the desired results. We’ll keep working away at a fix ASAP!

Update: Version 1.0.2 forces each editor instance to be of a certain height and also disables the resize handle due to it acting up in certain circumstances.

I’d like to review Input Helpers a bit. Out of the box, Pods offers a number of column types including date field, number, boolean, paragraph text, and more. We also can’t forget about one of the more unique column types offered; Pick columns.

Applying Input Helpers to Pick columns

On a recent project (like many projects) I found myself using a Pick column set to WP Page that automagically pulls a list of all WordPress Pages when the Pod entry form is displayed.

The goal with this Pod was to allow the client to dynamically define a background image for their website on a per-page basis. Out of the box, the solution worked as expected:

There was a problem though. I didn’t want the client to have full control over each and every page of the site. There were a number of pages on which it wouldn’t make sense to have a custom background. This is one of the many cases where Input Helpers come to the rescue.

The basics of Input Helpers

Input Helpers were designed to do one thing:

An Input Helper lets you completely customize the appearance of any input field.

What this means is we’re given the opportunity to both hook and manipulate the data pulled to an input field before it is displayed on screen. Input Helpers are applied on a per-column basis (as opposed to a Pod as a whole). The possibilities here are literally endless. If you have a requirement for the options available in an input field, Input Helpers are where you’d start.

As mentioned in the Codex, Input Helpers have a number of variables available to use. Each variable is well explained in the Codex, and depending on the column type, you can use and interact with each of these variables at your will in an effort to obtain your desired result.

Input Helpers are created using the Helpers tab in the admin panel. When naming your Input Helper, ensure the title is comprised of all lowercase (non-special) characters, no dashes, and no spaces. Also be sure to define the helper as Input.

After the Helper is created, you’re provided with a code editor. Here’s where the magic happens. Using this editor, you can manipulate your data using a combination of straight PHP and the variables outlined in the Codex.

After you’re done writing the PHP needed to manipulate the values available in your input column, the last step is to actually apply the Helper to your Input:

Note: due to AJAX, you’ll need to refresh the page before attempting to apply your Input Helper.

Limiting WordPress Pages with an Input Helper

Circling back to our single use case, we’ll go ahead and write a quick and dirty Input Helper that’s going to limit our WP Page Pick column to only a select few Pages I want to make available to my client. Writing an Input Helper might require a bit of initial legwork in inspecting the default markup used for the existing (out of the box) data available. In this example we’re working a multiple Pick, so the markup is as follows:

<div class="leftside pages">
  <label for="pods_form0_pages">
    Page(s)
    <span class="red">*</span>
  </label>
</div>
<div class="rightside pages">
  <div class="form pick pages" id="pods_form0_pages">
    <div class="option" value="2">About</div>
    ...
    <div class="option" value="18">Team</div>
  </div>
</div>

The snippet has been truncated, but we can see how the Pick column is structured. We simply need to recreate that markup as we filter through the data supplied to the field:

<?php
  $applicable_pages = array( 2, 31, 18, 23 );
?>
<div class="form pick <?php echo $name; ?>">
  <?php if ( !empty( $value ) ) : ?>
    <?php foreach ($value as $key => $val) : ?>
      <?php if( in_array( $val['id'], $applicable_pages ) ) : ?>

        <?php
          $pagename = $val['name'];
          $active= empty($val['active']) ? '' : ' active';
        ?>
        <div class="option<?php echo $active; ?>" value="<?php echo $val['id']; ?>">
          <?php echo $pagename ; ?>
        </div>

      <?php endif ?>
    <?php endforeach ?>
  <?php endif ?>
</div>

What we’re doing with this Helper is first defining $applicable_pages which contains an array of the Page ids we’re permitting to show up for use. We then loop through $value (provided by Pods as per the Codex) and check to see if the current Page id is in our array. If it is, we’ll go ahead and make it available, else we move on to the next. What results is our refined list of available WordPress pages:

A word of warning with this implementation: it’s tied to a single WordPress install. Additionally, problems will come up should the site be migrated to a new WordPress installation without a complete database export/import. WordPress Page ids are not retained using WordPress’ import/export features. Keep that in mind as you write your Helpers.

Input Helpers raise the bar

Input Helpers open a ton of new doors when it comes to Pods. We’ve just scratched the surface with the example above, and as with pretty much anything “Pods” the possibilities are endless.

Another great resource you’ll want to bookmark is the Packages section of the Pods CMS website. You can find a ton of available Helpers that have been made available by the community, some of which may come in handy straight away. The section isn’t limited to Helpers, but you can easily peruse the titles and poke around when you’ve got a minute.

Luckily enough, a client need came through which included such a feature. What better time to teach yourself something? Other programmers at my company had implemented proximity searches in the past, but I wasn’t involved on the projects and didn’t want to simply peruse their code and see what I could pull from it. I sat down with one of the guys as I began working on the feature to discuss past implementations. There were two ways to go about it:

1. Piggyback on Google Maps
2. Do things the hard way

It took me about zero seconds to determine that I wanted to do things the hard way. It’s not that I don’t enjoy working with Google Maps. Quite the contrary in fact. I just don’t want to depend on it too much in the day to day, especially for something as generic as a proximity search. Additionally, it just adds another layer of complexity with remote calls, API limits, and the other issues associated with using any other third party service. Hard way it is.

Pods setup

The first thing we’ll do is create a ‘stores’ Pod. If you’re not familiar with creating Pods, take a few minutes to read the beginner series, starting with Pods Basics: Installation and Setup. I’m going to use the following columns:

• name (txt)
• slug (slug)
• address (txt)
• city (txt)
• state (PICK state)
• zipcode (txt)

We’re also going to simply make this Pod a Top Level Menu. If you’re looking to make things even nicer, go ahead and include Pods UI where applicable.

I’ve made every column required data, as an address isn’t very useful without complete information. I segmented the addresses as such simply because the proximity search I’ll be implementing is based on ZIP code, and having that data in a separate column will help with server load. Lastly, I chose to use a txt column for the zipcode instead of a Number because many ZIP codes begin with one (or more) zeros, which would cause a bit of trouble.

As a last step, we’ll go ahead and add a few test store listings using various ZIP codes you’re familiar with. The more variance the better, as you’ll be able to see whether the proximity aspect of the search is working properly or not.

Once you’ve added a few samples, it’s time to integrate.

WordPress setup

For the sake of brevity, this location based search will sit on its own WordPress Page, using a template we’ll put together. We’ll continue working with the WordPress default theme, and add a new template; store-locator.php which includes the following:

<?php

/* Template Name: Store Locator */

get_header(); ?>

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

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

        <?php the_content(); ?>

        <form action="" method="post">

          <p>
            <label for="mbn_zipcode"><small>Your ZIP</small></label>
            <input type="text" name="mbn_zipcode" id="mbn_zipcode" value="<?php echo $_POST['mbn_zipcode']; ?>" size="5" tabindex="1" />
          </p>

          <p>
            <label for="mbn_distance"><small>Within (miles)</small></label>
            <select name="mbn_distance" id="mbn_distance" tabindex="2">
              <option value="5"<?php if( empty( $_POST['mbn_distance'] ) || $_POST['mbn_distance'] == "5" ) : ?> selected="selected"<?php endif ?>>5</option>
              <option value="10"<?php if( $_POST['mbn_distance'] == "10" ) : ?> selected="selected"<?php endif ?>>10</option>
              <option value="25"<?php if( $_POST['mbn_distance'] == "25" ) : ?> selected="selected"<?php endif ?>>25</option>
              <option value="50"<?php if( $_POST['mbn_distance'] == "50" ) : ?> selected="selected"<?php endif ?>>50</option>
              <option value="100"<?php if( $_POST['mbn_distance'] == "100" ) : ?> selected="selected"<?php endif ?>>100</option>
            </select>
          </p>

          <p><input name="submit" type="submit" id="submit" tabindex="3" value="Submit" /></p>

        </form>

      </div>
    </div>

  </div>

<?php get_sidebar(); ?>

<?php get_footer(); ?>

Nothing exciting happening here, we’re simply setting the stage with the basic form we’ll use to search our store directory by location.

Now that we’ve got our Page using our template, we’ll implement the location search functionality via Pods.

Setting up the location search

Our first step will be to add a conditional that checks to see if the form has been submitted. In this case, I’ll simply add a hidden input to track the current action:

<input type="hidden" name="mbn_action" value="search" />

With this action in place, we can include our conditional:

<?php if( !empty( $_POST['mbn_action'] ) ) : ?>
  <p>List our results</p>
<?php endif ?>

Here’s where everything happens. Once we find ourselves in the conditional, we’ll need to do a bit of work:

1. Sanitize our data
2. Retrieve search results
3. Display data

Our conditional will expand to be:

<?php
  if( !empty( $_POST['mbn_action'] ) )
  {
    if( !is_numeric( $_POST['mbn_zipcode'] ) )
    {
      $the_zip = '0';
    }
    else
    {
      $the_zip = $_POST['mbn_zipcode'];
    }

    $the_distance = intval( $_POST['mbn_distance'] );

    $stores = mbn_get_stores_by_location( $the_zip, $the_distance );
    $stores_total = count( $stores );
  ?>

    <?php if( $stores_total > 0 ) : ?>
      <h3>Search Results</h3>
      <ol>
        <?php foreach( $stores as $store ) : ?>
          <?php $store_address = $store['address'] . ' ' . $store['city'] . ', ' . $store['state'][0]['name'] . ' ' . $store['zipcode'] ; ?>
          <li><dl>
            <dt>Name</dt><dd><?php echo $store['name']; ?></dd>
            <dt>Address</dt><dd><?php echo $store_address; ?></dd>
            <dt>Distance</dt><dd><?php echo $store['distance']; ?> miles</dd>
          </dl></li>
        <?php endforeach ?>
      </ol>
    <?php endif ?>

<?php } ?>

You’ll notice that there’s no reference to Pods anywhere in that conditional, but there is a new function to take a look at; mbn_get_stores_by_location().

Implementing the proximity aspect

This new function, mbn_get_stores_by_location(), will take care of all the work including:

1. Determine the latitude and longitude of the source ZIP code
2. Use triginomitry to determine which additional ZIP codes fall within the chosen radius
3. Retrieve all Pods entries matching the pool of ZIP codes
4. Return an array of results, ordered by distance

The quickest and easiest way to implement the function will be adding it to functions.php in your theme. Before we implement the function, however, you’ll need to add a new table to your database. This table is going to include a listing of all US-based ZIP codes and acts as an integral piece for this function. The table is used to determine the latitude and longitude of applicable ZIP codes, and is used with each search submission. There are a number of places to obtain a ZIP code database, the one I’ve used in the past is made available for free from PopularData.com. It’s made available as a CSV file weighing in at about 700k. There is a donation button available on the download page, and I’d suggest showing your appreciation to the provider should you use the database for any commercial work.

You’ll need to set up a new table in your WordPress database and be sure to name it something unique. You’ll need to remember both the table name and column names as you implement the location search. Once you’ve added the table and verified its integrity, we can go ahead and implement mbn_get_stores_by_location() in functions.php:

<?php

function mbn_get_stores_by_location( $zip, $radius )
{
  global $wpdb;
  $radius = intval( $radius );

  // we first need to get the source coordinates
  $sql = "SELECT `latitude`, `longitude` FROM `mbn_zip_codes` WHERE `zipcode` = '$zip'";
  $coords = $wpdb->get_row( $sql );

  // now we'll get the other ZIP codes within the radius, ordered by distance
  $sql = "SELECT mbn_zip_codes.zipcode, ( 3959 * acos( cos( radians( $coords->latitude ) ) * cos( radians( mbn_zip_codes.latitude ) ) * cos( radians( mbn_zip_codes.longitude ) - radians( $coords->longitude ) ) + sin( radians( $coords->latitude ) ) * sin( radians( mbn_zip_codes.latitude ) ) ) )  AS distance FROM mbn_zip_codes HAVING distance <= $radius OR distance IS NULL ORDER BY distance";

  $nearby_zips = $wpdb->get_results( $sql );

  // we need to store the zips in order to build the Pods query
  $target_zips = array();
  foreach ($nearby_zips as $nearby_zip)
  {
    array_push($target_zips, $nearby_zip->zipcode);
  }

  // we're going to store the results as we go
  $store_results = array();

  if( count( $target_zips > 0 ) )
  {
    $final_target_zips = implode(',', $target_zips);

    if( strlen( $final_target_zips > 0 ) )
    {
      // let's snag the data
      $stores = new Pod('stores');
      $stores->findRecords('id ASC', 9, 't.zipcode IN (' . $final_target_zips . ')');

      $store_data = array();

      while ( $stores->fetchRecord() )
      {
        $store_data['id']       = $stores->get_field('id');
        $store_data['name']     = $stores->get_field('name');
        $store_data['slug']     = $stores->get_field('slug');
        $store_data['address']  = $stores->get_field('address');
        $store_data['city']     = $stores->get_field('city');
        $store_data['state']    = $stores->get_field('state');
        $store_data['zipcode']  = $stores->get_field('zipcode');

        foreach ($nearby_zips as $nearby_zip)
        {
          if( $store_data['zipcode'] == $nearby_zip->zipcode )
          {
            $store_data['distance'] = intval( $nearby_zip->distance );
          }
        }

        array_push( $store_results, $store_data );
        unset( $store_data );
      }

      usort( $store_results, "mbn_cmp" );
    }

  }
    return $store_results;
}

?>

Quite a bit is going on in this function. Once our globals are set and our data sanitized, we’re going to query the new table we set up to retrieve the coordinates of the submitted ZIP code. Once we have those coordinates, we’re going to perform a lengthy query on that same table to determine what other ZIP codes fall within the submitted radius:

SELECT mbn_zip_codes.zipcode, ( 3959 * acos( cos( radians( $coords->latitude ) ) * cos( radians( mbn_zip_codes.latitude ) ) * cos( radians( mbn_zip_codes.longitude ) - radians( $coords->longitude ) ) + sin( radians( $coords->latitude ) ) * sin( radians( mbn_zip_codes.latitude ) ) ) )  AS distance FROM mbn_zip_codes HAVING distance <= $radius OR distance IS NULL ORDER BY distance

You will need to be sure that table and column names are appropriately updated. There are a number of formulas which use trigonometry to solve proximity equations, but I’ve found the above to suit my needs well in this application.

Once we’ve got our nearby ZIP codes ordered by date, we query our Pod for any entries with ZIP codes that match our results. Instead of using get_field() to echo the display directly, we’ll instead use it to store the data in an array consisting of all returned results.

Once we’ve processed the results, our last step will be to use usort to ensure our results are actually sorted by distance:

usort( $store_results, "mbn_cmp" );

usort uses a custom function to determine the comparison result, and we’ll need to add that to functions.php as well:

function mbn_cmp($a, $b)
{
  $a = intval( $a['distance'] );
  $b = intval( $b['distance'] );
  if( $a < $b )
  {
    return -1;
  }
  elseif( $a > $b )
  {
    return 1;
  }
  else
  {
    return 0;
  }
}

Note that the comparison function uses a specific array key to generate a result. If you change the distance key, you’ll need to update this function as well.

That takes all the magic out of it. If we return to our submission form and search for a ZIP code that is known to produce results, we’ll see the functionality at work:

I realize the explanation is a bit lengthy, but I hope it helps to explain how a proximity search can work on a smaller scale.

Alternative implementations

As I researched location based proximity searches, I found a number of alternative solutions using PHP and MySQL. Some of which included stored procedures, and other advanced uses of MySQL. I’m nearly positive other implementations would require less computing power and run a bit faster, but I chose not to take that path because I wanted to keep the functionality as lightweight and portable as possible.

The queries used in the search function are performing quite a bit of math, and probably won’t scale extremely well. If you’re only looking to implement a location search on a smaller set of data (under 10,000 or so) I think using something like this will work for you as well.

Other uses

With Pods making a location based ZIP code search so easy, I’m hoping to implement it on more client projects since it won’t affect the budget very much. Some initial use cases that come to mind are:

• Member directory searches
• Service area searches
• Geographic zone searches
• Event listings

The next step I’d take with an implementation such as this would be to remove the requirement of entering your ZIP code manually altogether and instead use geolocation to automatically generate a starting point for the visitor.

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