From 5b7a6300ec4ed87cf582033f95da28aa3af9363a Mon Sep 17 00:00:00 2001
From: logmanoriginal <log.man@gmx.de>
Date: Fri, 5 Aug 2016 19:43:39 +0200
Subject: [PATCH] [CREATE_BRIDGE] Update documentation to reflect current
 status

---
 CREATE_BRIDGE.md | 238 +++++++++++++++++++++++++++++++++++++----------
 1 file changed, 189 insertions(+), 49 deletions(-)

diff --git a/CREATE_BRIDGE.md b/CREATE_BRIDGE.md
index 9948050c..f7dc13af 100644
--- a/CREATE_BRIDGE.md
+++ b/CREATE_BRIDGE.md
@@ -1,53 +1,54 @@
 # Howto create a bridge
 
-A bridge is an interface that allows rss-bridge to create a RSS feed from a website.
+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/` folder.
 
-##Specifications
+Read the following chapters an make sure to read the [Guidelines](#guidelines)!
 
-A rss bridge must extend the `BridgeAbstract` class, and implement the following functions :
+## Specifications
 
-* 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.
+A rss bridge must extend the `BridgeAbstract` class and implement the following functions :
 
-##The `collectData` function
+* [`loadMetadatas`](#the-loadmetadatas-function)
+* [`collectData`](#the-collectdata-function)
+* [`getName`](#the-getname-function)
+* [`getURI`](#the-geturi-function)
+* [`getCacheDuration`](#the-getcacheduration-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.
+Find a [template](#template) at the end of this file.
 
-The RSS elements are stored in the class variable `items[]`.
+## The `loadMetadatas` function
 
-Every RSS element is an instance of the `Item` class.
+This function is used by rss-bridge to determine the name, maintainer name, website, last updated date... of the bridge, and the user parameters.
 
-##The `loadMetadatas` function
+### Basic metadatas
 
-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 :
+The basic metadatas are :
 
 ```PHP
-$this->maintainer
-$this->name
-$this->uri
-$this->description
-$this->update
+$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
 ```
 
-The default values are the following :
+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->maintainer = 'No maintainer';
+$this->parameters = array();
 ```
 
 ### Parameters
 
-Parameters use a JSON-like format, which is parsed and transformed to HTML `<form>` by rss-bridge.
+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.
 
@@ -59,47 +60,186 @@ The array can be a key-based array, but it is not necessary. The following synta
 $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.
+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 (`[ ... ]`) containing every input.
+Every `$this->parameters` element is a JSON array of cluster (`[ ... ]`) containing all input fields.
 
-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.
+Following elements are supported :
 
-Hence, the most basic parameter definition is the following:
+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 =
+...
+	$this->parameters[] =
 	'[
 		{
 			"name" : "Username",
 			"identifier" : "u"
-
 		}
 	]';
+...
 ```
 
-####Optional parameters
+## The `collectData` function
 
-Here is a list of optional parameters for the input :
+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.
 
-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
+RSS elements collected by this function must be stored in the class variable `items[]`.
 
-#### Guidelines
+Every RSS element is an instance of the `Item` class.
 
-  * 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:
+## 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->thumbnailUri // URI for the thumbnail ("http://...")
+$item->title // Title of the item
+$item->name // Name 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
+`thumbnailUri`||X
+`title`|X|X|X
+`name`|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 should be displayed on the main page of rss-bridge.
+
+```PHP
+	public function getName(){
+		return ''; // Insert your bridge name here!
+	}
+```
+
+## 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 brige name.
+
+```PHP
+	public function getURI(){
+		return ''; // Insert your URI here!
+	}
+```
+
+## 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.
+
+```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 file_get_html 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 a template for a new bridge:
+
+```PHP
+class MySiteBridge extends BridgeAbstract{
+	public function loadMetadatas(){
+		$this->maintainer = 'No maintainer';
+		$this->name = $this->getName();
+		$this->uri = $this->getURI();
+		$this->description = 'No description provided';
+		$this->parameters = array();
+	}
+
+	public function collectData(array $params){
+		// Implement your bridge here!
+	}
+
+	public function getName(){
+		return ''; // Insert your bridge name here!
+	}
+
+	public function getURI(){
+		return ''; // Insert your URI here!
+	}
+
+	public function getCacheDuration(){
+		return 3600; // 1 hour
+	}
+}
+```