About PubwichFork
================================================================================

[PubwichFork][1] 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][2] is not actively maintained anymore by the original author.
PubwichFork fixes several bugs and enables filtering of the data streams.

[1]: https://github.com/haschek/PubwichFork
[2]: http://pubwich.org/

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.
* Change the permissions on the cache directory to make it writeable for all
(`chmod -R 0777 cache`).
* _optional:_ 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][3]
* _optional:_ 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`

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

[3]: http://humanstxt.org/

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][4]. Please check the latest [Pubwich documentation][5]
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][6].

[4]: http://mustache.github.com/
[5]: https://github.com/remiprev/pubwich#readme
[6]: https://github.com/haschek/PubwichFork/issues

Service configuration
--------------------------------------------------------------------------------

All services are configured in the `config.php` file, usually a service looks
like this:

```php
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][7] 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][8].

[7]: https://github.com/haschek/PubwichFork/wiki/ServiceFeed
[8]: https://github.com/haschek/PubwichFork/wiki/SocialWebServices

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:

```php
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:

```php
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:

```php
'<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:

```php
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):

```php
'{{{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:

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