Pubwich

Pubwich is an open-source PHP Web application that allows you to aggregate your published data from multiple Websites and services into a single HTML page.

Installation

Duplicate cfg/config.sample.php to cfg/config.php. (Optional: if you want to use a custom theme, duplicate themes/default to themes/your_theme_name and edit the PUBWICH_THEME constant in cfg/config.php to "your_theme_name".

Edit the newly created config.php to fill the blank spaces with your informations (API keys, usernames, site’s URL, etc.) and to modify the arguments passed to Pubwich::setServices(). See the Services configuration section of this file.

Modify your crontab file (by running crontab -e) and add the following line: */<N> * * * * <PHP> -f <ABSOLUTE_PATH>/cron/cron.php

Then replace the following elements: <N> → Cache expiration (in minutes) <PHP> → The path to PHP executable binary (usually /usr/bin/php or /usr/local/bin/php, use which php to find it) <ABSOLUTE_PATH> → Absolute path to Pubwich directory

Example: */10 * * * * /usr/bin/php -f /home/myusername/public_html/pubwich/cron/cron.php

Change the permissions on the cache directory to make it writeable for all (chmod -R 0777 cache).

Everything should be working now (when browsing to your server!).

Upgrading to Pubwich 1.4

There are a few things that you’ll need to consider when upgrading to Pubwich 1.4; Notably, Twitter OAuth support and a new templating language.

Twitter & OAuth

Before Pubwich 1.4, you needed to enter your Twitter username and password in order to make request to its API. This is called “Basic Authentication”. But since Twitter dropped support for this kind of authentication in june 2010, Pubwich doesn’t support it anymore. A small tutorial is available to show you how to create a Twitter application, get OAuth application keys and access tokens.

After you are done configuring Pubwich 1.4 to work with Twitter, you can remove your Twitter username and password parameters from your configuration file.

Custom item templates in your theme

Every theme has a functions.php file that contains at least the basic template for what Pubwich calls a “box”. Along with that boxTemplate function, you can define other templates, such as how an item is rendered for a specific service. Before Pubwich 1.4, you could use this template syntax:

function Atom_myblog_itemTemplate() {
  return '<li><a href="{%url%}">{%title%}</a> - {%content%}</li>'."\n";
}

But now, with the new Mustache.php template engine, you have to use this syntax:

function Atom_myblog_itemTemplate() {
  return '<li><a href="{{{url}}}">{{{title}}}</a> - {{{content}}}</li>'."\n";
}

So, basically, instead of {%variable%}, you have to use {{{variable}}}. The new template engine allows us to use conditionnals, loops and other kinds of cool stuff.

Service configuration

In Pubwich’s config.php file, a service looks like this:

array( 'Flickr', 'photos', array(
        'method' => 'FlickrUser',
        'title' => 'Flick<em>r</em>',
        'description' => 'latest photos',
        'total' => 16,
        'key' => '________',
        'userid' => '________',
        'username' => '__________',
        'row' => 4,
    )
),

Where Flickr is the service, photos is the variable and FlickrUser is the method.

These parameters can be used for all services:

• title → The box title.
• description → The box description.
• total → The number of items to display.

Atom

• url → The feed URL.
• link → The website URL.

Delicious

• username → The Delicious.com username.

Dribbble

• username → The Dribbble username.
• method → DribbbleShots.

DribbbleShots

No specific parameters

Facebook

• id → The Facebook user ID.
• key → The Facebook API key.
• username → The Facebook username.

Flickr

• row → The number of photos per row. Pubwich adds the class last-in-row to each row’s last photo.
• sort → The order in which to sort the photos. See this page for all the possible values.
• key → The Flickr API key.
• method → Either FlickrUser, FlickrGroup, FlickrTags

FlickrUser

• userid → The Flickr user ID. Use this page to find it.

FlickrGroup

• groupid → The Flickr group ID. Use this page to find it.

FlickrTags

• tags → The tags as an array() or a string with comma separated values.

GitHub

• username → The GitHub username
• method → Either GithubRecentActivity, GithubRepositories and GithubGists

GithubRecentActivity

No specific parameters

GithubRepositories

No specific parameters

GithubGists

No specific parameters

Goodreads

• userid → The Goodreads user ID.
• size → The size for each book cover.

Gowalla

• username → The Gowalla username.
• password → The Gowalla password.
• key → The Gowalla API key.
• method → Either GowallaUser, GowallaUserStamps, GowallaUserTopSpots

GowallaUser

No specific parameters

GowallaUserStamps

No specific parameters

GowallaUserTopSpots

No specific parameters

Lastfm

• username → The Last.fm username.
• key → The Last.fm API key.
• method → Either LastFMRecentTracks, LastFMWeeklyAlbums, LastFMTopAlbums

LastFMRecentTracks

No specific parameters

LastFMWeeklyAlbums

• size → The size of each album covers.

LastFMTopAlbums

• size → The size of each album covers.

Pinboard

• username → The Pinboard username.
• secret → The Pinboard secret token (grab it from your RSS feed URL).

Readernaut

• username → The Readernaut username.
• method → Either ReadernautBooks, ReadernautNotes

ReadernautBooks

• size → The size of each book covers.

ReadernautNotes

No specific parameters

Reddit

• username → The Readernaut username.
• key → Your API key. Go to this page and extract the key from one of the JSON feeds URL.
• method → RedditLiked

RedditLiked

No specific parameters

RSS

• url → The feed URL.
• link → The website URL.

SlideShare

• method → Either SlideShareUserSlideshows
• key → The SlideShare API key
• secret → The SlideShare shared secret

SlideShareUserSlideshows

• username → The SlideShare username.

StatusNet

• method → Either StatusNetUser, StatusNetSearch
• root → The StatusNet root URL (default is http://identi.ca)
• username → The StatusNet username.
• password → The StatusNet password.

StatusNetUser

No specific parameters

StatusNetSearch

• terms → The search query.

Text

• text → The text to display.

Twitter

• method → Either TwitterUser, TwitterSearch

• oauth → The OAuth configuration array. Example:

    'oauth' => array(
        'app_consumer_key' => '',
        'app_consumer_secret' => '',
        'user_access_token' => '',
        'user_access_token_secret' => ''
    ),
  

TwitterUser

• username → The Twitter username.

TwitterSearch

• terms → The search query.

Vimeo

• username → The Vimeo username.

YouTube

• username → The YouTube username.

Custom templates

When Pubwich is ready to display its data, it first looks into the theme’s functions.php file to see if custom template functions are defined. There are currently four kinds of template functions: box templates, item templates, column templates and layout templates.

Box templates

Box templates control the way whole boxes are displayed. There are a few different ways to define them:

• boxTemplate() (applies to all boxes, must be defined in functions.php)
• <Service>_boxTemplate()
• <Service>_<Method>_boxTemplate()
• <Service>_<Variable>_boxTemplate()
• <Service>_<Method>_<Variable>_boxTemplate()

Example:

function boxTemplate() {
    return '
        <div class="boite {{class}}" id="{{id}}">
            <h2><a rel="me" href="{{{url}}}">{{{title}}}</a> <span>{{{description}}}</span></h2>
            <div class="boite-inner">
                <ul class="clearfix">
                    {{{items}}}
                </ul>
            </div>
        </div>';
}

Item templates

Item templates control the way each box item is displayed. Each service has its own default templates, but using the following function names, you can redefine them:

• <Service>_itemTemplate()
• <Service>_<Method>_itemTemplate()
• <Service>_<Variable>_itemTemplate()
• <Service>_<Method>_<Variable>_itemTemplate()

Example:

function Twitter_TwitterUser_itemTemplate() {
    return '<li class="clearfix {{#in_reply_to_screen_name}}reply{{/in_reply_to_screen_name}}"><span class="date"><a href="{{{link}}}">{{{date}}}</a></span>{{{text}}}</li>'."\n";
}

There’s currently no documentation about which tag you can put between {{{}}} braces for which service. In the meantime, you can check a service file (located in lib/Services/<Service>.php) and look for the populateItemTemplate function.

Column templates

The column template defines how each column is rendered. You don’t have to define this template; the default used by Pubwich is this:

'<div class="col{{{number}}}">{{{content}}}</div>'

Where {{{number}}} is replaced by the column number and {{{content}}} is replaced by the column content (the boxes). For instance, you could put this in your functions.php file:

funtion columnTemplate() {
    '<div class="column column-{{{number}}}"><div class="column-inner">{{{content}}}</div></div>';
}

Layout templates

The layout template defines the columns layout. Again, you don’t have to define this template; the default layout used by Pubwich is this (eg. if you defined 3 columns in your config.php file):

'{{{col1}}} {{{col2}}} {{{col3}}}'

So each column is displayed one after the other. But if you’d like to change that layout, you can use this:

function layoutTemplate() {
    return '<div class="first-column">{{{col1}}}</div><div class="other-columns">{{{col2}}} {{{col3}}}</div>';
}