rss-bridge/CREATE_BRIDGE.md

Howto create a bridge

A bridge is an interface that allows rss-bridge to create a RSS feed from a website. The bridge is a PHP file, located in the bridges/ folder.

##Specifications

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

• The loadMetadatas function, described below,
• The getCacheDuration function, describing the time during which rss-bridge will output cached values instead of re-generating a RSS feed.
• The collectData function, also described below.

##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 setted in loadMetadatas. This function is the place where all the website scrapping and the RSS feed generation process will go.

The RSS elements are stored in the class variable items[].

Every RSS element is an instance of the Item class.

##The loadMetadatas function

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

Basic metadatas.

The basic metadatas are the following :

$this->maintainer
$this->name
$this->uri
$this->description
$this->update

The default values are the following :

$this->name = "Unnamed bridge";
$this->uri = "";
$this->description = 'No description provided';
$this->maintainer = 'No maintainer';

Parameters

Parameters use a JSON-like format, which is parsed and transformed to 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 :

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

Format specifications

Every $this->parameters element is a JSON array ([ ... ]) containing every input.

It needs the following elements to be setted :

• name, the input name as displayed to the user
• identifier, which will be the key in the $param array for the corresponding data.

Hence, the most basic parameter definition is the following:

	$this->parameters =
	'[
		{
			"name" : "Username",
			"identifier" : "u"

		}
	]';

####Optional parameters

Here is a list of optional parameters for the input :

Parameter Name	Parameter values	Description
type	text, number, list, checkbox	Type of the input, default is text
required	true	Set this if you want your attribute to be required
values	[ {"name" : option1Name, "value" : "option1Value"}, ...]	Values list, required with the 'list' type
title	text	Will be shown as tooltip when mouse-hovering over the input

Guidelines

• scripts (eg. Javascript) must be stripped out. Make good use of strip_tags() and preg_replace()
• 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: