Creating New Pods

Pods are reusable packages of code that add functionality to a PeoplePods site. Thought PeoplePods ships with several example pods, most sites will need a few custom pods.

Pods = Features

Pods can create new pages and features on your site. For example, a pod could create an activity dashboard, an invite tool, or a member profile. Each pod can create multiple pages, so a single pod can both display member profiles, as well as creating all of the tools necessary for members to edit their profiles.

Pods can handle new types of content. This type of pod typically handles the input and output of the content - creating an editing interface for users, as well as a display mechanism. A great example of this is a pod that creates a posting form, archive page, and permalink pages for posts.

Pods can add custom functionality to the PeoplePods objects. Need to define custom behavior for your members or content? Pods can layer additional methods onto the core PeoplePods objects to expand their capabilities. For example, the "Twitter Connect" pod adds a new method to the Person object called postToTwitter() which posts messages to Twitter. Once enabled, $person->postToTwitter() is available throughout the site!

Pods allow you to customize functionality with site-specific settings. Sometimes a plugin requires a few pieces of extra information to function properly - an API key, an email address, or some configuration option. Pods simply specify a list of options, and they'll appear magically in the PeoplePods command center.

Pods can provide default templates used for input and output within the pod. These default templates come packaged with the pod, but can be overwritten by templates within a theme.

Components of a Pod

A pod consists of a few PHP and template files. All of these files will live together in a folder, which in turn lives in the pods/ folder of your PeoplePods install.

settings.php contains a single command which tells PeoplePods what your pod does and how it interacts with the rest of the site. This command sets up the URLs that will be handled, defines where external methods are stored, and tells PeoplePods what configuration options are needed. This command is called $POD->registerPOD().

handler.php contains the main code for your pod. The code within handler.php is essentially treated like a standalone script, though it is tied into the rest of the site via the PeoplePods theme and functionality. There may be more than one file like handler.php within your pod depending on the requirements and complexity of the feature being defined. For example, if a pod handles more than one type of URL, you may want to create a separate file for each type in order to keep your code organized. Each handler must include the PeoplePods library file, instantiate a $POD object, and print the header and footer of the site.

methods.php contains additional methods that will be added to the core PeoplePods objects at runtime. In addition, it contains an optional setup function which defines a list of settings variables that are used by the command center. At the bottom of this file, each method must be added to the appropriate object using the registerMethod function.

Local template files may also be included within the pod. These template files should represent the default or standard interface to the pod, which may be overwritten by including a matching template file in the site's theme.

Set Up Your New Pod

In this tutorial, we will explain each of these components and walk you through the creation of a new pod. This example pod will create a welcome page that displays a personalized message to the visitor.

The first step to creating a new pod is to create a new folder in your PeoplePod's installation under the pods/ folder. The name of the folder should match the name of your new pod. For our example, we'll create a folder called "custom_welcome"

Inside this folder, immediately create three files blank files: settings.php, handler.php, and methods.php.

Once you're done, you should have a file structure something like this:

/mywebsite/peoplepods/pods/custom_welcome/settings.php

/mywebsite/peoplepods/pods/custom_welcome/handler.php

/mywebsite/peoplepods/pods/custom_welcome/methods.php

Settings.php

The settings.php file tells PeoplePods how to integrate the pods functionality into the site. It tells PeoplePods what the pods name is, describes it's functionality, sets up the path to the new functionality, and defines any system-wide variables the pod requires.

This file should contain just one command, a call to $POD->registerPOD().

For our example pod, we'll put the following code:

$POD->registerPOD(
  'custom_welcome',
  'display a custom welcome page',
  array(
    '^welcome'=>'custom_welcome/handler.php'
  ),
  array(),
  dirname(__FILE__) . "/methods.php",
  'customWelcomeSetup'
);

SWEET FANCY MOSES, that looks complicated! But don't fret! Let's break it down.

The first parameter we pass to registerPOD is the name of the pod. This is the same as the name of the folder you created above.

The second parameter is a short description of the pod. This is what will be displayed in the admin tools.

The third parameter is where we start to get tricky. This parameter is an array that defines the URL mapping, which is then used to build one or more mod_rewrite rules that tell your web server what to do. For each URL pattern you want to map, you'll add a value to this array.

In our example above, we are mapping the url /welcome to the code contained within the handler.php script. That is, once this pod is enabled, the url "http://mywebsite.com/welcome" will actually execute the code inside handler.php.

This pattern can contain multiple parameters, and may include wildcards. This allows you to create patterns that actually define many dynamic pages, such as content permalink pages. Read the registerPOD() page for information on how to construct these patterns.

The fourth parameter is an optional array of key/value pairs that will be available to all of PeoplePods when this pod is enabled. For this example pod, we don't need anything here. This parameter is most often used to define the permalink structure for new content types.

The fifth parameter should contain the path to the methods.php file. In almost all cases, this should be dirname(__FILE__) . "/methods.php", which points to the methods.php located within the pod directory. This parameter is optional - if you don't need to add methods or provide settings, it is safe to ignore this parameter.

The sixth parameter is a string which should contain the name of a function contained within methods.php that will return a list of the necessary settings for this pod. This function will be called from within the PeoplePods command center to construct a settings form.

Handler.php

The handler.php file contains the actual code of the module. You may have all of your code in one file, or you may have multiple files that provide different pieces of the functionality. Regardless, each file will follow the same basic structure.

The first thing we need to put in this file is a call to include the PeoplePods library and boot up the $POD object. As part of the boot up, we pass in the authentication cookie that identifies the current user, a parameter that describes the minimum access level a person must have to access the pod, and a debug level. These options are described in more detail here. In this example, we are not putting any access restrictions on this page, and we're turning off the debug information.

include_once("../../PeoplePods.php");
$POD = new PeoplePod(array(
  'authSecret'=>$_COOKIE['pp_auth'],
  'lockdown'=>null,
  'debug'=>0
));

After the $POD has been created, you'll want to actually do something with it. We'll start off by calling the header() and footer() functions which will wrap the pod's output in the site's header and footer:

include_once("../../PeoplePods.php");
$POD = new PeoplePod(array(
  'authSecret'=>$_COOKIE['pp_auth'],
  'lockdown'=>null,
  'debug'=>0
));

$POD->header('Welcome!');

// the pod's main code will go here

$POD->footer();

Now, all that's left is to write the custom code that will power the pod. Like any PHP script, you can put code and HTML markup here, though most of the markup should live in template files. For this example, we'll start by putting everything in the pod file, then later we'll move some of it into a new template file.

For our example, we're going to do something really, really basic: print a personalized welcome message to the current visitor. The visitor may be a member of the site, or they may be anonymous - that is, not logged in. So we'll have to tap into the PeoplePods library to do some basic logic - checking to see if the person is authenticated, then printing one of two messages. Put this code in between the calls to header() and footer().

if ($POD->isAuthenticated()) { 
  echo "Welcome back, ";
  $POD->currentUser()->write('nick');
} else {
  echo "Hello stranger!  Welcome to PeoplePods.";
}

At this point, you've got a fully functioning pod! Save the handler.php file and the settings.php file, and load up your PeoplePods admin tool. Navigate to Options -> Plugin Pods, and you should the name and description of your new pod in the list. Click the checkbox next to your new pod, then click the "Update" button. If everything has been set up correctly, you should now be able to navigate to "http://mywebsite.com/welcome" and see the output of the new pod, which should look something like this:

Welcome back, admin

Wow! Wow!

Ok, it is a bit boring. Let's give the visitor a little something extra to look at. How about a list of the most recent content posted to the site? Easy! We'll just use the getContents() function. (This is a very simple use of this function - check the function page for more information on customizing what content you load.) This code will load the most recent content of any type, then print out a paragraph for each post with a link to the post and a timestamp. Add it underneath the code you just added:

$recent_posts = $POD->getContents();
foreach($recent_posts as $post) {
  echo "<p>";
  $post->permalink();
  echo ", posted ";
  $post->write('timesince');  
  echo "</p>"
}

Now, you're output will look something like this:

Welcome back, admin

Post #5, posted 15 minutes ago

Post #4, posted 20 minutes ago

Post #3, posted 1 hour ago

Post #2, posted 1 day ago

Post #1, posted 5 days ago

Not too shabby! But having the markup of the content list in the pod is a bit messy, and will make the pod more difficult to manage in the future when modifications to the output styles are required. We can fix this by moving the markup for the content into a new template file.

Custom Template Files

PeoplePods allows you to create template files for any bit of markup or code you are going to use or reuse. This allows you to separate the application logic from your presentation.

For this example, we are going to create a new template file inside pod folder called "recent_post.php" So, when you're done, your file structure should be:

/mywebsite/peoplepods/pods/custom_welcome/recent_post.php

Inside this file, we want to put the code and markup that represents the output of one piece of content. This code and markup will then be re-used for each item in the $recent_posts list. Inside the template, we still have access to the $POD variable, and we also have a new variable called $content which represents the piece of content that is being displayed. So, inside of recent_post.php, put the following code:

  echo "<p>";
  $content->permalink();
  echo ", posted ";
  $content->write('timesince');  
  echo "</p>"

Save the new template file. Now, go back to your pod's handler.php file and strip out the markup that you just moved to the template, and replace it with a call to the content object's output() function. Notice that we pass in the name of the new template file to the output function, as well as the path to the pod folder.

