About PubwichFork

PubwichFork 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.

PubwichFork is an improved version of the original Pubwich application, since Pubwich is not actively maintained anymore by the original author. PubwichFork fixes several bugs and integrates pre-output filtering of the data streams.

Installation

If you need to upgrade from your current Pubwich install, please check the upgrading section in this file.

• 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 configuration section of this file.
• Edit the /humans.txt file to put your personal informations under TEAM title. You will find explanations and help about this initiative on humanstxt.org
• Modify your crontab file (by running crontab -e) and add the following line: */<N> * * * * <PHP> -f <ABSOLUTE_PATH>/cron/cron.php and 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 from Pubwich to PubwichFork 2.0

Last official Pubwich version is 1.5., please remember that Pubwich makes some important changes with version 1.4., e.g. Twitter OAuth support and the Mustache template engine. Please check the latest Pubwich documentation if you are still using a Pubwich install before version 1.4.

Backup your config.php; and your customized user theme, if you don't want to use the PubwichFork default theme. Then install PubwichFork and re-configure it. Usually your old config file and theme should work with PubwichFork. If not, please report bugs.

Service configuration

All services are configured in the config.php file, usually 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,
    )
),

In this example Flickr is the service name, photos is the service ID and the inner array is the service configuration. Some parameters can be used for all services:

• title → box title
• description → box description
• total → number of items to display
• cache_limit → cache invalidation time in seconds

The simplest and wide supported Feed service can be configured by additional parameters:

• url: URI of the feed
• contenttype: either application/rss+xml or application/atom+xml
• link: the URI of the website the feed is used for

There are several other service classes, e.g. for Delicious, Vimeo, YouTube, Flickr, Last.fm, simple Text, Dribbble, Facebook, Foursquare, Github, Goodreads, Gowalla, Instapaper, Pinboard, Readernaut, Readitlater, Reddit, Slideshare, Status.net and Twitter. For further info please read the Service documentation.

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>';
}