Wordpress Pods

User Guide – v1.0

http://pods.uproot.us/user_guide

Wordpress Pods - User Guide.doc

 Table of Contents
Section Page
Basic Info......................................................................................................................................................................... 3
1. Introduction ........................................................................................................................................................... 3
1.1 How Pods Works................................................................................................................................................ 3
1.2 Server Requirements ......................................................................................................................................... 3
1.3 Installation.......................................................................................................................................................... 3
1.4 Adding a Pod ..................................................................................................................................................... 3
1.4.1 Adding Pod Columns................................................................................................................................... 3
1.4.2 Column Types............................................................................................................................................. 4
1.5 Adding Pod Items............................................................................................................................................... 4
1.6 Displaying Pod Items (Example)......................................................................................................................... 4
1.6.1 Step 1: Configure the Templates ................................................................................................................. 4
1.6.2 Step 2: Fire up the Pod Class...................................................................................................................... 5
General Topics................................................................................................................................................................. 6
2. Introduction ........................................................................................................................................................... 6
2.1 Pod Pages ......................................................................................................................................................... 6
2.1.1 List Page..................................................................................................................................................... 6
2.1.2 Detail Page ................................................................................................................................................. 7
2.1.3 Detail Page (w/ Slug Support) ..................................................................................................................... 7
2.2 Templates.......................................................................................................................................................... 7
2.2.1 Example (List Template).............................................................................................................................. 7
2.2.2 Example (Detail Template) .......................................................................................................................... 8
2.2.3 Usage ......................................................................................................................................................... 8
2.2.4 Bypassing Templates .................................................................................................................................. 9
2.3 Helpers .............................................................................................................................................................. 9
2.3.1 Display........................................................................................................................................................ 9
2.3.2 Before Helpers ...........................................................................................................................................10
2.3.3 After Helpers..............................................................................................................................................10
2.4 Magic Tags .......................................................................................................................................................10
2.4.1 Format .......................................................................................................................................................10
2.4.2 Built-in Magic Tags.....................................................................................................................................10
2.4.3 Examples...................................................................................................................................................11
2.5 List Filters .........................................................................................................................................................11
Advanced Topics ............................................................................................................................................................12
3. Introduction ..........................................................................................................................................................12
3.1 Roles ................................................................................................................................................................12
3.2 findRecords() ....................................................................................................................................................12
3.2.1 Format .......................................................................................................................................................12
3.2.2 Examples...................................................................................................................................................13
3.2.3 Usage ........................................................................................................................................................14
3.3 Menu Editor ......................................................................................................................................................14
3.3.1 Adding Menu Items ....................................................................................................................................14
3.3.2 Usage ........................................................................................................................................................14
3.4 Public Forms.....................................................................................................................................................14
3.4.1 Displaying a Public Form for Adding Items (Example).................................................................................14
3.5 Editing Using Public Forms (Example)...............................................................................................................15
3.6 Relationships ....................................................................................................................................................16
3.7 Database Diagram ............................................................................................................................................17

Wordpress Pods - User Guide.doc

 Section 1
Basic Info
1. Introduction
The goal of this section is to introduce the Wordpress Pods plugin.

1.1 How Pods Works

A content type is fancy lingo for "a named group of fields".

WordPress has two main content types out-of-the-box: blog posts and pages. The Pods plugin allows you to
create, manage, and display custom content types in WordPress.

Pods physically breaks out each new content type (pod) into their own database table. This is for efficiency as
well as the ability to connect data from different content types. Other CMS plugins "hack" blog posts by storing
data into WP Custom Fields. The disadvantage of this approach is that Custom Fields make it all but impossible
to find and display groupings of similar items.

Pods makes it possible to create a content type, such as Events, and easily pull in items that match certain
criteria. E.g. Find all past events in Virginia attended by John Doe.

If you've been looking for a clean, lightweight alternative to Drupal/CCK or Joomla, then look no further.

1.2 Server Requirements

 Wordpress 2.7 or above.
 Apache (.htaccess).
 PHP 5.2 or above.
 MySQL 4 or above.
 wp-content/plugins/pods must be readable by the server.

