mirrors/rss-bridge
1
0
Fork 0
mirror of https://github.com/RSS-Bridge/rss-bridge.git synced 2024-11-26 19:36:52 +03:00
Code Issues Projects Releases Packages Wiki Activity

[CREATE_BRIDGE] Remove file

Browse source 
The contents of this file are now part of the Wiki
This commit is contained in:
logmanoriginal 2016-08-13 21:32:14 +02:00
parent 0e7f992e64
commit 890b48c56d
1 changed files with 0 additions and 237 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

237
CREATE_BRIDGE.md
View file

@ -1,237 +0,0 @@
# Howto create a bridge
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/`](bridges/) folder.
Read the following chapters an make sure to read the [Guidelines](#guidelines)!
## Specifications
A rss bridge must extend the `BridgeAbstract` class and implement the 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 metadatas
The basic metadatas 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 datas goes 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 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 :
```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 tooltip 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');
```
# 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 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();
}
public function collectData(array $params){
// Implement your bridge here!
}
}
```