diff --git a/BridgeAbstract.md b/BridgeAbstract.md new file mode 100644 index 0000000..5db2d7e --- /dev/null +++ b/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 `
` 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 +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! +``` \ No newline at end of file