1.3 Installation
1. Unzip the pods folder into wp-content/plugins/.
2. In Settings > Permalinks, set the Custom Structure to /%postname%/.
3. Enable the plugin through Plugins > Installed.

1.4 Adding a Pod

1. In Admin, click on Pods » Setup.
2. Click on the "Add new pod" button.

1.4.1 Adding Pod Columns

1. In Admin, click on Pods » Setup.
2. Click on the pod you want to change (if any exist).
3. Click the "Add a column" button.

Wordpress Pods - User Guide.doc

1.4.2 Column Types
 date - builds a date picker.
 number - integer (1,2,3) or currency (12.50, 100.00).
 boolean - generates a checkbox (True/False, Yes/No).
 text - short text (name, caption, URL).
 desc - long text (article body).
 code - long text (without the WYSIWYG editor).
 slug - a permalink (for pretty URLs).
 file - uses the WP file manager, saves the file URL.
 pick - relationship with a pod, post, page, parent category, or user.

1.5 Adding Pod Items

Once you create some Pods (in Pods > Setup), you'll be able to add new items using the Pods menu. If you
added a new pod called "event", then a new menu item named "Add event" will appear.

1.6 Displaying Pod Items (Example)

Let's start with a pod called event. It contains the columns: name, body, and start_date.

1.6.1 Step 1: Configure the Templates

In your event pod, there are List Template and Detail Template boxes. The List Template is used to display
groupings of Pod items, and the Detail Template is for displaying more information about a single item. Ideally,
each item in a List Template has a link to that item's own detail page. If a Pod listing has 10 items, then the
List Template will be executed 10 times. Below is some example List Template code:

<p class="list-item"><a href="{@detail_url}">{@name}</a></p>

…and some example Detail Template code:

<h2>{@name}</h2>
<p class="date">Starts on {@start_date}</p>
<p class="description">{@body}</p>

List and Detail Templates don't allow for PHP code, but they do support Magic Tags: {@column_name}. Magic
Tags simply pull in the value of the respective column. {@detail_url} is a placeholder Magic Tag, and can be
swapped out for a custom URL if needed.

Wordpress Pods - User Guide.doc

1.6.2 Step 2: Fire up the Pod Class
The PHP code needed to display Pod items can go either within a PodPage or a WP Template file (in your
active theme directory). Below is an example of how to call the Pod class:

<?php
// Start using the "event" pod
$Record = new Pod('event');

// Find 50 records, in descending order by id

$Record->findRecords('id DESC', 50);

// Use the Pod's List Template... and you're done!

echo $Record->showTemplate('list');

// You can optionally show List Filters & Pagination

echo $Record->getFilters();
echo $Record->getPagination();
?>

Wordpress Pods - User Guide.doc

 Section 2
General Topics
2. Introduction
The goal of this section is to introduce the general topics for the Wordpress Pods plugin.

2.1 Pod Pages

PodPages are a lot like WP Pages, but with a few key enhancements:

 There's no WYSIWYG editor to get in the way.

 PodPages support PHP, HTML, and client-side languages (e.g. Javascript).
 PodPages support wildcard URIs, useful for eliminating the need for many (slightly) different page
templates. If you create a PodPage with the URI of "/events/*/", then it'll be used for "/events/25/",
"/events/my-event/", and even "/events/2009/01/". The wildcard makes it the default handler of these
pages, until a more specific PodPage (e.g. "/events/2009/*/") gets added.

2.1.1 List Page

For an event listing page, just create a PodPage called "/events/" and enter the following code:

<?php
// Fire up the Pod class
$Record = new Pod('event');

// Find 25 records in alphabetical order

$Record->findRecords('name ASC', 25);

// Display the dropdown filters and search box

echo $Record->getFilters();

// Use the List Template to output the records

echo $Record->showTemplate('list');

// Display the pagination

echo $Record->getPagination();
?>

Wordpress Pods - User Guide.doc

2.1.2 Detail Page
For an event detail page, just create a PodPage called "/events/*/" and enter the following code:

<?php
// Find the ID from the URI
$uri = explode('/', $_SERVER['REQUEST_URI']);
$id = $uri[2];

// Fire up the Pod class

$Record = new Pod('event', $id);

// Use the Detail Template to output the records

echo $Record->showTemplate('detail');
?>

2.1.3 Detail Page (w/ Slug Support)

Some users would prefer their detail pages looking like /events/some-event/ instead of /events/29/ or
/detail/?type=event&id=29. Fortunately, slug support was recently added to Pods, making this a reality.

 Create a "slug" column in your event pod (name it "permalink" for this example).
 In the event pod's List Template box, replace {@detail_url} with "/events/{@permalink}/".
 Create a new PodPage called "/events/*/", and enter the following code:

<?php
// Find the slug name from the URI
$uri = explode('/', $_SERVER['REQUEST_URI']);
$slug_name = $uri[2];

// Find the event item with this slug name

$Record = new Pod('event', $slug_name);

// Call the Detail Template

echo $Record->showTemplate('detail');
?>

2.2 Templates
Templates are used for customizing the look and feel of certain data pulled from the database. Templates support
HTML, CSS, and Magic Tags. Magic Tags are little bits of code used to pull column values into templates.

List Templates are used for displaying groupings of items, whereas Detail Templates display information on a
specific item. Multiple templates can be pulled into PodPages or WP Template files.

2.2.1 Example (List Template)

This code goes into a pod's List Template box.

<p><a href="{@detail_url}">{@name}</a></p>

Wordpress Pods - User Guide.doc

2.2.2 Example (Detail Template)
This code goes into a pod's Detail Template box.

<h2>{@name}</h2>
<div class="italic">Created on {@date}</div>
<div class="content">{@body}</div>

2.2.3 Usage
This code goes into either a PodPage or a WP Template file (in the active theme folder).

<?php
$Record = new Pod('event');
$Record->findRecords('id DESC', 15);
echo $Record->showTemplate('list');
?>

The above example demonstrates how to call a List Template using showTemplate(). Below is an example of
how to implement the Detail Template.

<?php
// Find the ID from the URI (modify this code if needed)
$uri = explode('/', $_SERVER['REQUEST_URI']);
$id = $uri[2];

// Pass the ID into the Pod class

$Record = new Pod('event', $id);

// Display the Detail Template

echo $Record->showTemplate('detail');
?>

You can also override the template code on a per-page basis:

<?php
$override = '<p><a href="{@detail_url}">{@name}</a></p>';
echo $Record->showTemplate('list', $override);
?>

Wordpress Pods - User Guide.doc

2.2.4 Bypassing Templates
There might come a time when you want to skip using List or Detail templates altogether. This code would live on
either a PodPage or a WP Template file.

<?php
// Bypass the List Template
$Record = new Pod('event');
$Record->findRecords('id DESC', 15);
while ($Record->fetchRecord())
{
// Display the "start_date" column
echo $Record->get_field('start_date');
}
?>

<?php
// Bypass the Detail Template
$Record = new Pod('event', $id);

// Display the "start_date" column

echo $Record->get_field('start_date');
?>

2.3 Helpers
Helpers come in 3 different flavors, and each "flavor" serves a distinct purpose.

2.3.1 Display
A display helper's purpose is to modify a column's value before outputting it to the user. These are column-level
functions that can be called in the following ways:

1. Column edit box: display helpers can be defined from the column itself. If used, the column's value
would be modified globally.
2. Magic Tags: a display helper name can be entered as the 2nd parameter within a Magic Tag. If so, the
column's value would be modified for this instance, but not globally.
3. PodPages: after you've defined a new Pod(), you can use pod_helper('helper_name', 'column_name');
?>

When using a helper, the following are available at your disposal:

 $name: the current column's name.

 $value: the current column's value.
 $this->get_field('column_name'): get any single field value from the current item.
 $this->set_field('name', 'value'): set any single value.
 $this->data: an array of all fields and their values.

Wordpress Pods - User Guide.doc

2.3.2 Before Helpers
Before helpers are pod-level functions that execute RIGHT BEFORE any data is saved to the database. These
functions have access to all of the current item's fields. Before helpers have a myriad of potential uses, such as
for complex data validation.

