All Readmes from PeoplePods.net

$OBJ::addIgnoreFields()

2011-04-18T12:29:52-07:00

addIgnoreFields is a class method that teaches PeoplePods how to handle fields that you do not want stored in the database - either as real fields, or as meta fields.

This is very useful when one of your custom methods will regularly add temporary fields to the object, for use in templates or otherwise.

This method should be called from within a methods.php file in a plugin pod. The method is called on the class itself, much like the registerMethod() function.

This function takes an array of fieldnames.

Content::addIgnoreFields(array('temp','counter','fake'));

$Obj::addDatabaseFields()

2011-04-18T12:26:44-07:00

addDatabaseFields is a class method that teaches PeoplePods how to handle database fields that you've added to the schema (most likely via an install function).

This method should be called from within a methods.php file in a plugin pod. The method is called on the class itself, much like the registerMethod() function.

This function takes an array of fieldnames. If a field requires extra attention when going in and out of the database, you may also specify select and insert helpers.

// simply define 2 new fields called "foo" and "bar" in the content object
Content::addDatabaseFields(array('foo','bar'));

// define an additional field on the person object
Person::addDatabaseFields(array('phone_number'));

// add a field that requires processing on select and insert
Content::addDatabaseFields(array(
	'zipcode'=>array(
		'select'=>'zipcodeSelectHelper',
		'insert'=>'zipcodeInsertHelper'
	)
));

Creating Permalink Patterns

2011-04-15T02:18:20-07:00

There are two methods available for specifying a custom permalink format for your content. Both methods involve passing options to the $POD->registerPOD() method.

The first allows for a simple root path to be defined, to which the content's stub is appended.

Using this method, you can create permalinks like:

mysite.com/posts/my-post
mysite.com/pictures/my-picture

The second allows you to define a token replacement pattern which allows you to reference fields from the content, the content's author, and the content's parent to build complex urls.

Using this method, you can create permalinks like:

mysite.com/categories/cars/my-hotrod
mysite.com/people/chester/posts/my-post

Simple Permalinks

To create simple permalinks, where all content will have the same root url, you have to define the document path - the root url at which content will be viewed, and the document edit path - the root url at which content will be created and edited. PeoplePods will use these values, in combination with the content's stub, to generate the permalink and editlink values. These variables are called "TYPE_document_path" and "TYPE_document_editpath."

Given a content type called "posts," you would create 2 variables called "post_document_path" and "post_document_editpath." The values of these variables should match the URLS you set up for the pod's view and edit handlers.

$POD->registerPOD(
  'my_post_type',
  'a custom pod that sets up the "post" content type',
  // set up url rewrite rules
  array(
    '^posts/(.*)'=>'my_custom_pod/post_handler.php?stub=$1',
    '^edit/(.*)'=>'my_custom_pod/edit_handler.php?id=$1',
  ),
  // set up simple permalinks
  array(
    'post_document_path'=>'posts',
    'post_document_editpath'=>'edit',
  ),
);

// in any peoplepods script:
// create new content
$doc = $POD->getContent();

$doc->type = 'post';
$doc->headline = 'Test Post';
$doc->save();

echo $doc->permalink;
// $doc->permalink will be:
// http://mydomain.com/posts/test-post
// $doc->editlink will be:
// http://mydomain.com/edit/test-post

Permalink Patterns

Permalink patterns allow you to use values from the content item's parent object and author object in the permalink.

The permalink pattern system uses tokens similar to the activity stream system, translating a string with special codes into the final dynamic permalink.

To create a permalink that references the parent object, such as a category, you'd use a pattern like:

$permalink = "categories/{parent.stub}/posts/{this.stub}";

To create a permalink that references the object's author, you'd use a pattern like:

$permalink = "people/{author.stub}/posts/{this.stub}";

In each example, the dynamic elements of the permalink are defined by a set of curly brackets {}, a reference to the object (parent or author) and the name of a field (stub). You may use any field from the objects in these patterns:

