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

More about this function and it's related functions:

$Stack->getNext()
$Stack->asArray()
$Stack->output()
$Stack->fill()
$Stack->contains()
$Stack->extract()
$Stack->implode()
$Stack->add()
$Stack->peekAhead()
$Stack->hasNextPage()
$Stack->nextPage()
$Stack->hasPreviousPage()
$Stack->previousPage()
$Stack->getNextPage()
$Stack->getPreviousPage()
$Stack->offset()
$Stack->count()
$Stack->totalCount()
$Stack->sortBy()

• Discuss This Document

No comments have been posted yet.

Download the latest version of PeoplePods!

0.9 Latest Version:
Release Notes

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

Username:

What is your email address?

Choose a password:

  Already Registered? Login