foreach ($recent_posts as $post) {
  $post->output('recent_post',dirname(__FILE__));
}

Save your handler.php file, and reload the welcome page in your browser. The output should look exactly the same as before!

Now, after we've finished our pod and released it for other developers to use, this template will be included along with the code. If a developer wants to use a custom version of the template, instead of modifying the file inside the pod, they may create a version within their theme, and PeoplePods will use the custom version instead. This allows the pod to be safely upgraded without overwriting custom modifications.

Our pod code should now look like this:

include_once("../../PeoplePods.php");
$POD = new PeoplePod(array(
  'authSecret'=>$_COOKIE['pp_auth'],
  'lockdown'=>null,
  'debug'=>0
));

$POD->header('Welcome!');

if ($POD->isAuthenticated()) { 
  echo "Welcome back, ";
  $POD->currentUser()->write('nick');
} else {
  echo "Hello stranger!  Welcome to PeoplePods.";
}

$recent_posts = $POD->getContents();

foreach ($recent_posts as $post) {
  $post->output('recent_post',dirname(__FILE__));
}

$POD->footer();

Methods.php

We've now got a fully functioning custom pod that displays a simple welcome message to the user on a simple welcome page. But what if we wanted to be able to display that welcome message on ANY PAGE of the site? To do this, we create an extra method, and attach it to one of PeoplePods' core objects.

Additional methods look just like normal functions, and take as their first parameter the object which is being extended. So, to create a simple function that extends the $POD object, we would write:

function welcomeMessage($POD) {

	if ($POD->isAuthenticated()) { 
		echo "Welcome back, ";
		$POD->currentUser()->write('nick');
	}  else {
		echo "Hello stranger! Welcome to PeoplePods";
	}

}

PeoplePod::registerMethod('welcomeMessage');

Pay special attention to that last line of code. The registerMethod function is required so that PeoplePods knows about your function. Without it, your function will not be available outside of the methods.php file.

Once this function has been added to methods.php, it will be available in this and ALL OTHER pods. You can use it within any pod and any template, anywhere on the site.

So, go back into your handler.php, and update it to use the new function:

include_once("../../PeoplePods.php");
$POD = new PeoplePod(array(
  'authSecret'=>$_COOKIE['pp_auth'],
  'lockdown'=>null,
  'debug'=>0
));

$POD->header('Welcome!');

// call our new custom method!
$POD->welcomeMessage();

$recent_posts = $POD->getContents();

foreach ($recent_posts as $post) {
  $post->output('recent_post',dirname(__FILE__));
}

$POD->footer();

Methods can be added to any of the core objects. Read all about adding methods here.

Pod Settings

If your new pod contains information that might change on a site-by-site basis, such as specific messages, API keys, or personalized settings, this information should be stored in a pod setting variable. You define pod settings using a setup function - in our example, we called this setup function "customWelcomeSetup," so we need to define this function within the methods.php file.

The setup function is VERY SIMPLE and only needs to do one thing - return an array of variable names. For our example, we'll create 2 settings: a message to display to logged in users, and another message to display to logged out users.

function customWelcomeSetup() {
	return array(
		'user_welcome'=>'Welcome message for logged in users',
		'stranger_welcome'=>'Welcome message for anonymous users'
	);
}

Once the function has been created within methods.php, navigate back to your PeoplePods command center and go to the Options -> Plugin Pods screen. When you scroll down to your plugin, you should see a "settings" link next to the description of the plugin. Clicking this link should take you to a form where your 2 new fields are displayed!

Now that we've stored our custom welcome messages, we need to actually use them in our pod. Lets revisit our custom welcomeMessage() method and revise it so that it uses these messages. We use the $POD->libOptions() function to access these values.

function welcomeMessage($POD) {

	if ($POD->isAuthenticated()) { 
		echo $POD->libOptions('user_welcome');
		$POD->currentUser()->write('nick');
	}  else {
		echo $POD->libOptions('stranger_welcome');
	}

}

PeoplePod::registerMethod('welcomeMessage');

Now, when you visit mywebsite.com/welcome, you should see your custom messages displayed!

Install Function

You may optionally define a function that is called automatically when a pod is enabled via the Command Center. This function can initialize values, add fields to the database schema, or do anything else that is required by the pod to function.

Install functions should be defined in a pod's methods file, and must accept a $POD object as a parameter:

// In settings.php:
$POD->registerPOD(
  'custom_welcome',
  'display a custom welcome page',
  array(
    '^welcome'=>'custom_welcome/handler.php'
  ),
  array(),
  dirname(__FILE__) . "/methods.php",
  'customWelcomeSetup',
  'myPodInstall'
);

// in methods.php
function myPodInstall($POD) {
// do something here
}

Uninstall Function