$permalink = "people/{author.id}/{this.stub}";
$permalink = "categories/{parent.stub}/view?id={this.id}";
$permalink = "myscript.php?stub={this.stub}&headline={this.headline}";

In addition to the permalink, you may also specify an editlink - the url to edit the content, and an editpath - the url to create another piece of content of the same type as the current content object. These options use the same patterns as the permalink.

Like the simple permalinks, these patterns are passed into the registerPOD call in your settings.php file using variable names that include the content type. Given a content type called "posts," you would create 3 variables called "content_permalink_posts" and "content_editlink_posts" and "content_editpath_posts" The values of these variables should match the URLS you set up for the pod's view and edit handlers.

$POD->registerPOD(
  'my_post_type',
  'a custom pod that sets up the "post" content type',
  // set up url rewrite rules
  array(
    '^people/(.*)/posts/(.*)'=>'my_custom_pod/post_handler.php?stub=$1',
    '^edit/new'=>'my_custom_pod/edit_handler.php',
    '^edit/(.*)'=>'my_custom_pod/edit_handler.php?id=$1',
  ),
  // set up simple permalinks
  array(
    'content_permalink_posts'=>'people/{author.stub}/posts/{this.stub}',
    'content_editpath_posts'=>'edit/new'
    'content_editlink_posts'=>'edit/{this.id}',
  ),
);

Download Themes

2010-12-14T03:11:29-08:00

Add flare to your site with one of these member-contributed themes!

PeoplePods ships with a default theme, but developers can create new themes to redefine how PeoplePods looks and acts. Check out the themes linked below.

MediaBugs - The MediaBugs package contains not only a custom theme, but a host of additional pods that turns PeoplePods into a bug tracker! Created and maintained by MediaBugs.org.

Themes by @mrahfa:

PeopleBook - A theme inspired by Facebook.

KokoHitam - Inspired by Modularity Lite Wordpress Theme.

BiruMuda - It's light blue!

Have you built a theme? Add a link to it in the comments below!

Overriding Functions

2010-11-24T09:36:09-08:00

Certain functions within the PeoplePods core libraries can be overridden using theplugin registerMethod method. The functions that can be overridden are those that are frequently called from within other built in methods, such as methods dealing with the cache, templating system, email delivery, and generation of permalinks.

To override a function, create a new function which matches the original functions parameter list, and then call registerMethod. The new function will then be called in place of the built in function.

function personCustomPermalink($person,$field) {
    $person->permalink =  'http://myothersite.com/profiles/' . $person->stub;
}
Person::registerMethod('personCustomPermalink','generatePermalink');

The full list of override-able functions is below.

$person->permalink

$person->render$person->output

$person->sendEmail

$person->sendInvite

$person->sendMessage

$person->generatePermalink

$POD->cachestatus

$POD->cacheflush

$POD->cachew

$POD->cacher

$POD->cachefact

$POD->factcache

$POD->cacheclea

r$POD->cachestore

$POD->checkcache

$POD->cachehasexpired

$POD->loadCache

$POD->writeCache

$activity->formatActivity

$activity->render

$activity->output

$activity->publish

$comment->generatePermalink

$comment->output

$comment->render

$content->isEditable

$content->isViewable

$content->permalink

$content->generatePermalink

$content->render

$content->output

$file->generatePermalink

$file->cleanup$file->download

$file->src

$file->imageSize

$file->resizeImage

$file->createThumbs

$file->output

$file->render

$file->mime_content_type

$group->permalink

$group->output

$group->render

$group->generatePermalink

$message->output$message->render

$stack->output

$tag->output

$tag->render

Private Messaging

2010-11-23T02:25:13-08:00

// send a message to $user from $POD->currentUser()
$user->sendMessage($message);

// return a Stack of "thread" objects sorted by most recent activity on the thread.
// this returns the inbox for the currentUser.
$inbox = $POD->getInbox($count,$offset);

