[BridgeAbstract] Add new page

BridgeAbstract.md

@@ -0,0 +1,221 @@
+`BridgeAbstract` is a base class intended for standard Bridges that need to filter HTML pages for content. 
+
+To create a new Bridge extending `BridgeAbstract` you must implement 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 metadata
+
+The basic metadata 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 data go 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 mentioning that you can also define a set of parameters that will be applied to every possible utilization 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 tool-tip 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');
+```
+
+# 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();
+		$this->update = ``;
+	}
+
+	public function collectData(array $params){
+		// Implement your bridge here!
+	}
+}
+// Imaginary empty line!
+```