2.3.3 After Helpers

After helpers are pod-level functions that execute RIGHT AFTER an item is successfully saved to the database.
These functions have access to all of the current item's fields, and are useful for doing any sort of post-
processing. Some potential uses include sending confirmation emails, running update scripts, etc.

2.4 Magic Tags

Magic Tags are used exclusively within templates to dynamically pull in column values.

2.4.1 Format
This is the format in which to use Magic Tags within templates.

{@column_name[,display_helper][,before_text][,after_text]}

2.4.2 Built-in Magic Tags

These Magic Tags are available to choose from in addition to the column names.

// The item's ID
{@id}

// The item's pod type

{@type)

// The date the item was created

{@created)

// The date the item was last modified

{@modified)

// The item's DEFAULT detail page URL

// (equivalent to /detail/?type={@type}&id={@id})
{@detail_url}

Wordpress Pods - User Guide.doc

2.4.3 Examples
Below are a few examples of how you would use Magic Tags within your templates.

// Display the "name" column's value

{@name}

// Display the "body" column's value

{@body}

// Pass the "date" column's value through

// the "format_date" display helper
{@date,format_date}

// Wrap the "body" column's value in P tags

// (ONLY if a value exists)
{@body,,<p>,</p>}

// Wrap the "body" column's value in P tags

// (EVEN if the value is empty)
<p>{@body}</p>

2.5 List Filters

List filters are dropdowns that can appear on list pages, allowing users to filter content. Each Pod has an input
box called List Filters, which takes a comma-separated list of PICK columns to be used as filters. The filters are
then automatically generated by calling:

<?php echo $Record->getFilters(); ?>

You can also override the filters on a per-page basis:

<?php
$override = 'state,country';
echo $Record->getFilters($override);
?>

Lastly, you can change the label of the submit button by using the 2nd parameter:

<?php echo $Record->getFilters(null, 'Apply Filters'); ?>

Wordpress Pods - User Guide.doc

 Section 3
Advanced Topics
3. Introduction
With Pods, you can choose which roles have access to which Pods abilities. For each role's select box, simply
select the abilities to allow. To add new roles, please refer to the Role Manager plugin.

3.1 Roles
This document details the installation and usage of the Bed Data Demo application software.

3.2 findRecords()
The findRecords() function allows you to customize which items to display for any item listing.

3.2.1 Format
findRecords() supports 4 optional parameters:

findRecords($orderby, $limit, $where, $sql);

1. $orderby (default = 'id DESC')

2. $limit (default = 15)
3. $where (default = null)
4. $sql (default = null)

Wordpress Pods - User Guide.doc

3.2.2 Examples
Refer to the example Pods below for more info.

event person
id id
name (txt) name (txt)
start_date (date) first_name (txt)
location (desc) last_name (txt)
attendees (pick person) date_of_birth (date)
email (txt)

// Get 20 people ordered by last name

$Record = new Pod('person');
$Record->findRecords('last_name ASC', 20);

// Get 10 people with the first name of "Matt"

$Record = new Pod('person');
$Record->findRecords('id DESC', 10,
"t.first_name = 'Matt'");

// Get the 20 nearest upcoming events

$Record = new Pod('event');
$Record->findRecords('start_date ASC', 20,
"t.start_date >= NOW()");

// Get 5 events attended by "Matt Gibbs",

// sorted by newest event first
$Record = new Pod('event');
$Record->findRecords('start_date DESC', 5,
"attendees.name = 'Matt Gibbs'");

// Get 5 events attended by anyone named

// "Matt" or "Scott", sorted by event name
$Record = new Pod('event');
$Record->findRecords('name ASC', 5,
"attendees.first_name IN ('Matt', 'Scott')");

// Get 5 events attended by anyone named

// "Matt", sorted by the person's last name
$Record = new Pod('event');
$Record->findRecords('attendees.last_name ASC', 5,
"attendees.first_name = 'Matt'");

*NOTE* prefix all non-PICK columns with t., and all PICK columns with the pick column name [dot] the pick's
pod column to use (e.g. "attendees.first_name").