// get # of unread messages in all threads
$total_unread = $inbox->unreadCount():

// get the most recent thread
$thread = $inbox->getNext();

// get # of unread messages in a thread
$unread = $thread->unreadCount();

// who am I talking to?
$user = $thread->recipient();

// output a thread
$thread->output();

// mark all messges in the thread as read
$thread->markAsRead();

// reply to a thread
$thread->reply($message);

// delete all messages from a thread
$thread->clear();


// get messages out of a thread
// messages come out in cronological order!
$messages = $thread->messages();

// get first message
$message = $messages->getNext();

// message from returns a user object
$from = $message->from();

// message to return s a user object
$to = $message->to();

//output a message
$message->output();

$Group->files()

2010-11-23T01:39:36-08:00

Returns a stack of files that have been uploaded and associated with $Group.

Files of any type can be attached to Groups. Images are automatically resized to several sizes, as defined in the PeoplePods admin tool.

You can pull this file out of the stack by using the ->contains() function:

if ($img = $Group->files()->contains('file_name','img')) {
  $img->write('thumbnail');
} else {
  echo "No image";
}

$Person->comments()

2010-11-23T01:37:02-08:00

Returns a stack of comments that have been uploaded and associated with that $Person.

For example, the following code displays the first page of comments:

foreach($Person->comments() as $comment) { 
  $comment->output();
}

To add a new comment to a piece of content, use the $Person->addComment() function.

$Person->addComment()

2010-11-23T01:33:18-08:00

Add a new comment to this piece of content.

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

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

Of note, add comment causes $Person->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...

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

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

$Group->addFile()

2010-11-23T01:27:53-08:00

$Group->addFile('img',$_FILES['img'],'optional caption goes here');

Takes an uploaded file and attaches it to the group object. This function is designed to handle rows out of the $_FILES array which PHP automatically provides when a file has been uploaded via an HTTP POST.

// store all files that were uploaded
foreach ($_FILES as $file_name => $file) { 
	$Group->addFile($file_name,$file);
	if (!$Group->success()) { 
	  echo $Group->error();
	}
}

Image files will be automatically resized upon upload.

Sending and Receiving Alerts

2010-11-23T01:20:26-08:00

Alerts are automated messages sent to members by the system when certain events occur on the site, such as when a member adds another member as a friend, or when a comment is posted on a member's profile or content. An alert is sent to and displayed for one specific member of the site, unlike an activity stream message, which may appear to all members of the site.

Alerts share much in common with the activity stream and the private member-to-member messages. They may have content or people attached to them, and they can be marked read or unread.

Alerts may optionally be sent as email messages to the recipient.

Send an Alert

// send an alert to a user
$user->sendAlert(
	$message,
	$actingUser=null,
	$targetContent=null,
	$ok_to_send_email=true
);

The sendAlert method in its simplest form can be called with one parameter - a message to be displayed to $user.

$user->sendAlert('You are so cool.');

In the event that the alert is being sent in response to another user's action, such as when a user leaves a comment on another user's profile, include the second parameter, which should be the Person record of the user who has performed the action about which the alert is being sent.

$friend->addFriend($user);
$user->sendAlert('{actor.nick} added you as a friend',$friend);

In the event that the alert pertains to one specific piece of content (or comment or group), you may include that piece of content as an attachment:

$content->addComment($comment);
$content->author()->sendAlert(
	'{actor.nick} left a comment on {targetContent.headline}',
	$POD->currentUser(),
	$content
);

You may override the system-wide setting for sending alerts as email messages by passing in the final parameter. This setting can be controlled in the PeoplePods Command Center on the Options -> Notifications menu.

// do NOT send this alert as an email
$user->sendAlert($alert,$user,$content,false);

Attaching Data

If we attach data to an alert when we publish it, we can reference values from the objects within the message using simple tokens - this allows the messages to stay correct, even as the data changes.

