What is PeoplePods?

PeoplePods is a framework that makes it easier to create community or "social" applications. It provides a flexible infrastructure within which members of a site can create, comment upon, and consume content of arbitrary types. Popular social functionality such as friend lists, personalized content views, bookmarking, and voting are automatically available within any PeoplePods application. PeoplePods can be used to build stand-alone sites, or can be layered onto existing sites such as those run using Wordpress or other PHP applications.

There are three main pieces of PeoplePods. The first is a software development kit that was built from the ground up to numb the pain of building a fun website that does cool stuff. The PHP-based, object-oriented libraries provides the underpinnings for all the basic services present on modern websites: log-in, personalization, content creation and management, and all of the above mentioned social actions. Thanks to the magic of object inheritance, all of the objects within the PeoplePods environment - people, documents, comments and groups - share common access methods and template conventions.

The second component is a package of plugin modules - we call them "pods" - that demonstrate the functionality of PeoplePods. The core pods are intended as examples to be customized by developers. However, using the modules and their accompanying templates, even non-programmers can create and customize PeoplePods sites that feature member profile pages, member created groups, private messaging, and member content creation. Those with a bit of programming experience will find the code within the pods easy to modify so that new functionality can be created or remixed from existing functionality.

Finally, PeoplePods has a full set of administrative tools that will allow the site's operator to keep an eye on activity and configure a number of optional features. These tools support normal member management tasks such as editing account details and resetting passwords as well as content moderation and editorial control tasks such as approving and featuring member content.

Getting Started

Read about how to install PeoplePods. It is a pretty straight forward process comparable to other web software you might have installed before.

Once you've got everything up and running, you'll probably want to start customizing your new PeoplePods site. This will probably start with some changes to the theme templates where you can change how the site looks with some basic CSS and HTML. A lot of what PeoplePods does is defined in the templates, so you'll get your feet wet quickly.

If you want to alter the functionality of the core pods or build your own functionality, the first thing you'll want to do is bookmark the quick start guide and SDK Documentation. Every single function you'll run across is documented there, as well as some coding conventions and examples.

We recommend that you use one of the core pods as the starting point for any new functionality. Read the guide to creating new pods, or more specific instructions on creating a new content type

Integrating PeoplePods into Existing Sites

You can boot up a $POD wherever you can run PHP. This allows you to add a social layer to existing content, or to create community features that integrate with existing functionality. PeoplePods is a great way to add or extend an existing website with features like member profiles, discussion areas, and member-created groups.

PeoplePods also includes a basic Wordpress plugin that grants developers easy access to PeoplePods functionality in any Wordpress template.

Read more about how to use PeoplePods on an existing site in the SDK documentation.

Creating a new content type

To create a new content type, use the core_usercontent pod as an example. This pod contains several files, including generic handlers for adding and editing content, viewing permalinks, viewing lists of content, adding comments, add accepting votes.

You can customize the content type by editing a simple config file and creating a few templates in your theme! However, you'll probably want to dig deeper into the code to add special functionality.

1) Copy core_usercontent pod to a new name

cp -R core_usercontent content_post
2) Edit the content_type.php file. This file contains information used by all the other files.

Set the $content_type variable to a short name for the new content type. No spaces!

	$content_type ='post';

Set the $permamlink variable tp first part of the permalink. This will be used to make links to each piece of content, as well as to the list of most recent content. We'll use "blog." This means we can get a list of new posts at /blog and each post will be located at /blog/title-of-post

	$permalink = 'blog';

Set the edit/add url. This means I can go to /edit to create a new post.

$edit_link = "edit";

Change the name of the edit form template. This template will be located in the theme/content folder and will be used on the add/edit page

	$input_template = 'postform';

Change the name of the default output template for the content permalink:

	$output_template = 'post';

Change the $pod_dir variable to the same name as the folder you created in step 1.

	$pod_dir = "content_post";

3) Go into your theme content directory. Copy editform.php to the new template you referenced in step 2.

cp editform.php postform.php

4) Make changes to the form design and fields.

You can create meta fields by naming them meta_fieldname

You can attach files by simply creating file inputs. The files will be named the same as thing as the input.

For example, if we wanted to add a meta field named "Via" we could add this to our form:

<input type="text" name="meta_via" value="" />

5) Copy output.php to the the new template you referenced in step 2.

cp output.php post.php

6) Load the PeoplePods Command Center, go to Options->Plugin Pods and turn on your new custom content type pods. They'll be called contenttype_YOURCONTENTTYPE_add, contenttype_YOURCONTENTTYPE_edit, and contenttype_YOURCONTENTTYPE_list.

7) Navigate to your new add/edit screen. You should see your new form. Create your first test post!

8) Your new post should show up at the top of your content list. Click on it. You should see that it goes to a new permalink url as descrived in step 2. But the template is the generic template!

9) Go back to your theme directory and customize post.php

VOILA!

You may want to change the access restrictions on your new content type pods. For example, you may want to restrict the add/edit pod to admin users. You can do this by changing the 'lockdown' parameter in the pod files.

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:

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/all/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.

Core Pods

core_api_simple provides a simple RESTful JSON api to many of the common functions you'll need to implement Ajax controsl.

core_authentication provides everything you need to enable visitors to join your site, verify their accounts, and manage their security preferences.

core_feeds provides a flexible method for producing lists and feeds of documents that match certain conditions.

core_files handles file attachements.

core_friends provides a friend management interface with friends, followers, and recommended friends.

core_groups provides an interface for members to create and join groups.

core_invite provides an email invitation tool so that members can invite their friends.

core_newest provides a simple list of the newest posts on the site.

core_private_messaging provides the ability for members to send messages to one another on the site, and to manage these conversations in an onsite inbox.

core_profiles provides member with ability to create and modify personal profiles.

core_search provides an interface for searching the content and the members of the site.

core_usercontent provides a default handler for generic content. creates the add/edit screen, the permalink pages, and the reverse cron list of content. Can be customized to create new content types!

dashboard provides a customized activity dashboard for members including new content from their friends, as well as new comments on content they're interested in.

Admin Tools

Installing PeoplePods

To install PeoplePods, you will need a web server, a MySQL database server, and a copy of the PeoplePods code.

NOTE: The PeoplePods archive contains a README.txt file which may have more up-to-date instructions!

  1. Download the latest version of PeoplePods from PeoplePods.net.
  2. Upload the archive to your web server and place it in whatever directory you want PeoplePods to live in.

    All of the PeoplePods code will live in a sub-folder of your website called "/readme/all/peoplepods/index.html" that is created when you uncompress the tarball. Thus, if you want PeoplePods functionality to be present on the homepage of your site, you'd place the tarball in the root directory of your site. If you want PeoplePods functionality to live in a sub-folder such as myurl.com/community, place the tarball into that folder.

    Example
    
    My web root is: /var/www/httpdocs
    My domain is: http://myurl.com
    
    If I want PeoplePods to control the homepage and other root
     elements of my site, I decompress my tarball into my webroot,
     and end up with:
    
    PeoplePods folder is: /var/www/httpdocs/peoplepods
    PeoplePods admin tool: http://myurl.com/peoplepods/
    PeoplePods homepage: http://myurl.com
    
    If I want PeoplePods to live in a sub-folder of my site, I would
     decompress my tarball into that subfolder, and end up with:
    
    PeoplePods folder is: /var/www/httpdocs/my_sub_folder/peoplepods
    PeoplePods admin tool: http://myurl.com/my_sub_folder/peoplepods/
    PeoplePOds homepage: http://myurl.com/my_sub_folder/
    
  3. Uncompress your PeoplePods tarball into your web folder
          > tar -zxvf peoplepods-0.667.tar.gz
    
  4. This will create a new folder called peoplepods/ inside of which lives all of the PeoplePods code and configuration.
  5. Create a fresh, empty database on your MySQL server. Note the name of the database as well as the username and password.
  6. Before running the install, you will need to set the permissions on several folders. Change the permissions on files/ and lib/etc to 777:
          > chmod -R 777 peoplepods/files
          > chmod 777 peoplepods/lib/etc
    
  7. Visit your new PeoplePods installaton in a browser. Load http://myurl.com/peoplepods
  8. The automatic installation process should take over. Enter details about the site and about the database.
  9. Once the installation has completed, visit the PeoplePods admin tool and turn on some built in functionality by using the Options -> Plugin Pods menu. NOTE: The site will not be functional until you turn on some of the built in pods!
  10. Visit your new PeoplePods powered site!

SDK Documentation

If you are anxious to get hacking, we recommend the SDK Quick Start Guide.

At the core of PeoplePods is an object oriented programming library that provides much of the functionality required for building today's modern social applications. It provides a generic interface to create and manage content, members, and member activities.

If you are not familiar with the basics of object oriented programming, take some time to read up before proceeding. In short, object oriented programming, or OOP, allows you to bundle pieces of data and functionality together into logical units. PeoplePods provides a variety of different objects that represent different kinds of information.

For example, in PeoplePods, each member is represented by a person object. The object contains information about the member, such as the name and email address used to sign up, as well as functions available to that member, such as adding a friend or bookmarking a page. Here is a tiny snippet of code to illustrate this concept:

// get my person object from the main POD object
$member = $POD->currentUser();

// write out some information about this person
echo "My email address is:";
$member->write('email');

// add some content to this person's favorite list
$member->addFavorite($post);

All of the functionality within a PeoplePods application originates from a single PeoplePods object. We recommend developers name their parent object $POD, as this convention is used within many of the templates and sub-functions in the library.

$POD = new PeoplePod();
$content = $POD->getContent();
$person = $POD->getPerson();

Core Concepts

