Using Input Helpers in Pods CMS for WordPress

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.

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.