There are two types of token available - one that simply inserts a value, and one that inserts a value that is also a link to the object's permalink page.

To insert a simple value, use a token in the form of: @object.field.

To insert a link, use a token in the form of {object.field}

To reference the recipient of the alert, use the targetUser token:

$user->sendAlert('Hey @targetUser.nick!  You are receiving this alert');

To reference the member whose action caused the alert to be triggered, use the actor token:

$user->sendAlert('{actor.nick} is now following you',$actor);

To reference the attached piece of content, use the targetContent token:

$user->sendAlert(
	'{actor.nick} left a comment on {targetContent.headline}',
	$actor,
	$targetContent
);

Getting Unread Alerts

To get a list of a member's unread alerts, use the $Person->getAlerts() method. This will return a stack of alert objects.

// get at most 5 unread alerts
$alerts = $user->getAlerts(5);

// output all alerts using the theme/alerts/output.php template.
$alerts->output();

Marking Alerts as Read

There are two methods for marking alerts as read. You may mark individual alerts as read by calling the $alert->markAsRead() method, or you may mark all alerts pertaining to a specific person or piece of content by calling the $person->expireAlertsAbout($obj) method.

// mark each alert as read individually
$alerts = $user->getAlerts();
foreach($alerts as $alert) {
	$alert->markAsRead();
}

// mark alerts about $content as read
$user->expireAlertsAbout($content);

// mark alerts about $person as read
$user->expireAlertsAbout($person);

Use $alert->markAsRead() when a user manually dismisses an alert. Use $person->expireAlertsAbout() when a user visits the permalink page for an object so that any related alerts will automatically be marked as read once the user visits the object's page.

Displaying Activity Streams

Alerts are output via the output() method, either on the alert list itself, or on an individual alert message. Each message is output using a template from the alerts/ folder. By default, alerts/output.php will be used.

// output the entire stream
$alerts = $user->getAlerts();
$alerts->output();

// output one message at a time
foreach ($alerts as $alert) { 
	$alert->output();
}

// output the stream using mytheme/alerts/custom.php
$alerts->output('custom');

Inside the template, you not only have access to the alert message, but also to all of the attached data. You can use the attached data to display thumbnail images, do additional processing, or whatever the heck you want.

To display the formatted alert message, use the formatMessage() method. This method will choose the appropriate message to display and do all of the token replacement:

<? echo $alert->formatMessage(); ?>

You can also access the attached data using the following variables:

// reference the alert itself
$message = $alert->formatMessage();
$minutes_since = $alert->minutes;

// reference the acting user
$actor = $alert->author();
$actor->permalink();

// reference the target user
$targetUser->permalink();

// reference the target content
// this could be EITHER a piece of content
// or a comment
// check the TYPE field.
if ($targetContent->TYPE=='content')  {
	// do something with content
} else if ($targetContent->TYPE=='comment') { 
	// do something with a comment
}

Function Reference

// query the alert inbox
$alerts = $person->getAlerts($count);

// output a list of alerts:
$alerts->output($template,$header,$footer,$empty_message);

// output individual alerts:
foreach ($alerts as $alert) { 
	$alert->output($template,$alternative_path_to_template);
}

// format an alert for display:
$message = $alert->formatActivity();

// send an alert
$user->sendAlert(
	$message,
	$actor,
	$targetContent,
	$ok_to_send_email
);

// load a single alert by ID
$alert = $POD->getAlert(5);

// query all alerts
$alerts = $POD->getAlerts(
	$conditions,
	$sort,
	$count,
	$offset
);

$POD->libOptions()

2010-10-07T03:25:13-07:00

$val = $POD->libOptions($key);

Returns the value of one of the PeoplePods library options. These options are defined within the command center, by the library itself, and by plugin pods.