Generic Interfaces One of the main ideas behind PeoplePods is that it should be provide access to all sorts of content using the same set of functions. That is, you can use the same function with the same syntax to load blog posts as you would to load calendar events. Similarly, a generic system has been provided so that new types of relationships between memberships can be defined - friends, enemies, family, etc - that use the same syntax and provide the same access methods. What this means is, you only have to master a few simple functions to gain access to all of the power of PeoplePods.

This generic access is provided by the core objects such as $Stack, as well as the flagging module.

Ad Hoc Data Definition PeoplePods is different from many content management systems in that it does not require you to pre-define your content types or database schema. It uses a generic schema and the powers of it's underlying relational database system to allow you to create new fields on any content type at any time, and to define new content types on the fly. The admin tools will automatically adapt to the new content types you create.

This functionality is provided by the meta field module.

Building New Functionality

Unlike many website building systems available today, PeoplePods was not designed to create a specific type of website - a blog, for example. There are no limits to the type of pages present on the site, and there is no predefined structure inherent to a PeoplePods site. This allows developers to freely define new types of content and areas of functionality by building plugin pods, or by using PeoplePods functionality in other scripts.

Plugin Pods

PeoplePods has a simple plugin structure called "Pods" which allows developers to create reusable modules that define different functions of the site. It is helpful to think of each pod as defining a specific page type.

For example, one pod creates member profiles. Another creates content permalink pages. Yet another creates a personalized dashboard page.

Using the pod plugin system has a variety of advantages, and is the recommended method for creating new functionality within your PeoplePods site. Pods automatically map their functionality to friendly URLs, provide role-based security, and can be toggled on and off within the admin tools.

We highly recommend using one of the core pods as the basis for any new pods you create. Doing this will provide you with a template for all the necessary components.

Read the instructions for creating new pods, or the more specific instructions on create a pod that will create a new content type.

Stand Alone Scripts

If you don't want to play by our rules, you can use PeoplePods in normal PHP scripts. All one must do is include the PeoplePods library into the script:

require_once("/readme/all/podlib/PeoplePods.html");
$POD = new PeoplePod();

After creating the $POD object, all of the power of PeoplePods is available for use in that script. This makes it easy to add PeoplePods functionality to existing scripts - such as creating dynamic and personalized sidebars.

It is important to note that the difference between a stand alone script and a full pod is relatively minor - a pod simply provides extra information on how the script should be integrated into the site, whereas a stand alone script is just a script. This might mean the difference between having a pretty URL like "mysite.com/people/chester" and and ugly one like "/readme/all/mysitecom/scripts/profilescript_username_chester.html" Of course, talented developers can fix this problem using mod_rewrite.

Hack Yourself Crazy

We highly recommend that you explore the code of the SDK library. We have made every effort to make our code as readable and well organized as possible with the hopes that skilled developers will be able to modify and expand the provided functionality as necessary. In many cases, creating custom functionality may be as easy as cutting and pasting a few lines of code, then tweaking a parameter or two.

SDK Quick Start Guide

This page is intended to give developers a quick overview of the basic functionality of PeoplePods. Links to further documentation are scattered throughout - we highly encourage you to explore further to get a good feel for the scope and power of PeoplePods.

Using the techniques below, you can layer PeoplePods functionality onto existing PHP-powered sites, or you can create new plugin pods which function within PeoplePods.

Creating a $POD

To access PeoplePods, you need to create a $POD object. You do this by including the library file, and calling PeoplePod's constructor. In order to do so in a manner compatible with the core pods and default theme, you need to call it like so:

include_once("/readme/all/my_peoplepods_dir/PeoplePods.html");
$POD = new PeoplePod(array('authSecret'=>$_COOKIE['pp_auth']));

You may want to specify that the new feature you are creating can only be accessed by certain people. You can do this using the 'lockdown' parameter:

// only allow logged in people
$POD = new PeoplePod(array(
 'authSecret'=>$_COOKIE['pp_auth'],
  'lockdown'=>'login'
));

// only allow logged in people who have confirmed their email address
$POD = new PeoplePod(array(
  'authSecret'=>$_COOKIE['pp_auth'],
  'lockdown'=>'verified'
));

// only allow logged in people with the adminUser permission
$POD = new PeoplePod(array(
  'authSecret'=>$_COOKIE['pp_auth'],
  'lockdown'=>'adminUser'
));

Once you've got your $POD object, you can access the details about the current logged in user, if one exists, using $POD->isAuthenticated() and $POD->currentUser().

Creating Content

Creating a piece of PeoplePods content is as easy as creating an empty content object to store it using $POD->getContent(), then calling the save() function. At the bare minimum, a piece of content must have a headline and a type:

$new_content = $POD->getContent();
$new_content->headline = 'This is a new post';
$new_content->type = 'post';
$new_content->save();

Part of the magic of PeoplePods is that you can create any field you want, on the fly, and PeoplePods will automatically handle it as if it was a native field in your database. This allows you to create many types of content in many different configurations. We call this creating meta fields. But you don't need to know anything special to access this functionality - it all happens behind the scenes.

$new_content->new_field = 'foo';
echo $new_content->new_field;

PeoplePods automatically tracks a bunch of information about the content, including when it was created and who created it, so you can just worry about stuffing your website with cool content.

Once you've created your content, you can add tags, comments and files using simple object methods:

$content->addComment('my comment goes here');
$content->addTag('foo');
$content->addFile($filename,$_FILES[$filename]);

Combining all of these features, you can create and manage virtually any kind of web content, and can do so without any sort of pre-configuration.

// create a new piece of content of type 'post'
$new_post = $POD->getContent();
$new_post->type='post';
$new_post->headline='my new post';
$new_post->save();

// now create another piece of content of type 'receipt'
// the receipt will use a meta field to track what content was created
$receipt = $POD->getContent();
$receipt->type = 'receipt';
$receipt->headline='Created content';
$receipt->content_created = $new_post->get('id');
$receipt->cost = 500;
$receipt->save();

Finding and Displaying Stuff

PeoplePods provides a query interface to all of the stuff it manages, including your website content, users, groups, comments, files and tags. You can use this interface to generate customized and personalized lists of stuff, then output them into your pages. In this way, you can create blogs, sidebars, tag clouds, lists of attached files, comment streams, and many other configurations.

Each type of "stuff" PeoplePods manages has its own query function, but all of the functions take the same parameters:

$posts = $POD->getContents($conditions,$sort,$count,$offset);
$people = $POD->getPeople($conditions,$sort,$count,$offset);
$files = $POD->getFiles($conditions,$sort,$count,$offset);
$groups = $POD->getGroups($conditions,$sort,$count,$offset);
$tags = $POD->getTags($conditions,$sort,$count,$offset);
$comments = $POD->getComments($conditions,$sort,$count,$offset);

Most of the time, you'll be concerned with the $conditions parameter. This is an array of field=>value pairs that describe the content you want to load. This might be as simple as specifying the type of content or the id of the content's owner, or it might involve a combination of several fields. You can read about stack parameters here.

The return value of these functions is a list of objects, or what we call a stack. You can do all sorts of things with stacks, including iterating over them, searching them, and outputting them to the page.

Each object also has its own output function, which uses a template file located in one of the themes. You can also output individual fields using write() and other related functions.

// get recent posts
$posts = $POD->getContents(array('type'=>'post'));

// get recent posts by a specific author
$posts = $POD->getContents(array('type'=>'post','userId'=>6));

// use foreach to iterate over the results
foreach ($posts as $post) { 
  $post->output();
}

// use while to iterate over the results
while ($post = $posts->getNext()) {
  $post->output();
}

// just output the entire list, with automatically generated headers and footers
$posts->output();

You can query any of the different object types using any field in their object definition as well as any fields you create using the meta fields technique. You can also query fields in related objects, like the author of a post, members of groups, or a comment's parent content. Using this capability, you can create virtually any view of your website that you can imagine.

// get all comments that are attached to content in a specific group
$comments = $POD->getComments(array('d.groupId'=>5));

// get all files created by an admin user
$files = $POD->getFiles(array('u.adminUser'=>1));

Once you have the stuff you want, you can access related stuff without more queries. Each type of object comes with predefined stacks:

$comments = $content->comments();
$author = $content->author();
$files = $content->files();
$content = $comment->parent();
$people = $group->members();

Creating Relationships Between People and Content

You can create relationships between 2 people, or between a person and a piece of content using flags:

// add $content to $user's favorites
$content->addFlag('favorite',$user);

// add $friend as $user's friend
$friend->addFlag('friend',$user);

You can then query the content and people using those flags:

// load my favorites
$favorites = $POD->getContents(array(
  'flag.name'=>'favorite',
   'flag.userId'=>$user->id
));

// load my friends
$friends = $POD->getPeople(array(
  'flag.name'=>'friend',
  'flag.userId'=>$user->id
));

Luckily, PeoplePods provides a bunch of built in flag management for favorites, friends, followers, and comment subscriptions.

Groups

We believe the future of online community revolves around small groups. Groups for clubs, groups for interests, groups for neighborhoods, and group for groups! Thus, we've built basic group handling right into the core of PeoplePods.

// create a group
$new_group = $POD->getGroup();
$new_group->group_name = 'Scoobies';
$new_group->description = 'For vampire hunters';
$new_group->save();

// add a piece of content to a group
$new_group->addContent($post);

// add a user to the group
$new_group->addMember($user);

Read more about groups here.

Stacks

PeoplePods handles lists of objects using a special type of object called a Stack. Stacks give you the ability to query people, content, groups, comments and files, then manipulate the results in various ways.

PeoplePods provides a bunch of pre-defined stacks such as $Person->favorites() and $Content->comments(). You can also create new stacks using the stack constructor functions: $POD->getPeople(), $POD->getContents(), $POD->getComments(), and $POD->getGroups().

All of these functions take a very similar set of parameters:

$people = $POD->getPeople($conditions,$sort,$count,$offset);

$posts = $POD->getContents($conditions,$sort,$count,$offset);

$groups = $POD->getGroups($conditions,$sort,$count,$offset);

$comments = $POD->getComments($conditions,$sort,$count,$offset);

$conditions is an associative array of conditions that the objects must meet to be included in the stack. PeoplePods will attempt to link in related information based on what conditions are passed in. Read about creating these conditions.

$sort is a SQL-style sort statement. You can sort by any of the fields in the object, or by any fields in related objects linked in to the query.

$count is the number of objects you want to return.

$offset is the number of objects the stack should pass over before returning results. This allows you to page your results.

To create a stack of recent content, you might use:

$recent = $POD->getContents(array('type'=>'post'),'date DESC',20,0);

Once you've got your stack set up, you can do all sorts of fun things with it:

// see how many items you have in your stack
$count = $recent->count();

// see how many total items match your conditions
$totalCount = $recent->totalCount();

// sort by any field, including meta fields.
$recent->sortBy('rating');

// see if another 'page' of results exists:
if ($recent->hasNextPage()) {
  // print out next page link
}

// use a while loop to iterate over the items
while ($post = $recent->getNext()) {
  $post->output('short');
}

// reset the contents
$post->reset();

// use a foreach loop to iterate over the items
foreach ($recent as $post) { 
  $post->output('short');
}

// reset again!
$post->reset();

// forget iterating, and just output everything
$recent->output('short');

// extract an array of the values of one specific field
$friend_ids = $person->friends()->extract('id');

Stacks do a ton of behind the scenes work for you to make things as efficient and easy to use as possible. For example, if a stack stumbles upon a piece of content that the current user does not have access to (such as content with friends_only or group_only privacy), it will automatically skip the record and find another to replace it. This frees you from considering privacy settings when loading content, while ensuring that you'll always get the right number of results back.

Stacks use a technique called lazy loading to make sure that the data you need is ready when you need it, but not until then. What this means is, you can set up a stack without actually loading information from the database. The database will only be accessed when the stack data is accessed for the first time.

This allows PeoplePods to always offer the pre-defined stacks like $Person->friends() without causing unnecessary database hits when you aren't using them. They're always available, but will only leap into action when called upon.

This also allows you to define a stack, and never actually access it's data, but to access some of its properties:

// set up a stack containing my followers
$followers = $POD->getPeople(array(
  'flag.name'=>'friend',
  'flag.itemId'=>$POD->currentUser()->get('id')
));

// now, access the totalCount function without 
// actually loading the records from the db
echo $followers->totalCount();

$Stack->sortBy()

$Stack->sortBy($field,$reverse=false);

Resort the contents of the stack by $field. You can also sort by meta fields!

$Stack->totalCount()

Returns the total number of items available to the stack in the database.

$Stack->count()

Returns the number of items currently in the stack.

$Stack->offset()

Returns the stack's current offset value.

$Stack->getPreviousPage()

Reload the stack with the previous set of results, based on the original $count and $offset parameters.

$Stack->getNextPage()

Reload the stack with the next set of results, based on the $count and $offset parameters originally passed in.

$Stack->previousPage()

Returns the offset value of the previous page of results.

$Stack->hasPreviousPage()

Returns true if there are more results in the database than were included in the stack.

You can use this to generate paging links:

// is there a next page?
if ($posts->hasPreviousPage()) { 
  echo "Previous";
}

Or, you can just load the next page:

if ($posts->hasPreviousPage()) {
  $posts->getPreviousPage();
}

$Stack->nextPage()

Returns the offset value of the next page of results.

$Stack->hasNextPage()

Returns true if there are more results in the database than were included in the stack.

You can use this to generate paging links:

$offset = ($_GET['offset']) ? $_GET['offset'] : 0;

// load 5 documents
$posts = $POD->getContents(
  array('type'=>'post'),
  'date DESC',
  5,$offset);

// display all 5 docs.
$posts->output();

// is there a next page?
if ($posts->hasNextPage()) { 
  echo "<a href='?offset=" . $posts->nextPage() . "'>Next</a>";
}

Or, you can just load the next page:

if ($posts->hasNextPage()) {
  $posts->getNextPage();
}

$Stack->peekAhead()

Returns the next document in the list without advancing the list forward. If no next item can be found, returns null.

$Stack->add()

$Stack->add($obj);

Adds $obj to $Stack. If an item with the same id field as $obj is already in the stack, $obj is assumed to already be in the stack and is not added.

It is important to note that simply adding an object to a stack does not modify it's contents in any way. That is, it does not set the object's contents so that it would appear in that stack again, were it recreated.

$Stack->implode()

$list = $stack->implode($delimiter,$field);

Returns a string containing the value of $field from each item in the stack, separated by $delimiter.

$names = $person->friends()->implode(',','nick');
// returns something like
// Ben, Chester, Katie

$Stack->extract()

$values = $stack->extract($field);

Returns an array containing the value of $field for each item in the stack. Handy for generating stack conditions based on other stacks.

$ids = $person->friends()->extract('id');

$Stack->contains()

$obj = $stack->contains($field,$value);

Searches all the objects in the stack and returns the first object where $field = $value. If no object is found, returns null.

This is commonly used to look for image attachements:

if ($img = $content->files()->contains('file_name','img')) { 
// do something with $img
} else {
// no image!
} 

$Stack->fill()

Causes the stack to load its data from the database.

This function is mostly used internally, and should only rarely be used. The only time it is explicitly necessary is when you want to force a stack to reload its contents from the database, such as when you've added an item that should be included.

$Stack->output()

$Stack->output($template_name);

Outputs the contents of the entire stack with special formatting variables made available to the templates. If $template_name is specified, a template of that name from the appropriate theme folder will be used. Otherwise, the default 'output' template is used.

$person->friends()->output('short');

When outputted through a stack, each object in the list gets special formatting variables available in the template which pertain to the item's position in the list:

In templates, you can access these as if they were normal fields:

// in template file
if ($content->get('isFirstItem')) { 
  // do something special for the first item
}

By default, stacks wrap their output in a simple header and footer template, located in the theme folder under the stacks sub-folder. You can override this by passing in a few extra parameters:

// no header or footer
$stack->output('short',null,null);

// use the normal header, 
// but swap in the pagination footer
$stack->output('short','header','pager');

Finally, you can specify a title and an empty message to be displayed in the header and footer templates:

$stack->output('short','header','pager','Search Results','No results!');

$Stack->asArray()

Returns the entire stack as an array of associative arrays. Great for returning json encoded results:

echo json_encode($search_results->asArray());

$Stack->getNext()

Returns the next item in the stack. If no items remain, returns null. Great for using in a while loop!

while ($post = $posts->getNext()) {
// do stuff with $post
}

Flags

Flags are per-user pieces of information that can be added to Person Objects, Content Objects, and Group Objects.

Flags establish links between people, and between people and pieces of content. Favorites, watch lists, and friends are all implementations of flags that are provided by PeoplePods, but you can create your own custom flags too!

Flags might be used to create new relationships between users, such as additional friend lists or block lists.

Flags can also be used to create new relationships to content, such as adding a rating, or reporting something as "offensive."

To learn about adding and querying flags, see $Obj-addFlag(), $Obj-removeFlag(), $Obj-hasFlag(), and $Obj->toggleFlag().

If you want to add a value to a person or piece of content that will be the same for every user, use meta fields.

Meta Fields

PeoplePods allows you to extend data included in the Person Object, Content Object, and the Group Object by adding meta fields.

Meta fields behave, for the most part, the same way normal fields behave. You can get(), set() and write() them as if they were "real" fields.

Meta fields can be added at any time with no prior configuration. You can add different sets of meta fields to each object, or reuse the same fields. However, each object can only have one field of any given name.

If you need to assign values to objects that are different for each user, use flags.

Use meta fields to add profile questions to your $person objects, or to collect extra information about $content objects.

See also: $Obj->addMeta(), $Obj->removeMeta(), and $Obj->getMeta().

Object Definitions

PeoplePods is an object oriented SDK, which means that all of the functionality for each type of information is bundled up into an object. There are a variety of objects than handle different types of data, and offer different functionality.

All of the objects are listed below. It is important to note that many of the functions that are present in each object are actually defined by the parent $Obj object. These generic functions have been included in each object definition, however it is helpful to remember which functions are available to all objects, and which are present only for certain types of object.

File Objects

The file is a pretty simple object with only a few fields. Each file is linked to a person object representing the person who uploaded the file. In addition, the file may be linked to a content object.

Fields

id the unique id of this file
contentId reference to a piece of content
userId reference to the file's uploader
file_name the descriptive name of this file. files uploaded via the edit profile script and default pods name the file 'img' because it is primarily used as an avatar.
original_name the original filename of the file
description a description of the file, or a caption for an image
extension 3 character file extension
mime_type the mime type of the file which is autodetected
changeDate date this file was most recently changed
date date this file was uploaded
original_file url of uploaded original file
resized url of resized image, as defined in the PeoplePods admin tool
thumbnail url of the thumbnail image, as defined in the PeoplePods admin tool
minutes minutes since the file was uploaded
tmp_name temporary name of a file that has just been uploaded. this is found in the $_FILES array.

Relationships

You can access the files of the owner by using the $file->creator() function, which returns a person object.

// access person object member functions
echo "Uploaded by: ";
$file->owner()->permalink();

// output the owner using a special template
$file->owner()->output('avatar');

You can also access the content that the file is attached to, using the handy $file->parent() function.

// access content values
$file->parent()->write('headline');

// is this file by the original poster?
if ($file->get('userId')==$file->parent()->get('userId')) { 
  // do something
}

Displaying Files

You can use the $file->output() function to output a file using its own templates, or you can access individual fields.