Just like the install function, you may optionally define a function that is called automatically when a pod is disabled via the Command Center. This function can cleanup any settings values, remove fields from the database schema, or do anything else necessary to clean up.

Uninstall functions should be defined in a pod's methods file, and must accept a $POD object as a parameter:

// In settings.php:
$POD->registerPOD(
  'custom_welcome',
  'display a custom welcome page',
  array(
    '^welcome'=>'custom_welcome/handler.php'
  ),
  array(),
  dirname(__FILE__) . "/methods.php",
  'customWelcomeSetup',
  'myPodInstall',
  'myPodUninstall'
);

// in methods.php
function myPodUninstall($POD) {
// do something here
}

Extending The Schema

As of version 0.9, plugin pods can make changes to the database schema. Developers may want to consider changing the schema instead of using the meta field facilities when a custom field is going to be used in a frequent search query. Modifying the schema may make queries more efficient.

PeoplePods does not provide a method for actually modifying the schema. You must do this via SQL commands called from an install function. But in addition to making the actual changes, you must tell PeoplePods how to handle the new fields. This allows PeoplePods to properly construct database queries.

You can specify additional fields in any of the PeoplePods object tables using the addDatabaseFields() command. In its simplest form, this command accepts an array of fields which have been added to the schema:

function myPodInstall($POD) {
$sql = "ALTER TABLE content ADD zipcodeplusfour varchar(10);";
$POD->executeSQL($sql);
}

function myPodUninstall($POD) {
$sql ="ALTER TABLE content DROP zipcodeplusfour;";
$POD->executeSQL($sql);
}

Content::addDatabaseFields(array('zipcodeplusfour'));

In addition to defining fields that should be treated as a native field instead of a meta field, you may also define fields that should never be stored - as a meta field or as a native field. To do these, use addIgnoreFields().

Sometimes, you may need to add a field to the database that requires additional processing, either when it is being pulled from the database, or when it is inserted into the database. By passing in a select modifier and/or an insert modifier, you can change the way PeoplePods constructs its database queries to handle your custom fields.

Select modifiers accept a PeoplePods object, and the name of the field being handled. They must return an array of SQL field select statements.

Insert modifiers accept a PeoplePods object, the name of the field being handled, and the current value. They must return an array of SQL field set statements.

The following example adds a 10-character field to the content table used to store a zipcode+4 value (78704-1234). Upon retrieving this value from the table, it will be split into its two constituent parts, and stored into 2 "fake" fields called "zipcode" and "plusfour." Upon saving, the two fake fields will be recombined into the full 10-character value.

function myPodInstall($POD) {
$sql = "ALTER TABLE content ADD zipcodeplusfour varchar(10);";
$POD->executeSQL($sql);
}

function myPodUninstall($POD) {
$sql ="ALTER TABLE content DROP zipcodeplusfour;";
$POD->executeSQL($sql);
}

Content::addDatabaseFields(array(
	'zipcodeplusfour'=>array(
		'select'=>'zipcodeSelect',
		'insert'=>'zipcodeInsert'
	)
));
Content::addIgnoreFields(array(
	'zipcode',
	'plusfour'
));


// this function adds additional field requests to the SELECT query
function zipcodeSelect($obj,$field) {

	return array(
		'LEFT(zipcodeplusfour,5) as zipcode',
		'RIGHT(zipcodeplusfour,4) as plusfour',
	}
}

// this function modifies how the UPDATE and INSERT queries handle the field
function zipcodeInsert($obj,$field,$value) {

	if (isset($obj->zipcode) && $isset($obj->plusfour)) {
		return array(
			'zipcodeplusfour="' . 
			$obj->zipcode . '-' . $obj->plusfour .
			'"',
		);
	}
}

You're done!

At this point, you've got a fully functioning custom pod! You can turn it on and off and customize the messages it displays via the admin tools, you can modify the output by creating a copy of recent_posts.php in your theme folder, and you can safely upgrade PeoplePods and this pod without overwriting your custom modifications. You can even share this pod with other PeoplePod's sites by simply zipping up the custom_welcome/ folder and sending it to other developers!

Further Reading

If you are going to develop your own pods, you will definitely want to familiarize yourself with the PeoplePods SDK.

The best way to start a new pod - the way we do it in the home office - is to copy an existing pod and make modifications.

We anticipate that one of the most popular uses of custom pods will be to create interfaces for new content types - that is, to add functionality to the site to support the creation and display of custom information. For details on how to make this specific kind of pod, read read this tutorial.

• Discuss This Document

Download the latest version of PeoplePods!

0.9 Latest Version:
Release Notes

Join the PeoplePods developer network and get direct access to documentation, additional plugins, and our forums!

Username:

What is your email address?

Choose a password:

  Already Registered? Login