Most of the options are stored into the lib/etc/options.php file within your PeoplePods install. (Some may be defined at runtime by the $POD->registerPOD() function, though these should function in the same manner.)

Add functionality to PeoplePods with registerMethod

2010-10-06T02:39:35-07:00

As of 0.8, plugin pods can add functionality to core classes using the registerMethod() class method. This allows PeoplePods to be extended without changing the library code, and thus allows the system to be upgraded without overwriting custom additions.

The registerMethod() function should only be used within a methods.php plugin file, as described here. Using it outside of the methods file will cause your entire website to explode.

In addition, registerMethod() is a class method, which means it is called directly on a class, not on a specific object. This way, the method is available to all objects of that class.

function myMethod($POD) {
// do stuff.
}

PeoplePod::registerMethod('myMethod');

function myPersonMethod($person) {
// do stuff.
}

Person::registerMethod('myPersonMethod');

function myContentMethod($content) {
// do stuff.
}

Content::registerMethod('myContentMethod');

After being registered, the method may be used on any object of that class.

// create a piece of content
$doc = $POD->getContent();

// call the custom method
$doc->myContentMethod();

Methods that are added in this manner must take as their first parameter an object which represents the object upon which the method was called. That is, the first parameter is the object that would otherwise be referenced using the $this variable:

// in handler.php or other pod code:
$doc->sampleFunction();


// in methods.php
function sampleFunction($content) {
  // $content == $doc
}

Content::registerMethod('sampleFunction');

You may also specify additional parameters after the object:

// in handler.php
$doc->sampleFunction2('foo');

// in methods.php
function sampleFunction2($content,$message) { 
// ...
}
Content::registerMethod('sampleFunction2');

Note, methods added in this way are only available if the pod is enabled!

In some circumstances, such as when overriding core functions or to avoid namespace collisions, you call your new method by a name that is different from the actual function name. In this case, you can pass a second parameter to registerMethod which will be used instead of the real name.

function functionWithALongUglyName($content){
...
}
Content::registerMethod('functionWithALongUglyName','foo');

// $content->foo() will now execute functionWithALongUglyName($content)

Activity Streams

2010-10-06T02:35:58-07:00

PeoplePods has the ability to generate an activity stream similar to the "news feed" found on Facebook and other social networking sites. Activity streams describe recent activity on the site by members - containing such brilliant pieces of content as "Joe is now following Bob," and "Bob left a comment on Joe's photo."

In order to make these messages as flexible and useful as possible, PeoplePods allows various pieces of data to be associated with the activity stream message. This data, such as a record of the person who performed the action, is used to display the activity message, and also allows the activity stream to be queried by any field within any of the related records - just like any stack object.

In addition, messages in the activity stream can include dynamic references to the associated data such as automatically generated links, usernames and headlines. Messages may also a "You" version for the acting user, and another for the target user. So, one recorded action might be represented as "Joe is now following Bob" as well as "You are now following Bob" as well as "Joe is now following you," depending on who is looking at it.

PeoplePods automatically publishes activity stream messages in 2 cases - when a member leaves a comment on another member's content, and when a member adds the "friend" flag to another member. Any additional messages must be added to custom pods or custom methods using the $user->publishActivity method().

Publishing Activity

// publish an activity to the stream
$user->publishActivity(
	$message,
	$userMessage,
	$targetMessage,
	$targetUser,
	$targetContent,
	$resultContent,
	$gid
);

The publishActivity method in its simplest form can be called with one parameter - a message to be added to the stream.

$user->publishActivity("Bob left a comment on Joe's photo.");

However, in most cases, you will want to also pass a second message so that when a member sees a message about their own action, it is personalized. This can be achieved by passing in the second parameters, $userMessage.

$user->publishActivity(
	"Bob left a comment on Joe's photo",
	"You left a comment on Joe's photo."
);

But why should Bob be the only member to receive the special first person treatment? Joe is a first person too! To personalize the message for the member who has been acted upon, we use the $targetMessage parameter.