Templates for file objects are found in the files/ sub folder of your theme.

// output a file using the files/download.php template
$file->output('download');

// print an image link using the resized image
<img src="<? $file->write('resized'); ?>" />

// print a link to the original file
< a href="<? $file->write('original_file'); ?>" />

You might also want to send the actual contents of a file instead of just making a link to it. To do this, use the $file->download() function.

Image Files

When an image is uploaded, PeoplePods will automatically resize it into 2 sizes: a resized version, and a thumbnail version. The specifics of how the image is resized can be set using the PeoplePods Command Center tool.

You can tell whether or not a file is an image by using the $file->isImage() function.

PeoplePods can also automatically generate new sizes of an image using the $file->src() function:

// generate a version that is 100 pixels wide
<img src="< $img->src(100); ?>" />

// generate a version that is 50 pixels wide and cropped to a square
<img src="< $img->src(50,true); ?>" />

Loading Files

The vast majority of the time, you'll probably be displaying the files that are attached to the piece of content you are viewing, or that were uploaded by a specific person. To do this, simply use the $content->files() and $person->files() functions, which returns a list of the files in chronological order.

You can also load a specific file by it's id using the $POD->getFile() function.

If you need to query the file database on any of the file fields or fields in the related tables, use the $POD->getFiles() function.

// output the files from a piece of content
$content->files()->output();

// load a specific file (for editing, etc)
$file = $POD->getFile(array('id'=>1));

// load all files from a user, 
// regardless of whether or not it was attached to content
$files = $POD->getFiles(array('userId'=>1));

// load all files from a user NOT attached to contnet
$files = $POD->getFiles(array('userId'=>1,'contentId'=>'null'));

// load all files from any piece of content in a specific group
$group_files = $POD->getFiles(array('d.groupId'=>5));

Adding and Removing File

The best way to add a file is to use the $content->addFile() function or the $person->addFile() function, which handles all the nitty gritty details.

To delete files, call $file->delete().

$file->src()

$src = $file->src($max_width,$square=false);

This function will resize the image to $max_width pixels wide and return the URL for the new image. If $square is true, the image will also be cropped into a square.

This function caches the resulting image, so it will only be generated once.

// get a 100 pixel wide image
$src = $image->src(100);

// get a 50 pixel square image
$src = $image->src(50,true);

Note: If the image is smaller than $max_width, no resizing will occur.

$file->download()

// download original file
$file->download();

// download resized image file
$file->download('resized');

// download thumbnail image file
$file->download('thumbnail');

Cause the contents of the file to be sent to the browser, complete with mime-type headers. The file will download with the original uploaded file's name.

$file->isImage()

Returns true if the file is an image file, false if it is any other kind of file.

Image files include jpg, gif and png files.

$Obj

The Obj class is the base class for Person Objects, Content Objects, Group Objects, Comment Objects and File Objects. It provides all the basic functionality like setting values, getting values, and writing values out for display.

Thanks to the magic of object inheritance, all of the objects have access to these functions. We've defined $Obj->write(), so it exists for every type of object!

$person->write('nick');
$content->write('headline');
$group->write('groupname');
$comment->write('comment');
$file->write('thumbnail');

The Obj class also implements the meta field and flagging functionality for people, content and groups. This functionality works the same everywhere:

// add an about_me field to $person
$person->addMeta('about_me','I am awesome');

// add an endDate to $content
$content->addMeta('endDate','2012-12-31');

// add a motto to $group
$group->addMeta('motto','Stay Hoopy');

// flag $person as a friend of the current user
$person->addFlag('friend',$POD->currentUser());

// flag $content as a favorite of the current user
$content->addFlag('favorite',$POD->currentUser());

// flag $group with a warn flag
$content->addFlag('warn',$POD->currentUser());

You should never directly instantiate one of these! They don't do anything on their own. But paired with the subclasses, these puppies do all the heavy lifting. All of the SQL queries responsible for loading things from the database are located in this class. Obj knows how different objects relate to one another and can build the necessary links.

$Obj->creator()

Works exactly the same as $Obj->author(), but looks for a createdBy field instead of a userId field. If no createdBy field is found, userId is used.

This is only useful when you change the userId after content has been created. You might do this in a scenario where you are "assigning" a piece of content to another user.

In most cases, this will be the same as $Obj->author().

$Obj->author()

Returns a person object referencing the object's author.

In the case of a content object, this will be the person referenced by userId - by default, the person who created the content

In the case of a comment object, this will be the person who left the comment.

// write out a link to the author's profile
$content->author()->permalink();

// access author's name
$name = $content->author()->get('nick');

$Obj->parent()

Returns a content object referencing the object's parent.

In the case of a content object, this will return the content referenced by parentId.

In the case of a comment object, this will return the content referenced by contentId.

// access parent content
if ($content->parent()) {
  echo "This is a child of: " . $content->parent()->write('headline');
}

// reference a comment's parent
$alert = $content->author()->get('nick') . ' left a comment on ' . $comment->parent()->get('headline');

$Obj->asArray()

Returns all the fields in the object as an associative array. Handy for creating JSON nuggets!

$array = $content->asArray();
echo json_encode($array);

Some of the objects have overridden this method to protect certain fields, such as the authSecret field in the Person object.

$Obj->error()

Contains the last error message that occurred. Should be used alongside $Obj->success().

$Obj->success()

Returns true if the last operation taken on $Obj was successful. Otherwise, returns false.

$content->save();
if ($content->success()) {
  // do something
} else {
  echo "Error! " . $content->error();
}

$Obj->hasFlag()

$Obj->hasFlag($flag,$person);

Has $person added flag $flag to $obj? Returns true if so, otherwise returns false.

// do not post comment if user is blocked
if ($POD->currentUser()->hasFlag('block',$content->author())) {
  echo "You have been blocked!";
} else {
  $content->addComment($comment);
}

$Obj->toggleFlag()

$Obj->toggleFlag($flag,$person);

Toggles the value of $person's flag $flag on $obj between true and false.

If no value was set, sets $flag to true.

If value was true, sets $flag to false.

$Obj->removeFlag()

$Obj->removeFlag($flag,$person);

Removes $person's flag $flag from $obj.

$Obj->addFlag()

$Obj->addFlag($flag,$person,$value=true);

Causes $person to add a flag named $flag to $Obj, with an optional value of $value. If no value is specified, it defaults to true.

To be clear, $person is the person object who is adding the flag. This is important to remember when adding flags to other person objects. The VAST majority of the time, the second parameter should be $POD->currentUser()

Some examples:


// flag a document as 'awesome'

$content->addFlag('awesome',$POD->currentUser());

// set a rating of 5 on a document
$content->addFlag('rating',$POD->currentUser(),5);

// set a 'block' flag on a person
$person->addFlag('block',$POD->currentUser());

Once a flag has been added, it can be referenced in your stack parameters:


// load all content with the awesome flag
$awesome = $POD->getContents(array(
  'flag.name'=>'awesome'
));

// load all content with a rating of 5
$top_rated = $POD->getContents(array(
  'flag.name'=>'rating',
  'flag.value'=>'5'
));

// load all people with the block flag
$blocked = $POD->getPeople(array(
  'flag.name'=>'block'
));

At this point, you can only refer to one flag at a time in your stack parameters. In some future version of PeoplePods, this may change.

Several flag names are reserved by PeoplePods for use in pre-defined stacks: friend, favorite, watching, and vote. You can use any other flag name to define your own functionality.

$Obj->getMeta()

Returns an associative array of all the meta fields that have been added to an object.

$meta = $content->getMeta();
foreach ($meta as $key=>$value) {
  echo "$key = $value";
}

$Obj->removeMeta()

// $obj->removeMeta($field);
$person->removeMeta('about_me');
$content->removeMeta('endDate');
$group->removeMeta('mott');

Removes the meta field named $field from the object. The field will be removed immediately from the database.

$Obj->addMeta()

// $Obj->addMeta($field,$value);
$person->addMeta('about_me','I live in Austin');
$content->addMeta('endDate','2012-12-31');
$group->addMeta('motto','Stay Classy');

Add a meta field to the object named $field with the value $value. This new field will be saved to the database immediately if the object has already been saved, or upon first save.

Most of the time, this function should not be called directly, as it is automatically called when necessary by the $obj->set() function.

However, to access some specialized functionality, you can call it directly. For example, if you want to strip $value of any HTML, an optional third parameter can be passed:

// value will be stripped of html
$person->addMeta('tagline','I am putting <b>bold tags!</b>',true); 

Meta fields cannot contain blank strings or null values. Setting a meta field to a blank value will result in it being removed.

There is ONE reserved meta field name: adminUser. This field has a special meaning, and thus, you should not mess with it. Seriously!

Once you've added a meta field, you can refer to it in your stack parameters as if it were a native field:

$content->addMeta('transaction_status','active');

// get all content that has a meta field named
// transaction_status that is set to 'active'
$active_transactions = $POD->getContents(array(
   'transaction_status'=>'active'
));

You can also just look for the existence of a meta field:

// get content that has a sidebar field.
$content_with_sidebars = $POD->getContents(array(
  'sidebar:!='=>'null'
));

Read more about Meta Fields.

$Obj->htmlspecialwrite()

// $Obj->htmlspecialwrite($field);
$person->htmlspecialwrite('nick');
$content->htmlspecialwrite('headline');
$group->htmlspecialwrite('groupname');

Writes out the value of $field after it has been run through htmlspecialchars. Especially useful for writing values into form fields!

$Obj->writeFormatted()

// $Obj->writeFormatted($field);
$content->writeFormatted('body');
$group->writeFormatted('description');
$comment->writeFormatted('comment');

Writes out an HTML formatted version of $field.

Currently, this formatting includes:

For example, the following code...

$body = "Hello!

Check out this link:
http://xoxco.com/

Bye!";
$content->set('body',$body);
$content->writeFormatted($body);

...would output the following HTML:

  <p>Hello!</p>
  <p>Check out this link:<br />
      <a href="http://xoxco.com/">http://xoxco.com</a></p>
  <p>Bye!</p>

See also: $Obj->write() and $Obj->htmlspecialwrite().

$Obj->set()

// $Obj->set($field,$value);
$person->set('nick','Chester');
$content->set('headline','Hello World!');
$group->set('groupname','Fish Lovers');
$comment->set('comment','Shut up!');
$file->set('file_name','img');

Set the value of $field to $value.

You may set values for native fields - those that exist in the pre-defined list of fields present in the database schema - or for meta fields which can be created at any time.

// set a real field
$doc->set('headline','This is a test');

// set a meta field
$doc->set('clown_nose','red');

You may specify that a value is NOT saved to the database by passing in an optional third parameter. Otherwise, values will be saved to the database upon calling the save() function.

// set a temporary field on a $person object

if ($person->get('id') == $POD->currentUser()->get('id')) {
  $person->set('isCurrentUser','1',false);
}

As of version 0.7, you no longer have to use the set method for basic content changes. You may now reference the field as if it was a native object attribute:

// set real fields
$content->headline = 'this is my headline';
$person->nick = 'chester';
$group->description = 'a group for cool kids';

// set meta fields
$content->endDate = '2012-12-31';
$person->aboutme = 'this is my bio';

$Obj->write()

// $Obj->write($field);
$person->write('nick');
$content->write('headline');
$group->write('groupname');
$comment->write('comment');
$file->write('thumbnail');

Writes the raw value of $field to the client.

Used primarily in templates for including dynamic values.

$Obj->get()

// $Obj->get($field);
$nick = $person->get('nick');
$headline = $content->get('headline');
$groupname = $group->get('groupname');
$comment_text = $comment->get('comment');
$thumbnail = $file->get('thumbnail');

Returns the raw value of $field as a string.

As of version 0.7, it is no longer necessary to use the get function! You can simply access the named field like a native object attribute:

$headline = $content->headline;
$nick = $person->nick;
$id = $group->id;

Comment Object

The comment object is a pretty simple object with only a few fields. Each comment is linked to a person object representing the author of the comment, and a content object representing the piece of content upon which the comment was left.

Fields

id the unique id of this comment
contentId reference to a piece of content
userId reference to the comment's author
id the unique id of this comment
comment the text of the comment
date timestamp of when the comment was posted
type short string, used to create multiple types of comment - ie review vs comment
permalink url for this comment
minutes minutes since the comment was posted

Relationships

You can access the author of the comment using the $comment->author() function, which returns a person object.

// access person object member functions
echo "Comment by: ";
$comment->author()->permalink();

// output the author using a special template
$comment->author()->output('avatar');

You can also access the content upon which the comment was left, using the handy $comment->parent() function.

// access content values
$comment->parent()->write('headline');

// is this comment by the original poster?
if ($comment->get('userId')==$comment->parent()->get('userId')) { 
  // do something
}

Loading Comments

The vast majority of the time, you'll probably be displaying the comments that are attached to the piece of content you are viewing. To do this, simply use the $content->comments() function, which returns a list of the comments in chronological order.

You can also load a specific comment by it's id using the $POD->getComment() function.

If you need to query the comment database on any of the comment fields or fields in the related tables, use the $POD->getComments() function.

// output the comments from a piece of content
$content->comments()->output();

// load a specific comment (for editing, etc)
$comment = $POD->getComment(array('id'=>1));

// load all comments from a user
$comments = $POD->getComments(array('userId'=>1));

// load all comments from any piece of content in a specific group
$group_comments = $POD->getComments(array('d.groupId'=>5));

Adding and Removing Commments

The best way to add a comment is to use the $content->addComment() function, which handles all the nitty gritty details.

To delete comments, call $comment->delete().

Group Object

HEY! Groups! For people and content.

Content Object

PeoplePods stores all of the content it manages in Content Objects. These are generic storage containers that can be customized to contain any kind of content you desire.

At the bare minimum, a piece of PeoplePods content consists of a headline and a content type. The headline field is a simple text field used as the display title of the content. The type field is also a text field: you can create as many types of content as you want by specifying different values for this field.

Content object's also optional contains fields for body text, an extermal link, an editorial status field, and a privacy information field. These can be used together in any configuration.

But the real power of the content object comes through using the Meta Field functionality, which allows you to append any field you want to any content object. Using this ability, you can customize your content objects to include any and all information that you need to store.

With the meta fields and the dynamic content typing, PeoplePods gives you very flexible access to your content. You should be able to query and display anything you can image with a few lines of code.

Content Objects are stored in the content table in the database.

Content Objects should always be created through the main $POD object using the $POD->getContent() or $POD->getContents() functions.

Fields

id the unique identifier of this content record in the db
userId the unique identifier of the "author" of this record. will in the vast majority of cases be the same as createdBy
headline REQUIRED - title of this content
type REQUIRED - a short string that defines what type of content this is
body the body text of this content
link space to store an arbitrary URL
status Editorial status field. Defaults to 'new' but can be set to 'approved' or 'featured'
createdBy the unique identifier of the person who created this record.
parentId the unique id of another piece of content considered to be the "parent" content, if any.
groupId the unique id of the group this content is a member of, if any.
privacy Describes the privacy setting of this piece of content. Defaults to public, indicating anyone can view this content. Can also be 'friends_only', 'group_only', or 'owner_only'
date date this content was created
changeDate date this content was last modified in any way
editDate date the core values of this content were last upated
commentDate date of the most recently added comment
flagDate date of the most recent change to the status field.
yes_votes number of yes votes that have been registered to this content
no_votes number of no votes that have been registered to this content
yes_percent percentage of total votes that are yes votes
no_votes percentage of total votes that are no votes.
stub URL friendly version of the headline which can also be used as a unique identifier for this post.
permalink URL to post's permalink page

Examples

Create a simple piece of content with just the minimum info:

$content = $POD->getContent();
$content->set('headline','This is a new post!');
$content->set('type','post');
$content->save();
echo "Here is your new post:";
$content->permalink();

Now, create a different kind of content with some extra fields:

$content = $POD->getContent();
$content->set('type','event'); // ad-hoc create a new content type 
$content->set('headline','Chester's Birthday'); // event title
$content->set('body','Chester is having a birthday party!');
$content->save();  // create the record in the db so we can use meta fields.

$content->addMeta('startDate','2009-03-15'); // add a new field
$content->addMeta('endDate','2009-03-15'); // add a new field
$content->addMeta('please_bring','BEER!'); // add a new field

echo "Your new event has been created!  ";
$content->permalink();
echo "Start: " . $content->write('startDate');
echo "End: " . $content->write('endDate');

We can query for content of any type...

$posts = $POD->getContents(array('type'=>'post'));
$events = $POD->getContents(array('type'=>'event'));

Or, you could look for content that matches specific parameters.

// load all the posts the current user created
$my_posts = $POD->getContents(array(
  'type'=>'post',
  'userId'=>$POD->currentUser()->get('id')
));


// load all the events where the start date is today
$today = date("Y-m-d");
$todays_events = $POD->getContents(array(
  'type'=>'event',
  'm.name'=>'startDate',
  'm.value'=>$today
));

Relationships

Each piece of content has a set of predefined relationships to people and other pieces of content within the site. These relationships are represented by cleverly named functions that return other objects or stacks of objects.

And don't forget, every content object inherits all the functions from the $Obj object. These functions include:

$Content->permalink()

Prints a link to the piece of content's permalink page. By default, the text of the link will be the content's headline field, though this can be overridden by passing in a fieldname:

$content->permaink(); // print link with headline
$content->permalink('id'); // print link with id instead of headline

You can also return the permalink as a string by passing in a second parameter:

$permalink = $content->permalink('headline',true);

$Content->unvote()

Clears the vote of the current user.

$Content->vote()

$Content->vote('y');
$Content->vote('n');

Sets the current user's vote on a piece of content. Vote can either be "Y" for yes or "N" for no.

$Content->changeStatus()

$content->changeStatus('featured');

Change the editorial status of a document. This bypasses the normal isEditable() check. Calling this function also updates the flagDate field.

Valid status values are: new, approved, featured, hidden

You can then use the status field to load content of a given status: for example, loading only featured posts:

$featured_posts = $POD->getContents(array(
  'status'=>'featured',
  'type'=>'post'
));

This function is used primarily in the PeoplePods admin tool.

$Content->setGroup()

$content->setGroup(1);

Sets the groupId of the content. This function bypasses the isEditable() check, and instead defers to current user's relationship to the group. If the current user is not the owner of or a manager of the group specified, this function will fail.

This function should only be used in the context of a group manager adding a piece of content to a group, as opposed to a group member adding their own content to a group.

$Content->group()

Returns the Group Object defined by the $content's groupId.

if ($content->group()) { 
  echo "This content is part of:";
  $content->group()->permalink();
}

If you pass in a parameter, will return the value of that field as set in the group.

echo $content->group('groupname');

$Content->tagsAsString()

Returns all the tags assigned to a piece of content as a space-delimited string.

This is mostly useful for displaying input form values, in partnership with $Content->tagsFromString().

<input name="tags" value="<? echo $Content->tagsAsString(); ?>" />

$Content->tagsFromString()

$string = "foo bar baz";
$content->tagsFromString($string);

Replaces all the tags currently assigned to a piece of content with new tags in a string. By default, tags are separated by a space, though this can be overridden by passing in a second delimiter parameter:

$string = "foo,bar,baz";
$content->tagsFromString($strong,",");

$Content->removeTag()

$content->removeTag('foo');

Removes the specified tag from the content.

$Content->addTag()

$content->addTag('foo');

Adds a tag to the content.

You can then query content by that tag:

$tagged = $POD->getContents(array('t.name'=>'foo'));

$Content->hasTag()

$content->hasTag('foo');

Returns true if the tag specified has been added to the content. Otherwise, returns false.

$Content->goToFirstUnreadComment()

Finds the first unread comment, as defined by the current user's watch list.

This function is useful for creating a "new comments" dashboard:

foreach ($POD->currentUser()->watched() as $post) {
  $post->write('headline');
  $post->goToFirstUnreadComment();
  echo "New comments:";
  $post->comments()->output();
}

$Content->markCommentsAsRead()

Marks all the current comments as read for the current user. This is essentially the same as calling $POD->currentUser()->addWatch($content);

$Content->addComment()

Add a new comment to this piece of content.

The new comment will be owned by $POD->currentUser().

$content->addComment('This content sucks!!');

Of note, add comment causes $Content->comments() to reload itself automatically, so the new comment will be present in the stack immediately.

Comments can be assigned an arbitrary "type" field, though custom stack queries will have to be built to utilitize this field...

$content->addComment('This is great!','review');
$content->addComment('What is going on?','question');

(To remove a comment, use $Comment->delete())

$Content->delete()

Deletes the content record, all comments, tags, flags, and files.

Any child documents of the deleted record will have their parent record set to null.

NOTE that this function currently does a hard, permanent delete on this data. In some future version of PeoplePods, this will be changed to do a soft-delete, leaving the data behind, but marking it as inactive.

By default, this function pays attention to the isEditable() function. However, you can override this by passing in a true variable. This should only be done in administrative settings.

$content->delete(true); // override isEditable.

$Content->save()

Saves the content object to the database.

Before saving a new content record, make sure that the headline field and the type field are set. If these fields are not set, the save will fail.

$content = $POD->getContent();
$content->set('headline','This is the title');
$content->set('type','post');
$content->save();

If no userId is specified, the userId field will be set to $POD->currentUser().

By default, the headline, link and type fields are stripped of any HTML tags. The body field, however, is left unmolested. If you would like to filter the body tag of any potentially malicious tags, pass in true as a parameter. This will cause the body field to be stripped of all tags NOT INCLUDING basic formatting tags like p, br, a, i, u, b, strike and img.

$content = $POD->getContent();
$content->set('headline','My body has bad code in it!');
$content->set('type','example');
$content->set('body','');
$content->save(true);

Once a piece of content has been saved, the id, stub and permalink fields will be available, as well as all of the normal relationship functions (children, parent, etc.) Meta and Flag functions are also available after saving.

There are two alternative functions that also save content to the database. These are $Content->changeStatus() and $Content->setGroup(). These functions bypass the isEditable().

$Content->isEditable()

Returns true if this piece of content is editable by the current user. This function takes into account the authentication status of the currentUser, and also looks for the adminUser meta field.

If isEditable() is false, any call to $Content->save() will error.

$Content->output()

Outputs the current content using a template.

By default, this function will use the content/output.php file in the current theme. This can be overridden by passing in a template name:

// output the content using the default template 'output'
$content->output();

// output the person using an alternative template:
$content->output('short');

Within the template, you can access the content's information using the $content variable, and the POD using the $POD variable. So, you can do something like this:

// load some content and display it
$c = $POD->getContent(array('stub'=>'foo'));
$c->output('tiny');

And then, in content/tiny.php in your theme directory:

// inside the content/tiny.php template, we write out fields:
< $content->write('headline'); ?>

Read more about how templates and themes work in PeoplePods.

Person Object

Members of your site are represented within PeoplePods as Person Objects. Person Objects provide functionality to support all the basic actions a member can take like adding and managing friends, adding and managing favorites, and updating profile information.

Person Objects are stored in the users table in the database.

Person Objects should always be created through the main $POD object using the $POD->getPerson() or $POD->getPeople() functions.

Fields

id the unique identifier of this person's record in the db
nick the person's display name.
email the person's email address. this is also used as the username.
authSecret a unique encrypted string that identifies the user. Should never be modified! Use the password field to change the passowrd.
passwordResetCode Semi-random encrypted string. Used to find a person who needs to have their password reset. This should be null unless a password reset has been initiated by the user.
lastVisit Datetime of the last time this person hit the site.
date Datetime of the last modification to this person record.
memberSince Datetime of the member's join date.
verificationKey If this field is null, the person has verified their email. Otherwise, it will contain a semi-random encrypted string. Should not be modified! Use $Person->isVerified() and $Person->verify().
invitedBy user id of the member whose invite was used to join the site.
permalink URL to the peron's onsite profile.
safe_nick Escaped version of the nick field, safe for use in URLS and form elements.
password Set only when you want to change a users password. Note: Setting this variable will cause the authSecret to change, so the pp_auth cookie must be reset to match this new value.
invite_code An invite code that matches a row in the invites table. This should only be specified for new users who have specified an invite code, duh!

Examples:

// write a person's nickname
$person->write('nick');

// change a person's nickname
$person->set('nick','Chester');

// change a person's password
$person->set('password','12345');

// save changes to the db.
$person->save();

Relationships

Each person has a set of predefined relationships to other people and content within the site. These relationships are represented by cleverly named functions that return stacks that can be handled like any other stack.

$Person->friends() - Returns a stack of people who the current person has added as a friend.

$Person->followers() - Returns a stack of people who have marked the current person as a friend.

$Person->favorites() - Returns a stack of content objects that the current person has added as favorite.

$Person->watched() - Returns a stack of content objects that the current person is watching.

$Person->files() - Returns a stack of file objects that the current person has uploaded.

Examples:

// display a list of the person's friends
if ($Person->friends()->count() > 0) {
    $Person->friends()->ouput('short');
}

// display a person's follower count
echo $Person->followers()->totalCount();

// Find a person's profile image
if ($img = $Person->files()->contains('file_name','img')) {
    $img->write('thumbnail');
} else {
    echo "/img/no_icon.png";
}

// Show the first page of a person's favorites
while ($docs = $Person->favorites()) {
    $docs->output('short');
}

Every person object inherits all the code i/o functions from it's parent object. These functions include:

$Person->isFriendsWith()

$boolean = $Person->isFriendsWith($friend);

Returns true if $Person has added $friend as a friend.

$Person->removeFriend()

$Person->removeFriend($crappy_friend);

Removes $crappy_friend from $Person's friend list.

$Person->addFriend()

$Person->addFriend($new_friend,$send_email = true);

Add $new_friend to $Person's friend list. If specified in the PeoplePods library options, an email is sent to $new_friend informing them of the new relationship. This option may be overridden by passing a value to $send_email.

Check $Person->success() to see if the friend was successfully added.

$Person->isWatched()

$isWatched = $Person->isWatched($content);

Returns true if $content is on $Person's watch list. Otherwise, returns false.

$Person->toggleWatch()

$isWatched = $Person->toggleWatch($content);

Toggles the watched status of $content. That is, if $content is already on the watch list, remove it. If the content is not already on the watch list, add it.

Returns true if the content is now a favorite, or false is it is not.

$Person->removeWatch()

$content = $Person->removeWatch($content);

Removes $content from $Person's watch list. Returns the same $content on success or null on error.

$Person->addWatch()

$content = $Person->addWatch($content);

Adds $content to $Person's watch list. Once it has been added, it should be present in $Person->watched() Returns the same $content on success or null on error.

This is essentially a wrapper to $Person->addFlag(), with the addition of a quick query to find the most recently viewed comment and set that as the flag's value.

$Person->toggleFavorite()

$isFavorite = $Person->toggleFavorite($content);

Toggles the favorite status of $content. That is, if $content is already on the favorites list, remove it. If the content is not already on the favorites list, add it.

Returns true if the content is now a favorite, or false is it is not.

$Person->isFavorite()

$isFavorite = $Person->isFavorite($content);

Returns true if $content is on $Person's favorite list. Otherwise, returns false.

Note that this is just a wrapper to $Person->hasFlag().

$Person->removeFavorite()

$Person->removeFavorite($content);

Removes $content from $Person's favorite list. Returns the same $content on success or null on error.

Note that this is just a wrapper for $Person->removeFlag().

$Person->addFavorite()

$Person->addFavorite($content)

Adds $content to $Person's favorite list. Once it has been added, it should be present in $Person->favorites() Returns the same $content on success or null on error.

Note that this is simply a wrapper to $Person->addFlag().

$Person->verify()

$Person->verify($verification_code);

This function is used to verify that a person's email address is correct. Upon joining the site, each person receives an email with a unique verification code. This code can be entered into the site, and using this function, the person becomes verified.

Check $Person->success() to see if the person was successfully verified.

// verify the current user with a code passed in from the web
if ($POD->isAuthenticated()) {
    $Person = $POD->currentUser();
    $code = $_GET['verification_code'];
    $Person->verify($code);
    if ($Person->success()) {
        echo "You are verified!";
    } else {
        echo "Your verification failed!";
        echo $Person->error();
    }
} else {
    echo "Before you verify, you have to login!";
}

$Person->isVerified()

Returns true if the person has verified their email address, otherwise returns false.

$Person->sendPasswordReset()

Sends the password reset email as defined in the emails template sub folder. This should only be sent after a user has requested their password be reset, and the passwordResetCode has been set.

Note, the passwordResetCode is NOT set automatically!

$Person->sendMessage()

$Person->sendMessage($message);

Send a person-to-person message to $Person. $message is the text of the message to be sent. The message is sent by $POD->currentUser().

Learn more about how PeoplePods handles on-site messages.

$Person->welcomeEmail()

Send a welcome email to $Person. This happens automatically when the user is person is created, unless that option has been overridden.

This function uses the "welcome" template in the emails template sub folder. Of note: if the user has a verificationKey set, this template should include a verification link with that key. If the field is blank, no link is necessary.

$Person->sendInvite()

$Person->sendInvite($to,$message,$groupId=null);

Send an email invitation from $Person to the email address in $to. The invitation will include the $message as a message from $Person. If $groupId is specified, the invitation will include an invitation to join that group.

In addition to sending an email, this creates an invite record and invite code that gets stored in the invites table. This invite code can then be specified when creating a new user. This will result in the new user being added automatically to $Person's friend list, and vice-versa. If a $groupId is specified, the new user will be added as a member.

$Person->sendEmail()

$Person->sendEmail($email_template,$vars);

Send an email to $Person using the $email_template template. $vars should contain any PeoplePods objects you want to refer to in the email - you can pass a document, a group, a text message, or an invite code.

By default, the message is sent to $Person. However, passing in a "to" address will override this.

// send a 'share this' email to someone 
$friend = "chester@xoxco.com";
$Person->sendEmail('share_this',array(
  'document'=>$document,
  'to'=>$friend
));

// send a 'new comment' email to $Person
$Person->sendEmail('new_comment',array('document'=>$document));

The email's content and subject are set inside the template file, located in the theme directory under the emails folder.

$Person->recommendFriends()

$recommended = $Person->recommendFriends($minimum_overlap=2,$max_Results=20);

Returns a stack of people that $Person might know, based on the person appearing at least $minimum_overlap times in $Person's current social network.

Default operation is to return anyone who appears two or more times.

If there are no friends to recommend, this will result in an empty stack.

$Person->output()

Outputs the current person using a template.

By default, this function will use the people/output.php file in the current theme. This can be overridden by passing in a template name:

// output the person using the default template 'output'
$person->output();

// output the person using an alternative template:
$person->output('short');

Within the template, you can access the person's information using the $person variable, and the POD using the $POD variable. So, you can do something like this:

$p = $POD->currentUser();
$p->output('tiny');

And then, in people/tiny.php in your theme directory:

// people/tiny.php template
<? $person->write('nick'); ?>

Read more about how templates and themes work in PeoplePods.

PeoplePods Objects

PeoplePods is an object-oriented framework - all one must do to access the entire power of PeoplePods is include the PeoplePods library file into a PHP script and boot up a PeoplePod object.

require_once("/readme/all/peoplepods/PeoplePods.html");
$POD = new PeoplePod($params);

In almost all cases, the constructor will take one or more parameters. These parameters tell PeoplePods about the identity of the current "acting" user and what sort of permission is required to view the content offered by $POD.

authSecret An encrypted string that identifies a single user in the database. Typically, this will be kept in a cookie named 'pp_auth'

If a valid authSecret is passed in, $POD->isAuthenticated() will return true, and $POD->currentUser() will return a Person Object that represents, you may have guessed, the current user.
lockdown Tells PeoplePods who can access the page. The authentication status of the current user, should there be one, will be evaluated against the specified test. If the test fails, the user will be redirected to the appropriate page. Valid values for this parameter are:

login - a valid user was passed into the authSecret parameter.

verified - a valid user was passed into the authSecret parameter, and that user has verified the email address attached to the account.

adminUser
- a valid user was passed into the authSecret parameter, and the adminUser flag has been added to the account.
debug
Tells PeoplePods to turn on debug messaging. Debug messages appear in the normal web error_log. Valid values are:

0 - no debug messages

1 - trace debug messages. functions will announce what they are doing.

2 - sql debug messages. all sql statements that are executed will be logged.

Errors

If an error occurs during the creation of a PeoplePods object, $POD->success() will return false. The last error message can be found by accessing $POD->error(). An error code may also be generated, which can be found by accessing $POD->errorCode().

101 - unable to connect to db

100 - PeoplePods can't find its configuration

These errors represent a catastrophic failure of PeoplePods to start, and the resulting $POD object will be essentially non-functioning.

Examples:

To create an authenticated PeoplePods object, include the following code. Note that if the cookie is not set, the PeoplePod will be unauthenticated, but will otherwise be completely functional. This represent the "logged out" state.

require_once("/readme/all/peoplepods/PeoplePods.html");
$POD = new PeoplePod(array(
 'authSecret'=>$_COOKIE['pp_auth']
));

To create a page that requires a user to be logged in, include the following code. Note that if the cookie is not set, the page will halt execution and redirect to the default PeoplePods login page.

require_once("/readme/all/peoplepods/PeoplePods.html");
$POD = new PeoplePod(array(
 'authSecret'=>$_COOKIE['pp_auth'],
 'lockdown'=>'login'
));

$POD->getFile()

Returns one specific File Object. This function can be used to load existing content from the database, or create a new piece of content.

Loading Files

To load an existing file, pass in it's database id:

$file = $POD->getFile(array(
  'id'=>12
));

Creating Files

To create files, use the $content->addFile() and $person->addFile() functions.

Errors

Be sure to check for errors! In some instances, the content object may not be created properly, and will throw an error.

if (!$file->success()) {
  echo $file->error();
}

$POD->getFiles()

$POD->getFiles($conditions,$sort,$count,$offset);

Get a stack of file objects that match the parameters you pass in.

Parameters

$conditions An associative array of stack parameters that describe the files you want to load. See the stack parameters document for constructing these arrays.
$sort A SQL style sort statement. Defaults to 'date DESC'
$count
Maximum number of pieces of content to return. Defaults to 100
$offset
Offset results by this many files. (for use in paging)

Examples

Get a simple list of the most recent files.

$most_recent = $POD->getFiles();

Get a simple list of the most recent files by a specific person.

$most_recent = $POD->getFiles(array(
  'userId'=>$person->get('id')
));

Get a simple list of the most recent files on a piece of content:

$most_recent = $POD->getFiles(array(
  'contentId'=>$content->get('id')
));

The above example is essentially the same thing as using the $content->files() function.

Get files from a group.

$group_files = $POD->getFiles(array(
	'd.groupId'=>$group->get('id')
));

Be sure to check out the stack documentation for all the functionality the resulting stack will have!

$POD->templateDir()

$POD->templateDir();

Prints out the root URL of the current theme, as set in the PeoplePods admin tool. Passing a false in will cause the function to return the URL instead of echoing it out.

$templateDir = $POD->templateDir(false);

This is mostly useful for creating relative links to images or stylesheets included with the theme.


$POD->currentTheme()

$theme = $POD->currentTheme();

Returns the name of the current theme.

$POD->podRoot()

$POD->podRoot($display=true);

Prints out the URL to the PeoplePods installatio, as set in the PeoplePods admin tool. Passing a false in will cause the function to return the URl instead of echoing it.

This function is mostly used internally by the admin tools.

$podRoot = $POD->podRoot(false);

$POD->siteRoot()

$POD->siteRoot($display=true);

Prints out the root URL of the site, as set in the PeoplePods admin tool. Passing a false in will cause the function to return the URL instead of echoing it out.

$siteRoot = $POD->siteRoot(false);

$POD->siteName()

$POD->siteName($display=true);

Prints out the name of the site, as set in the PeoplePods admin tool. Passing a false in will cause the function to return the name instead of echoing it out.

$siteName = $POD->siteName(false);

$POD->output()

$POD->output($template);

Outputs a template from the current theme. This is mostly used for creating reusable sidebars or modules.

For example, if you placed a file called ad_unit.php in the sidebars/ folder of your theme, you could then include it into your other templates with the following code:

$POD->output('sidebars/ad_unit');

Code inside of the ad_unit template will have access to the current PeoplePods environment, which means they can include content, people or any other kind of PeoplePods functionality.

$POD->footer()

Prints the footer template of the current theme.

$POD->header()

$POD->header($page_title,$rss_link);

Prints the header template of the current theme.

$POD->getComments()

$POD->getComments($conditions,$sort,$count,$offset);

Get a stack of comment objects that match the parameters you pass in.

Parameters

$conditions An associative array of stack parameters that describe the comments you want to load. See the stack parameters document for constructing these arrays.
$sort A SQL style sort statement. Defaults to 'date DESC'
$count
Maximum number of pieces of content to return. Defaults to 100
$offset
Offset results by this many comments. (for use in paging)

Examples

Get a simple list of the most recent comments.

$most_recent = $POD->getComments();

Get a simple list of the most recent comments by a specific person.

$most_recent = $POD->getComments(array(
  'userId'=>$person->get('id')
));

Get a simple list of the most recent comments on a piece of content:

$most_recent = $POD->getComments(array(
  'contentId'=>$content->get('id')
));

The above example is essentially the same thing as using the $content->comments() function.

Get a list of comments from all users with a meta field called 'frontpage' set to '1':

$front_comments = $POD->getComments(array(
	'u.frontpage'=>'1'
));

Get comments from featured posts.

$featured_comments = $POD->getComments(array(
	'd.status'=>'featured'
));

Be sure to check out the stack documentation for all the functionality the resulting stack will have!

$POD->getComment()

Returns one specific Comment Object. This function can be used to load an existing comment from the database, or create a new comment.

Loading a Comment

To load an existing piece comment, pass in the comment's database id

$id = 5;
$comment = $POD->getComment(array(
  'id'=>$id
));

Creating a Comment

To create comment, you can either load an empty content object and set values for its fields, or pass in default values to the constructor.

HOWEVER, the much more useful way of doing this is to use the $content->addComment() function, which handles almost everything automagically.

Create a brand new, empty comment object:

$new_comment = $POD->getComment();
$new_comment->set('comment','This comment sucks!');
$new_content->set('userId',$POD->currentUser()->get('id'));
$new_comment->set('contentId',$content->get('id'));
$new_comment->save();

Or, pass in values:

$new_comment = $POD->getComment(array(
  'comment' => 'This is the default headline',
  'userId'=>$POD->currentUser()->get('id'),
  'contentId'=>$content->get('id')
));
$new_comment->save();

Errors

Be sure to check for errors! In some instances, the comment object may not be created properly, and will throw an error.

if (!$new_comment->success()) {
  echo $new_comment->error();
}

$POD->getGroups()

$POD->getGroups($conditions,$sort,$count,$offset);

Get a stack of group objects that match the parameters you pass in.

Parameters

$conditions An associative array of stack parameters that describe the content you want to load. See the stack parameters document for constructing these arrays.
$sort A SQL style sort statement. Defaults to 'date DESC'
$count
Maximum number of pieces of content to return. Defaults to 20
$offset
Offset results by this many groups. (for use in paging)

Examples

Get a simple list of the most recent groups of any type.

$groups = $POD->getGroups();

The getGroups function can automatically link in information about group membership, so you can do things like get all the groups a user is a member of:

$person = $POD->currentUser();
$my_groups = $POD->getGroups(array(
  'mem.userId'=>$person->get('id')
));

Or, get all the groups a person has been invited to, but has not yet joined:

$person = $POD->currentUser();
$my_groups = $POD->getGroups(array(
  'mem.userId'=>$person->get('id'),
  'mem.type'=>'invitee'  // you might also use 'member' 'manager' or 'owner'
));

You can also query groups by flags and meta fields, in the same manner that you would content or people.

Be sure to check out the stack documentation for all the functionality the resulting stack will have!

$POD->getGroup()

Returns one specific Group Object. This function can be used to load an existing group from the database, or create a new group.

Loading a Group

To load an existing piece group, pass in ONE of the following parameters:

The vast majority of the time, you will load specific groups by their stubs. For example, the following code will load the group with the stub name 'awesomeville'

$content = $POD->getContent(array(
  'stub'=>'awesomeville'
));

Creating Groups

To create a group, you can either load an empty group object and set values for its fields, or pass in default values to the constructor. Surprising, I know.

Create a brand new, empty group object:

$new_group = $POD->getGroup();
$new_group->set('groupname','Music Learning Club Austin');
$new_group->set('description','A club where Austin people learn music.');
$new_group->save();

Or, pass in values:

$new_group = $POD->getContent(array(
  'group_name' => 'Ebola Research Group',
  'description' => 'Blood Everywhere!!!!!'
));
$new_group->save();

Errors

Be sure to check for errors! In some instances, the content object may not be created properly, and will throw an error.

if (!$new_group->success()) {
  echo $new_content->error();
}

$POD->getContents()

$POD->getContents($conditions,$sort,$count,$offset);

Get a stack of content objects that match the parameters you pass in.

Parameters

$conditions An associative array of stack parameters that describe the content you want to load. See the stack parameters document for constructing these arrays.
$sort A SQL style sort statement. Defaults to 'date DESC'
$count
Maximum number of pieces of content to return. Defaults to 20
$offset
Offset results by this many people. (for use in paging)

Examples

Get a simple list of the most recent content of any type.

$most_recent = $POD->getContents();

Get a simple list of the most recent content of a specific type.

$most_recent_posts = $POD->getContents(array(
  'type'=>'post'
));

Get a list of content that have a certain specific meta field:

$content = $POD->getContents(array(
  'm.name'=>'special'
));

Get a list of content who have a specific value for a specific meta field:

$people = $POD->getContents(array(
  'm.name'=>'special',
  'm.value'=>'featured'
));

Get a list of content with a specific flag - this example will return any content flagged by any other user with the "warn" flag:

$content = $POD->getContents(array(
  'flag.name'=> 'warn',
));

Get a list of content with a specific flag/value set - this example will return any content flagged by any other user with the rating flag set to 5:

$content = $POD->getContents(array(
  'flag.name'=> 'rating',
  'flag.value'=> '5'
));

Get a list of content with a specific flag set by a specific user. This is how you would pull a list of a person's favorites:

$person = $POD->currentUser();
$favorites = $POD->getContents(array(
  'flag.name'=>'favorite',
  'flag.userId'=>$person->get('id');
));

Get a list of content created by a specific user:

$person = $POD->currentUser();
$posts = $POD->getContents(array(
  'userId' => $person->get('id')
));

Get a list of content created by anyone in a list of people - for example, a person's friends:

$person = $POD->currentUser();
$posts = $POD->getContents(array(
  'userId' => $person->friends()->extract('id')
));

Get a list of content a person is watching, and sort it by most recent comment activity - this would essentially createa a "new comments" list:

$person = $POD->currentUser();
$posts = $POD->getContents(array(
  'flag.name'=>'watch',
  'flag.userId'=>$person->get('id')
),'commentDate DESC');

Be sure to check out the stack documentation for all the functionality the resulting stack will have!

$POD->getContent()

Returns one specific Content Object. This function can be used to load existing content from the database, or create a new piece of content.

Loading Content

To load an existing piece of content, pass in ONE of the following parameters:

The vast majority of the time, you will load specific pieces of content by their stubs. For example, the following code will load the content with the stub name 'about'

$content = $POD->getContent(array(
  'stub'=>'about'
));

Creating Content

To create content, you can either load an empty content object and set values for its fields, or pass in default values to the constructor.

Create a brand new, empty content object:

$new_content = $POD->getContent();
$new_content->set('headline','This is a new piece of content!');
$new_content->set('type','post');
$new_content->save();

Or, pass in values:

$new_content = $POD->getContent(array(
  'headline' => 'This is the default headline',
  'type' => 'post'
));
$new_content->save();

Errors

Be sure to check for errors! In some instances, the content object may not be created properly, and will throw an error.

if (!$new_content->success()) {
  echo $new_content->error();
}

$POD->changeActor()

$newCurrent = $POD->changeActor($params)

Takes the same parameters as $POD->getPerson(), except instead of just returning a person object, also sets the $POD's currentUser and isAuthenticated status.

This can be used to switch primary users mid-execution, for example in the event that you create a new user who should then take over execution.

Note: If the user fails to load, isAuthenticated will be false and currentUser will be null.

$POD->getPeople()

$people = $POD->getPeople($conditions,$sort,$count,$offset);

Get a stack of person objects that match the parameters you pass in.

Parameters

$conditions An associative array of stack parameters that describe the people you want to load. See the stack parameters document for constructing these arrays.
$sort A SQL style sort statement. Defaults to 'lastVisit DESC'
$count
Maximum number of people to return. Defaults to 20
$offset
Offset results by this many people. (for use in paging)

Examples

Get a simple list of the people who have logged in most recently:

$most_recent = $POD->getPeople();

Get a list of people who have a certain specific meta field:

$people = $POD->getPeople(array(
  'm.name'=>'special'
));

Get a list of people who have a specific value for a specific meta field:

$people = $POD->getPeople(array(
  'm.name'=>'special',
  'm.value'=>'featured'
));

Get a list of people with a specific flag - this example will return any person flagged by any other user with the "warn" flag:

$people = $POD->getPeople(array(
  'flag.name'=> 'warn',
));

Get a list of people with a specific flag/value set - this example will return any person flagged by any other user with the rating flag set to 5:

$people = $POD->getPeople(array(
  'flag.name'=> 'rating',
  'flag.value'=> '5'
));

Get a list of people with a specific flag set by a specific user. This is how you would pull a list of a person's friends:

$person = $POD->currentUser();
$friends = $POD->getPeople(array(
  'flag.name'=>'friend',
  'flag.userId'=>$person->get('id');
));

Get a list of people who flagged a user with a specific flag. This is how you would pull a list of a person's followers (people who have added the friend flag):

$person = $POD->currentUser();
$friends = $POD->getPeople(array(
  'flag.name'=>'friend',
  'flag.itemId'=>$person->get('id');
));

Get a list of people who flagged a specific piece of content with a specific flag. This is how you would pulla list of all the people who have favorited a specific piece of content:

$favorite_users = $POD->getPeople(array(
  'flag.name'=>'favorite',
  'flag.itemId'=>$content->get('id')
));

Be sure to check out the stack documentation for all the functionality the resulting stack will have!

$POD->getPerson()

Returns a Person Object. This function can be used to load an existing person from the database, or to create a new person object.

Loading A Person

To load an existing person, pass in ONE of the following parameters:

For example, the following code will load user id 1:

$person = $POD->getPerson(array(
  'id'=>1
 ));

This will load the user who registered with the name 'Chester':

$person = $POD->getPerson(array(
  'nick'=>'chester'
 ));

Creating a Person

You can create a new person object either by passing 0 parameters to this function, OR by passing a nick, email and password.

Create a brand new, empty user:

$new_user = $POD->getPerson();
$new_user->set('nick','Chester');
$new_user->set('email','chester@xoxco.com');
$new_user->set('password','foobar');
$new_user->save();

Create a new user by passing in all the deets:

$new_user = $POD->getPerson(array(
  'nick'=>'Chester',
  'email'=>'chester@xoxco.com',
  'password'=>'foobar'
 );
$new_user->save();

Errors

Be sure to check for errors! In some instances, the person object may not be created properly, and will throw an error.

if (!$new_user->success()) {
  echo $new_user->error();
}

$POD->currentUser()

Returns a Person Object if $POD is authenticated. Otherwise returns null.

NOTE: Be sure to check $POD->isAuthenticated() or set the lockdown parameter on your $POD before using $POD->currentUser(). If there is no current user to access, an error will occur!

Examples:

Display the current user's name, or "Stranger" for someone not logged in.

if ($POD->isAuthenticated()) {
    $POD->currentUser()->write('nick');
} else {
    echo "Stranger";
}