[RssExpander] Add new page

RssExpander.md

@@ -0,0 +1,130 @@
+`RssExpander` extends [`HttpCachingBridgeAbstract`](HttpCachingBridgeAbstract) and adds functions to collect data from existing RSS feeds.
+
+**Usage example**: _You have discovered a site that provides RSS feeds which are hidden and inaccessible by normal means. Tough it is possible if you know the URL. You want your bridge to directly read the feeds and provide them via **RSS-Bridge**_
+
+To create a new Bridge extending `RssExpander` you must implement all required functions of [`BridgeAbstract`](BridgeAbstract). You may also use all functions defined by [`HttpCachingBridgeAbstract`](HttpCachingBridgeAbstract). `RssExpander` additionally provides following functions:
+
+* [`parseRSSItem`](#the-parseRSSItem-function) (**required**)
+* [`collectExpandableDatas`](#the-collectExpandableDatas-function)
+* [`collect_RSS_2_0_data`](#the-collect_RSS_2_0_data-function)
+* [`RSS_2_0_time_to_timestamp`](#the-RSS_2_0_time_to_timestamp-function)
+* [`load_RSS_2_0_feed_data`](#the-load_RSS_2_0_feed_data-function)
+* [`getDescription`](#the-getDescription-function)
+
+Find a [template](#template) at the end of this file.
+
+**Notice:** For a standard RSS 2.0 feed only [`parseRSSItem`](#the-parseRSSItem-function) needs to be implemented.
+
+## The `parseRSSItem` function
+
+This function receives one item from the current RSS feed and should return one element of the [Item](BridgeAbstract#items) class.
+
+**Notice:** The following code sample is just an example. Implementation depends on your requirements!
+
+```PHP
+protected function parseRSSItem($rssItem){
+	$item = new \Item();
+	$item->title = $rssItem->title;
+	$item->uri = $rssItem->link;
+	$item->author = $rssItem->autor;
+	$item->timestamp = $this->RSS_2_0_time_to_timestamp($rssItem);
+	$item->content = $rssItem->content;
+
+	return $item;
+}
+```
+
+**Notice:** This function is automatically called by the [`collect_RSS_2_0_data`](#the-collect_RSS_2_0_data-function) function, unless the bridge implements that function differently.
+
+## The `collectExpandableDatas` function
+
+This function loads the RSS data from a given URL.
+
+```PHP
+public function collectExpandableDatas(array $param, $name){
+	if (empty($name))
+		$this->returnServerError('There is no $name for this RSS expander');
+
+	$content = $this->getContents($name) or $this->returnServerError('Could not request ' . $name . '!');
+	$rssContent = simplexml_load_string($content);
+	$this->collect_RSS_2_0_data($rssContent);
+}
+```
+
+**Notice:** Only implement this function if you require different behavior!
+
+## The `collect_RSS_2_0_data` function
+
+This function will iterate over the contents of an RSS 2.0 feed
+
+```PHP
+protected function collect_RSS_2_0_data($rssContent){
+	$channelData = $rssContent->channel[0];
+	$this->load_RSS_2_0_feed_data($channelData);
+	foreach($channelData->item as $item){
+		$this->items[] = $this->parseRSSItem($item);
+	}
+}
+```
+
+**Notice:** Only implement this function if you require different behavior!
+
+## The `RSS_2_0_time_to_timestamp` function
+
+This function will convert the RSS 2.0 times to a timestamp valid for **RSS-Bridge**
+
+```PHP
+protected function RSS_2_0_time_to_timestamp($item)  {
+	return DateTime::createFromFormat('D, d M Y H:i:s e', $item->pubDate)->getTimestamp();
+}
+```
+
+**Notice:** Only implement this function if you require different behavior!
+
+## The `load_RSS_2_0_feed_data` function
+
+This function will load header information from the current RSS feed.
+
+```PHP
+protected function load_RSS_2_0_feed_data($rssContent) {
+	$this->name = $rssContent->title;
+	$this->uri = $rssContent->link;
+	$this->description = $rssContent->description;
+}
+```
+
+**Notice:** Only implement this function if you require different behavior!
+
+## The `getDescription` function
+
+This function returns the description for the current bridge.
+
+```PHP
+return $this->description;
+```
+
+**Notice:** Only implement this function if you require different behavior!
+
+# Template
+
+This is the template for a new bridge:
+
+```PHP
+<?php
+class MySiteBridge extends RssExpander{
+	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!
+		parent::collectExpandableDatas($params, 'your RSS URL');
+	}
+}
+// Imaginary empty line!
+```