To infinity and beyond

TopExtending Lifestream

LifeStream was built with a very specific goal: to create a system which would support any feed with very little modification. All included LifeStream feeds are run off of RSS or Atom, but the underlying system allows you to generate a feed from anything, including a database or API.

Let’s start with quick example of creating a feed, using the included Skitch feed. Your feed is contained within a single class, which must extend LifeStream_Feed. Inside of this there are several constants which you are most certainly going to want to define:

class LifeStream_SkitchFeed extends LifeStream_Feed
{
    // A unique ID for your feed. Must not conflict with any other feed plugins.
    const ID            = 'skitch';
    // The verbose name for your feed.
    const NAME          = 'Skitch';
    // An optional URL for more information about this feed.
    const URL           = 'http://www.skitch.com/';
    // A description for the feed, shown in the add feed and edit feed dialogs.
    const DESCRIPTION   = '';
    // The label class which handles rendering of events.
    const LABEL         = 'LifeStream_MessageLabel';
}

The constants are the very minimum required to operate a feed (which extends LifeStream_Feed), but there are also several functions within the feed which you may wish to override in order to customize your feeds interactions.

__toString()

Called when displaying the name of the feed instance in your feed management. This should return a string, and is typically the URL to the feed or some other key value unique to that feed.

    function __toString()
    {
        return $this->options['username'];
    }

get_options()

An array of arrays defining the options available for this feed. Please look at the included examples for more information and use cases of option types.

    function get_options()
    {        
        return array(

            // key_name => array(string label, boolean is_required, mixed default value, mixed choices
            'username' => array('Username:', true, '', ''),

        );
    }

get_url()

Returns the full URL to the RSS or Atom feed.

    function get_url()

    {
        return 'http://skitch.com/feeds/'.$this->options['username'].'/atom.xml';
    }

New in 0.50: get_url() can now return an array of URLs to fetch. You may also pass an additional key_name for use in more complex feeds.

    function get_url()
    {
        return array(

            array('http://skitch.com/feeds/'.$this->options['username'].'/atom.xml', 'key_name'),

        );
    }
 
    function get_url()
    {
        return array(

            'http://skitch.com/feeds/'.$this->options['username'].'/atom.xml',
        );
    }

yield($row)

The yield() function is passed one argument, the current row which is being processed. You MUST return an array, with at least a date and link value. The rest of the fields are entirely optional, but the default feed class looks for a title value.

    // This is from the Yelp feed
    function yield($row)
    {
        $title = $row->get_title();

 
        $on_part = ' on Yelp.com';
        if (substr($title, strlen($title)-strlen($on_part)) == $on_part)

            $title = substr($title, 0, strlen($title)-strlen($on_part));

 
        return array(
            'date'      =>  $row->get_date('U'),

            'link'      =>  html_entity_decode($row->get_link()),
            'title'     =>  html_entity_decode($title),

        );
    }

render_item($row, $item)

Called for each item when it is rendered. Should return a valid string. $row is the current row (from the database); $item is the current item (the row may be a group of rows, whereas the item is always the current item within that row).

    // Taken from the Twitter feed example.
    function render_item($row, $item)
    {

        return $this->parse_users($this->parse_urls($item['title']));
    }

Finally, you will need to register your feed with the LifeStream core:

register_lifestream_feed('LifeStream_YelpFeed');

If you are developing a feed which does not use RSS/Atom you will want to look at the internals of LifeStream_Feed to see how you can properly extend fetch() and any other calls which are SimplePie specific.


© 2005-2014 Enthropia Inc