$user->publishActivity(
	"Bob left a comment on Joe's photo",
	"You left a comment on Joe's photo.",
	"Bob left a comment on your photo."
);

Attaching Data

To really access the full power of the activity stream, we also need to pass along information about the activity. We know who did it, but we should also keep a record of what content or member the action was performed upon, and if any new content resulted from the activity. If we attach this data to the activity message when we publish it, we can reference values from the objects within the message using a simple tokens - this allows the messages to stay correct, even as the data changes.

There are two types of token available - one that simply inserts a value, and one that inserts a value that is also a link to the object's permalink page.

To insert a simple value, use a token in the form of: @object.field.

To insert a link, use a token in the form of {object.field}

In our example, we're using all of the different types of attached content. The tokens for each type of attached content are explained below.

Bob is the actor.

Bob took an action on a photo. The photo is the targetContent.

Since the photo is owned by Joe, he is the targetUser.

And since the action resulted in a new comment, the comment is the resultContent.

Using the token replacement system, the message becomes:

$message = '{actor.nick} left <a href="@resultContent.permalink">a comment</a> 
on {targetUser.nick}'s <a href="@targetContent.permalink">photo</a>.';

The tokens give you access to any field within the object, and either style of token can be used on any of the attached objects. Unless you need to construct a link with custom anchor text, we recommend you use the link tokens whenever possible:

// a message posted when someone posts something:
// members name will link to profile
// post headline will link to the post's permalink page
$message = '{actor.nick} just posted {targetContent.headline}';

Taking all of this together, we now have a publishActivity() call that looks something like this:

$comment = $photo->addComment('This is great!');

$user->publishActivity(
	'{actor.nick} left <a href="@resultContent.permalink">a comment</a> 
on {targetUser.nick}'s <a href="@targetContent.permalink">photo</a>.',
	'You left <a href="@resultContent.permalink">a comment</a> 
on {targetUser.nick}'s <a href="@targetContent.permalink">photo</a>.',
	'{actor.nick} left <a href="@resultContent.permalink">a comment</a> 
on <a href="@targetContent.permalink">your photo</a>.',
	$photo->author(),
	$photo,
	$comment
);

Repeating Actions

Your site might have certain actions that are repeatable. You don't want the same message appearing in the activity stream over and over again for the same action.

To avoid this, you can pass a unique identifier for the message into the publishActivity method. If the unique identifier already exists in the activity stream, the new version will be ignored.

This is useful for avoiding multiple "X is friends with Y" messages caused by members adding and removing friends.

$gid = $user->id . '-friends-with-' . $targetUser->id;	
$user->publishActivity(
	$message,
	$userMessage,
	$targetMessage,
	$targetUser,
	null,
	null,
	$gid
);

Querying the Activity Stream

$activity_stream = $POD->getActivityStream(
	$conditions,
	$sort,
	$count,
	$offset);

We can get a list of all activity on the site by calling the $POD->getActivityStream method with no parameters:

$activity = $POD->getActivityStream();

Or we can get a list of activities performed by specific user:

$my_activity = $POD->getActivityStream(array('u.id'=>$userid));

Or we can get a list of activities targeted at specific user:

$my_activity = $POD->getActivityStream(array('tu.id'=>$userid));

Or about activity related to a specific piece of content:

$content_activity = $POD->getActivityStream(array('d.id'=>$contentId));

The getActivityStream method can also be called on a Person object. In this scenario, the activities returned include both activities performed by the person, and activities targeted at the person. In other words, everything that person did, and everything that anyone else did to that person.

$my_activity = $user->getActivityStream();

Click here to view all of the options available when querying activity streams.

Displaying Activity Streams

Activity streams are output via the output() method, either on the activity stream itself, or on an individual activity message. Each message is output using a template from the activity/ folder. By default, activity/output.php will be used.

