Home » Documentation » What is PeoplePods? » Creating New Pods

Creating New Pods

Pods are reusable modules that define areas of functionality on a PeoplePods site. Each pod lives in it's own folder, and contains the following elements:

  • A file called '/readme/creating_new_pods/settings.html' which contains an API call that describes the pod and how it works to PeoplePods.
  • One or more script files containing PHP code and SDK calls.
  • Any custom template files referenced within the scripts.

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.

Set Up Your New Pod

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 two files blank files: settings.php and index.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/index.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'=>'/readme/creating_new_pods/custom_welcome/index.html'
  ),
  array()
);

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 index.php script. That is, once this pod is enabled, the url "http://mywebsite.com/welcome" will actually execute the code inside this pod.

This pattern can contain multiple parameters, and may include wildcards. This allows you to define 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 final 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.

Index.php

The index.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.html");
$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.html");
$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 index.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 "Turn On" to enable the pod. 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.

Template files are located inside of themes, which are located in the themes/ folder of your PeoplePods installation. By default, PeoplePods uses a theme called default, located in themes/default/.

Inside each theme are many template files, spread across a few folders. Template files for outputting a person object are inside the people/ folder, whereas template files for outputting a content object are inside the content/ folder.

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

/mywebsite/peoplepods/themes/default/content/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 index.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.

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

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

If we wanted to be extra clever, we could shorten this code even further by using stack object's output() function. This is just like the content object's output function, except that it will cause each item in the stack to output itself without having to use the foreach() loop:

$recent_posts->output('recent_post');

Again, the output should be exactly the same as before.

It should be noted that, theoretically, we could also move the actual welcome message to a template within the people/ folder, and instead of printing it in the pod's code, simply call the output() function on the person object. However, since we're not going to be reusing that markup anywhere, and because it only appears once on the page, it's not necessary to add another template file in this case.

Our completed pod code should now look like this:

include_once("/PeoplePods.html");
$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();
$recent_posts->output('recent_post');

$POD->footer();

At this point, you've got a fully functioning custom pod! You can turn it on and off via the admin tools, and you can customize its display by modifying the recent_post template file instead of hacking into the pod's code. 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

No comments have been posted yet.

Download Download the latest version of PeoplePods!

0.7 Latest Version:
Release Notes

A free membership is required to download PeoplePods.

  Already Registered? Login

Recent Posts from Our Blog

PeoplePods powers MediaBugs.org and the Helsinki Design Lab

April saw the launch of two brand new PeoplePods-powered applications. These new sites use the latest version of PeoplePods - 0.8 - which will be available to download at the end of...

Version 0.7 Now Available

Last night, I uploaded a new release of PeoplePods: version 0.7. The most exciting new features in this version are: new dynamic image resizing options, a faster comment polling system, new ways...

Developer Preview Launch!

I am very excited to announce the launch of PeoplePods version 0.666, THE DEVELOPER PREVIEW! After tons of hacking, I have tweaked the last line of code, and I am finally ready for a wider audience...