blallo/rss-bridge
1
0
Fork 1
Code Issues Pull requests Releases Wiki Activity

[CREATE_BRIDGE] Update documentation to reflect current status

Browse source
This commit is contained in:
logmanoriginal 2016-08-05 19:43:39 +02:00
parent db95a2afca
commit 5b7a6300ec
1 changed files with 189 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

238
CREATE_BRIDGE.md
View file

@ -1,53 +1,54 @@
# Howto create a bridge # 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. 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, A rss bridge must extend the `BridgeAbstract` class and implement the following functions :
* 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 * [`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`. Find a [template](#template) at the end of this file.
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[]`. ## 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. The basic metadatas are :
### Basic metadatas.
The basic metadatas are the following :
```PHP ```PHP
$this->maintainer $this->maintainer // Name of the maintainer
$this->name $this->name // Name of the bridge
$this->uri $this->uri // URI to the target website of the bridge ("http://....")
$this->description $this->description // A brief description of the bridge
$this->update $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 ```PHP
$this->maintainer = 'No maintainer';
$this->name = "Unnamed bridge"; $this->name = "Unnamed bridge";
$this->uri = ""; $this->uri = "";
$this->description = 'No description provided'; $this->description = 'No description provided';
$this->maintainer = 'No maintainer'; $this->parameters = array();
``` ```
### Parameters ### 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. 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[] = ...
$this->parameters['First usage of my bridge'] = ... $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. 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 ### 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 : Following elements are supported :
* 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: 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 ```PHP
$this->parameters = ...
$this->parameters[] =
'[ '[
{ {
"name" : "Username", "name" : "Username",
"identifier" : "u" "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 RSS elements collected by this function must be stored in the class variable `items[]`.
---------------|------------------|------------
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 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()` ## Items
* 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 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 :
* `<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! ```PHP
* don't create duplicates. If the website runs on WordPress, use the generic WordPress bridge if possible. $item->uri // URI to reach the subject ("http://...")
* maintain efficient and well-commented code :wink: $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
}
}
```