// output the entire stream
$activity_stream = $POD->getActivityStream();
$activity_stream->output();

// output one message at a time
foreach ($activity_stream as $action) { 
	$action->output();
}

// output the stream using mytheme/activity/custom.php
$activity_stream->output('custom');

Inside the template, you not only have access to the activity message, but also to all of the attached data. You can use the attached data to display thumbnail images, do additional processing, or whatever the heck you want.

To display the formatted activity message, use the formatActivity() method. This method will choose the appropriate message to display and do all of the token replacement:

<? echo $activity->formatActivity(); ?>

You can also access the attached data using the following variables:

// reference the activity itself
$message = $activity->formatActivity();
$minutes_since = $activity->minutes;

// reference the acting user
$actor = $activity->author();
$actor->permalink();

// reference the target user
$targetUser->permalink();

// reference the target content
// this could be EITHER a piece of content
// or a comment
// check the TYPE field.
if ($targetContent->TYPE=='content')  {
	// do something with content
} else if ($targetContent->TYPE=='comment') { 
	// do something with a comment
}

// reference the result content
// this can also be either content or a comment
if ($resultContent->TYPE=='content')  {
	// do something with content
} else if ($resultContent->TYPE=='comment') { 
	// do something with a comment
}

Function Reference

// query the activity stream
$stream = $POD->getActivityStream($conditions,$sort,$count,$offset);

// output a stream:
$stream->output($template,$header,$footer,$empty_message);

// output individual activities:
foreach ($stream as $action) { 
	$action->output($template,$alternative_path_to_template);
}

// format an activity for display:
$message = $activity->formatActivity();

// publish an action
$user->publishActivity(
	$message,
	$userMessage,
	$targetMessage,
	$targetUser,
	$targetContent,
	$resultContent,
	$gid
);


// get a personalized action stream of actions BY and UPON a user
$my_stream = $user->getActivityStream($count);

$Obj->flagDate()

2010-10-06T02:19:55-07:00

$date = $obj->flagDate($flag,$person);

Returns a string representing the date that $flag was added to $obj by $person

If the flag has NOT been added, returns false.

SDK Quick Start Guide

2009-12-03T03:59:10-08:00

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("$my_peoplepods_dir/PeoplePods.php");
$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();

Activity Streams, Alerts and Private Messaging

PeoplePods supports a variety of messaging techniques, including public activity stream, automated alerts, and member-to-member private messaging.

Read about Activity Streams

Read about Alerts

Read about Private Messaging

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);

$person->addFile()

2009-12-03T02:47:36-08:00

$person->addFile('img',$_FILES['img'],'optional caption goes here');

Takes an uploaded file and attaches it a person. This function is designed to handle rows out of the $_FILES array which PHP automatically provides when a file has been uploaded via an HTTP POST.

// store all files that were uploaded
foreach ($_FILES as $file_name => $file) { 
	$person->addFile($file_name,$file);
	if (!$person->success()) { 
	  echo $person->error();
	}
}

Image files will be automatically resized upon upload.

$content->addFile()

2009-12-03T02:46:53-08:00

$content->addFile('img',$_FILES['img'],'optional caption goes here');

Takes an uploaded file and attaches it to the piece of content. This function is designed to handle rows out of the $_FILES array which PHP automatically provides when a file has been uploaded via an HTTP POST.

// store all files that were uploaded
foreach ($_FILES as $file_name => $file) { 
	$content->addFile($file_name,$file);
	if (!$content->success()) { 
	  echo $content->error();
	}
}

Image files will be automatically resized upon upload.

$file->output()

2009-12-03T02:42:10-08:00

Outputs the current file using a template.

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

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

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

// output the file using a template from outside of the theme
// this will use /var/www/otherthemes/custom.php 
// unless custom.php is found in current theme.
$file->output('custom','/var/www/otherthemes/');

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

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

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

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

$POD->getFile()

2009-12-03T02:40:24-08:00

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();
}