rss-bridge/CREATE_BRIDGE.md

# Howto create a bridge

A bridge is an class that allows rss-bridge to create a RSS feed from a website.
The bridge is a PHP file, located in the [`bridges/`](bridges/) folder.

Read the following chapters an make sure to read the [Guidelines](#guidelines)!

## Specifications

A rss bridge must extend the `BridgeAbstract` class and implement the following functions :

* [`loadMetadatas`](#the-loadmetadatas-function) (**required**)
* [`collectData`](#the-collectdata-function) (**required**)
* [`getName`](#the-getname-function)
* [`getURI`](#the-geturi-function)
* [`getCacheDuration`](#the-getcacheduration-function)

Find a [template](#template) at the end of this file.

## The `loadMetadatas` function

This function is used by rss-bridge to determine the name, maintainer name, website, last updated date... of the bridge, and the user parameters.

### Basic metadatas

The basic metadatas are :

```PHP
$this->maintainer // Name of the maintainer
$this->name // Name of the bridge
$this->uri // URI to the target website of the bridge ("http://....")
$this->description // A brief description of the bridge
$this->update // Date of last change in format "yyyy-mm-dd"
$this->parameters // (optional) Definition of additional parameters
```

Find a description of `$this->parameters` [below](#parameters)

The default values are :

```PHP
$this->maintainer = 'No maintainer';
$this->name = "Unnamed bridge";
$this->uri = "";
$this->description = 'No description provided';
$this->parameters = array();
```

### Parameters

Parameters are defined in a JSON-like format, which is parsed and transformed into a HTML `<form>` by rss-bridge.

These datas goes into the `$this->parameters` array, which is not mandatory if your bridge doesn't take any parameter.

Every possible usage of a bridge is an array element.

The array can be a key-based array, but it is not necessary. The following syntaxes are hereby correct :

```PHP
$this->parameters[] = ...
$this->parameters['First usage of my bridge'] = ...
```

It is worth mentionning that you can also define a set of parameters that will be applied to every possible utilisation of your bridge.
To do this, just create a parameter array with the `global` key :

```PHP
$this->parameters['global'] = ...
```

### Format specifications

Every `$this->parameters` element is a JSON array of cluster (`[ ... ]`) containing all input fields.

Following elements are supported :

Parameter Name | Required | Type | Supported values | Description
---------------|----------|------|------------------| -----------
`name`|**yes**|Text||Input name as displayed to the user
`identifier`|**yes**|Text||Identifier, which will be the key in the `$param` array for the [`collectData`](#the-collectdata-function) function
`type`|no|Text|`text`, `number`, `list`, `checkbox`|Type of the input, default is text
`required`|no|Boolean|`true`, `false`|Set this if you want your attribute to be required
`values`|no|Text|`[ {"name" : option1Name, "value" : "option1Value"}, ... ]`| Values list, required with the '`list`' type
`title`|no|Text||Will be shown as tooltip when mouse-hovering over the input

Hence, the most basic parameter definition is the following :

```PHP
...
	$this->parameters[] =
	'[
		{
			"name" : "Username",
			"identifier" : "u"
		}
	]';
...
```

## The `collectData` function

This function takes as a parameter an array called `$param`, that is automatically filled with values from the user, according to the values defined in the parameters array in `loadMetadatas`.
This function is the place where all the website scrapping and the RSS feed generation process must be implemented.

RSS elements collected by this function must be stored in the class variable `items[]`.

Every RSS element is an instance of the `Item` class.

## Items

The `Item` class is used to store parameter that are collected in the [`collectData`](#the-collectdata-function) function. Following properties are supported by rss-bridge :

```PHP
$item->uri // URI to reach the subject ("http://...")
$item->title // Title of the item
$item->timestamp // Timestamp of the item in numeric format (use strtotime)
$item->author // Name of the author
$item->content // Content in HTML format
```

In order to create a new item you'll have to escape the **I** in **I**tem like this :

```PHP
$item = new \Item();
```

### Item usage

Which items are necessary depends on the output format. There are two formats that support literally any property in the `$item`:

* JSON
* Plaintext

The following list provides an overview of the parameters used by the other formats :

Parameter | ATOM | HTML | (M)RSS
----------|------|------|-------
`uri`|X|X|X
`title`|X|X|X
`timestamp`|X|X|X
`author`|X|X|X
`content`|X|X|X

## The `getName` function

This function returns the name of the bridge as it will be displayed on the main page of rss-bridge or on top of the feed output (HTML, ATOM, etc...).

**Notice:** rss-bridge will by default return `$this->name` which is defined in the [`loadMetadatas`](#the-loadmetadatas-function) function, so you only have to implement this function if you require different behavior!

```PHP
	public function getName(){
		return $this->name;
	}
```

## The `getURI` function

This function returns the URI to the destination site of the bridge. It will be used on the main page of rss-bridge when clicking your bridge name.

**Notice:** rss-bridge will by default return `$this->uri` which is defined in the [`loadMetadatas`](#the-loadmetadatas-function) function, so you only have to implement this function if you require different behavior!

```PHP
	public function getURI(){
		return $this->uri;
	}
```

## The `getCacheDuration` function

This function returns the time in **seconds** during which rss-bridge will output cached values instead of re-generating a RSS feed.

**Notice:** rss-bridge will return `3600` seconds (1 hour) by default, so you only have to implement this function if you require different timing!

```PHP
	public function getCacheDuration(){
		return 3600; // 1 hour
	}
```

# Bridge Abstract functions

All bridges extend from `BridgeAbstract` and therefore are able to make use of functions defined in `BridgeAbstract`. 

Following functions should be used for good practice and will support you with your bridge :

* [`returnError`](#the-returnerror-function)
* [`file_get_html`](#the-file_get_html-function)

## The `returnError` function

This function aborts execution of the current bridge and returns the given error message with the provided error number :

```PHP
$this->returnError('Your error message', 404)
```

Check the [list of error codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for applicable error numbers.

## The `file_get_html` function

This function is a wrapper around the [simple_html_dom](http://simplehtmldom.sourceforge.net/) [file_get_html](http://simplehtmldom.sourceforge.net/manual_api.htm#api) function in order to provide context by design. It is considered good practice to use this function.

```PHP
$html = $this->file_get_html('your URI');
```

# Guidelines

* scripts (eg. Javascript) must be stripped out. Make good use of `strip_tags()` and `preg_replace()`
* each bridge must present data within 8 seconds (adjust iterators accordingly)
* cache timeout must be fine-tuned so that each refresh can provide 1 or 2 new elements on busy periods
* `<audio>` and `<video>` must not autoplay. Seriously.
* do everything you can to extract valid timestamps. Translate formats, use API, exploit sitemap, whatever. Free the data!
* don't create duplicates. If the website runs on WordPress, use the generic WordPress bridge if possible.
* maintain efficient and well-commented code :wink:

# Template

This is the minimum template for a new bridge:

```PHP
<?php
class MySiteBridge extends BridgeAbstract{
	public function loadMetadatas(){
		$this->maintainer = 'No maintainer';
		$this->name = 'Unnamed bridge';
		$this->uri = '';
		$this->description = 'No description provided';
		$this->parameters = array();
	}

	public function collectData(array $params){
		// Implement your bridge here!
	}
}

```