Using Input Helpers in Pods CMS for WordPress

Posted: March 22, 2010 Comments(9)

Pods CMS really aims to be a framework in the sense that you can do anything you want with it. The approach of the developers always seems to keep that in mind, which is sometimes the most difficult thing to do when writing software.

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.

Setting up a WP Page Pick column in Pods

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:

The default output of a Pick column in Pods CMS

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.

Screenshot outlining how to create an Input Helper in Pods CMS

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:

Applying an Input Helper to an input column in Pods CMS

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:

Screenshot illustrating that our WP Page Pick column has indeed been filtered

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.

Get my newsletter

Receive periodic updates right in the mail!

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

Comments

  1. Just checked out your site for the first time, great to see a fellow Pods fanatic! Truth be told I don’t know much about Pick Filters beyond what the Codex offers. It mentions that it interacts with the SQL itself, and on top of that I found a thread which seemed a bit intimidating as well.

    Additionally, what lead me to use an Input Helper was a suggestion by Scott to use one. You’ve definitely piqued my interest in using a Pick filter, though. Did you happen to write a piece on it or have any more information?

  2. I don’t have anything written on it, but basically it just adds a WHERE clause to the SQL query. In this case, since you’re just filtering on the post ID, your filter would be:

    ID in (2, 31, 18, 23)

    Of course, this only works for simple filtering. In that thread you linked to, you mentioned that you were planning to filter the pages based on data in another table, so you will probably need to use an input helper in that case.

    Either way, keep up the great writing! ๐Ÿ™‚

  3. Just wanted to share my appreciation for the great pods tutorials you’ve been adding – I’ve read every one of them and hope you make more!

  4. Hi,

    Just got into WordPress and will soon be launching my re-vamped website on the platform. Very, very interested in WP and now also Pods and this website has been a mine of information so thank you for that. I have a question which might be a little generic but it does relate to the information above. So please may I ask…

    I have a project where I want to allow a client to manage some data held by me, so Pods looks great, however, I’m not quite clear on how the client makes use of them. The screenshots above show the screens where the data can be entered by the client – is that actually inside WordPress’ wp-admin pages? As I wouldn’t want to give the client access to control the whole rest of the website. Pods are obviously set up within the admin section of WordPress but how does the Client access them?

    Thanks again for a great resource.

    Best wishes,

    Gareth.

  5. Yes, Pods uses the WP Admin to manage the data, but you could technically get creative and build a front-end based system using the Pods API, but that’s quite an ambitious angle to take. Instead I’d recommend using something like Members and giving your client a very specific user role and granting access only to your Pods.

Leave a Reply

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