Wordpress Pods - User Guide.doc

3.2.3 Usage
This is the complete implementation. Please refer to the above section for available findRecords() options.

<?php
$Record = new Pod('event');
$Record->findRecords('name ASC', 25);
echo $Record->showTemplate('list');
?>

3.3 Menu Editor

Pods allows you to define your own menu structure. Once this structure is created, you can display it (or parts of
it) on your site. This is perfect for adding primary or local navigations.

3.3.1 Adding Menu Items

When you first go to the Menu Editor, you'll see the "Home" section with a little icon next to it. Clicking on the icon
will allow you to add a new child item to Home. You can keep adding children (or edit existing menu items) by
clicking on the appropriate radio button in the edit box. You may need to refresh the page before adding child
items to new menu items.

3.3.2 Usage
When your menu structure is ready, use pods_navigation() within a PodPage or WP Template file to display it.

<?php
// Display items from Home up to 1 level deep
echo pods_navigation();

// Same as above (top level navigation)

echo pods_navigation('/', 1);

// Display the entire menu structure

echo pods_navigation('/', 0);

// Display the "/about/" page and everything in it

echo pods_navigation('/about/', 0);

// Display the "/about/" page and up to 3 levels deep

echo pods_navigation('/about/', 3);
?>

3.4 Public Forms

Public forms allow users to add new Pod items, or edit existing items, without needing to log in. Public forms can
be added onto Pod Pages.

3.4.1 Displaying a Public Form for Adding Items (Example)

This is the most basic way to add a public form, and it displays all columns.

Wordpress Pods - User Guide.doc

 <?php
// Change "event" to the Pod you want to use
$Record = new Pod('event');
echo $Record->publicForm();
?>

You can also choose which columns to show by using…

<?php echo $Record->publicForm(array('name', 'date', 'email')); ?>

or…

<?php
$fields = array('name', 'date', 'email');
echo $Record->publicForm($fields);
?>

You can also add field defaults like so:

<?php
$fields = array('name', 'date', 'email' =>
array('default' => 'foo@bar.com'));
echo $Record->publicForm($fields);
?>

If you want to set a field default while hiding the field (so it can't be changed):

<?php
$fields = array('name', 'status' =>
array('default' => 'Submitted', 'hidden' => true));
echo $Record->publicForm($fields);
?>

3.5 Editing Using Public Forms (Example)

You'll need to obviously tell pods which item to edit. The first step demonstrates how to retrieve an item's ID, and
the second part shows how to use the ID to build the edit form.

Wordpress Pods - User Guide.doc

 <?php
// 1. Find the ID (or slug) of the record
// you want to edit (if you don't have it already)
$Record = new Pod('event');
$Record->findRecords('id DESC', 1, "t.name = 'Some Item'");
$Record->fetchRecord();
$id = $Record->get_field('id');

// 2. Retrieve the specific pod item by

// passing in the unique identifier
$Form = new Pod('event', $id);
echo $Form->publicForm();
?>

3.6 Relationships
Relationships are created using PICK columns. A relationship column is essentially a select list, which shows all
the items of the related pod (or category) and allows you to select which items to relate to.

When creating a new pod column, you have the option of selecting which column type to use. Select PICK from
the dropdown menu. Another dropdown will appear with a list of Pods (and categories) that you can relate to.

Relating to another Pod

You can relate a column of one pod to another pod. Let's say you have two pods: "person" and "document". You
also created a column in the "document" pod called "Related Person". If you select PICK from the dropdown, then
select "person" from the relationship dropdown, that column is a relationship to the "person" pod.

Relating to a category
You can also relate a column to a parent category (a category with children). If you have any categories with
children (e.g. "Document Type"), then that parent category will show up in the relationship dropdown after
selecting the PICK column type.

Wordpress Pods - User Guide.doc

3.7 Database Diagram
The database diagram for the Wordpress Pods plugin is shown in Figure 1.

Figure 1: Wordpress Pods Database Diagram.

Wordpress Pods - User Guide.doc

Wordpress Pods - User Guide.doc