mirror of
https://github.com/RSS-Bridge/rss-bridge.git
synced 2025-07-22 19:55:02 +02:00
Updated BridgeAbstract (markdown)
LogMANOriginal
parent
91cfa0bf2e
commit
04172923b7
1 changed files with 98 additions and 114 deletions
|
|
@ -1,150 +1,134 @@
|
|||
`BridgeAbstract` is a base class intended for standard Bridges that need to filter HTML pages for content.
|
||||
`BridgeAbstract` is a base class for standard bridges. It implements the most common functions to simplify the process of adding new bridges.
|
||||
|
||||
To create a new Bridge extending `BridgeAbstract` you must specify some [basic metadata](#basic-metadata) implement following functions:
|
||||
***
|
||||
|
||||
- [`collectData`](The-collectData-function) (**required**)
|
||||
- [`getDescription`](The-getDescription-function)
|
||||
- [`getMaintainer`](The-getMaintainer-function)
|
||||
- [`getName`](The-getName-function)
|
||||
- [`getURI`](The-getURI-function)
|
||||
- [`getIcon`](The-getIcon-function)
|
||||
# Creating a new bridge
|
||||
|
||||
Find a [template](#template) at the end of this file.
|
||||
You need four basic steps in order to create a new bridge:
|
||||
|
||||
## Basic metadata
|
||||
[**Step 1**](#step-1---create-a-new-file) - Create a new file
|
||||
[**Step 2**](#step-2---add-a-class-extending-bridgeabstract) - Add a class, extending `BridgeAbstract`
|
||||
[**Step 3**](#step-3---add-general-constants-to-the-class) - Add general constants to the class
|
||||
[**Step 4**](#step-4---implement-a-function-to-collect-feed-data) - Implement a function to collect feed data
|
||||
|
||||
The basic metadata are :
|
||||
These steps are described in more detail below. At the end of this document you'll find a complete [template](#template) based on these instructions. The pictures below show an example based on these instructions:
|
||||
|
||||
<details><summary>Show pictures</summary><div>
|
||||
|
||||
[[images/screenshot_bridgeabstract_example_card.png]]
|
||||
|
||||
[[images/screenshot_bridgeabstract_example_atom.png]]
|
||||
|
||||
</div></details><br>
|
||||
|
||||
Make sure to read these instructions carefully. Please don't hesitate to open an [Issue](https://github.com/RSS-Bridge/rss-bridge/issues) if you have further questions (or suggestions). Once your bridge is finished, please open a [Pull Request](https://github.com/RSS-Bridge/rss-bridge/pulls), in order to get your bridge merge into RSS-Bridge.
|
||||
|
||||
***
|
||||
|
||||
## Step 1 - Create a new file
|
||||
|
||||
Please read [these instructions](How-to-create-a-new-Bridge) on how to create a new file for RSS-Bridge.
|
||||
|
||||
## Step 2 - Add a class, extending `BridgeAbstract`
|
||||
|
||||
Your bridge needs to be a class, which extends `BridgeAbstract`. The class name must **exactly** match the name of the file, without the file extension.
|
||||
|
||||
For example: `MyBridge.php` => `MyBridge`
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
const NAME // Name of the Bridge
|
||||
const URI // URI to the target website of the bridge ("http://....")
|
||||
const DESCRIPTION // A brief description of the Bridge
|
||||
const MAINTAINER // Name of the maintainer
|
||||
const PARAMETERS // (optional) Definition of additional parameters
|
||||
<?PHP
|
||||
class MyBridge extends BridgeAbstract {
|
||||
|
||||
}
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
</div></details>
|
||||
|
||||
## Step 3 - Add general constants to the class
|
||||
|
||||
In order to present your bridge on the front page, RSS-Bridge requires a few constants:
|
||||
|
||||
```PHP
|
||||
const NAME // Name of the Bridge (default: "Unnamed Bridge")
|
||||
const URI // URI to the target website of the bridge (default: empty)
|
||||
const DESCRIPTION // A brief description of the Bridge (default: "No description provided")
|
||||
const MAINTAINER // Name of the maintainer, i.e. your name on GitHub (default: "No maintainer")
|
||||
const PARAMETERS // (optional) Definition of additional parameters (default: empty)
|
||||
const CACHE_TIMEOUT // (optional) Defines the maximum duration for the cache in seconds (default: 3600)
|
||||
```
|
||||
|
||||
Find a description of `const PARAMETERS` [below](#parameters)
|
||||
|
||||
The default values are :
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
const NAME = 'Unnamed bridge';
|
||||
const URI = '';
|
||||
const DESCRIPTION = 'No description provided';
|
||||
const MAINTAINER = 'No maintainer';
|
||||
const PARAMETERS = array();
|
||||
const CACHE_TIMEOUT = 3600;
|
||||
<?PHP
|
||||
class MyBridge extends BridgeAbstract {
|
||||
const NAME = 'My Bridge';
|
||||
const URI = 'https://github.com/RSS-Bridge/rss-bridge/wiki/BridgeAbstract';
|
||||
const DESCRIPTION = 'Returns "Hello World!"';
|
||||
const MAINTAINER = 'ghost';
|
||||
}
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
</div></details><br>
|
||||
|
||||
Parameters are defined in an array, which is used to generate an HTML `<form>` by **RSS-Bridge**.
|
||||
**Notice**: `const PARAMETERS` can be used to request information from the user. Refer to [these instructions](const-PARAMETERS) for more information.
|
||||
|
||||
The `const PARAMETERS` array is not mandatory if your bridge doesn't take any parameter.
|
||||
## Step 4 - Implement a function to collect feed data
|
||||
|
||||
The first level of this array describes every possible usage of a bridge.
|
||||
In order for RSS-Bridge to collect data, you must implement the **public** function `collectData`. This function takes no arguments and returns nothing. It generates a list of feed elements, which must be placed into the variable `$this->items`.
|
||||
|
||||
The array can be a key-based array, but it is not necessary. The following syntaxes are hereby correct :
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
const PARAMETERS = array(array(...), array(...));
|
||||
const PARAMETERS = array('First usage' => array(...), 'Second usage' => array(...));
|
||||
<?PHP
|
||||
class MyBridge extends BridgeAbstract {
|
||||
const NAME = 'My Bridge';
|
||||
const URI = 'https://github.com/RSS-Bridge/rss-bridge/wiki/BridgeAbstract';
|
||||
const DESCRIPTION = 'Returns "Hello World!"';
|
||||
const MAINTAINER = 'ghost';
|
||||
|
||||
public function collectData() {
|
||||
$item = array(); // Create an empty item
|
||||
|
||||
$item['title'] = 'Hello World!';
|
||||
|
||||
$this->items[] = $item; // Add item to the list
|
||||
}
|
||||
}
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
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 :
|
||||
</div></details><br>
|
||||
|
||||
```PHP
|
||||
const PARAMETERS = array('global' => array(...));
|
||||
```
|
||||
For more details on the `collectData` function refer to [these instructions](The-collectData-function).
|
||||
|
||||
### Format specifications
|
||||
|
||||
`const PARAMETERS` element is an associative array whose key is the input field identifier, and the value is another array containing all input fields names and values.
|
||||
|
||||
Following elements are supported :
|
||||
|
||||
Parameter Name | Required | Type | Supported values | Description
|
||||
---------------|----------|------|------------------| -----------
|
||||
`name` | **yes** | Text | | Input name as displayed to the user
|
||||
`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`](#list-values) | no | associative array | | name/value pairs used by the HTML option tag, required with the '`list`' type
|
||||
`title` | no | Text | | Will be shown as tool-tip when mouse-hovering over the input
|
||||
`pattern` | no | Text | | Defines a pattern for an element of type `text`. The required pattern should be mentioned in the `title` attribute!
|
||||
`exampleValue` | no | Text | | Defines an example value that is shown for elements of type `text` and `number`
|
||||
[`defaultValue`](#defaultvalue) | no | | | Defines the default value.
|
||||
|
||||
Hence, the most basic parameter definition is the following :
|
||||
|
||||
```PHP
|
||||
...
|
||||
const PARAMETERS = array(
|
||||
'u' => array('name' => 'Username')
|
||||
);
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
#### defaultValue
|
||||
|
||||
This attribute defines the default value for your parameter. Its behavior depends on the `type`:
|
||||
|
||||
- `text`: Allows any text
|
||||
- `number`: Allows any number
|
||||
- `list`: Must match either name or value of one element
|
||||
- `checkbox`: Must be "checked" to activate the checkbox
|
||||
|
||||
#### List values
|
||||
|
||||
List values are defined in an associative array where keys are the string displayed in the combo list of the **RSS-Bridge** web interface, and values are the content of the \<option\> HTML tag value attribute.
|
||||
|
||||
```PHP
|
||||
...
|
||||
'type' => 'list',
|
||||
'values' => array(
|
||||
'Item A' => 'itemA'
|
||||
'Item B' => 'itemB'
|
||||
)
|
||||
...
|
||||
```
|
||||
|
||||
If a more complex organization is required to display the values, the above key/value can be used to set a title as a key and another array as a value:
|
||||
```PHP
|
||||
...
|
||||
'type' => 'list',
|
||||
'values' => array(
|
||||
'Item A' => 'itemA',
|
||||
'List 1' => array(
|
||||
'Item C' => 'itemC',
|
||||
'Item D' => 'itemD'
|
||||
),
|
||||
'List 2' => array(
|
||||
'Item E' => 'itemE',
|
||||
'Item F' => 'itemF'
|
||||
),
|
||||
'Item B' => 'itemB'
|
||||
)
|
||||
...
|
||||
```
|
||||
***
|
||||
|
||||
# Template
|
||||
|
||||
This is the minimum template for a new bridge:
|
||||
Use this template to create your own bridge. Please remove any unnecessary comments and parameters.
|
||||
|
||||
```PHP
|
||||
<?php
|
||||
class MySiteBridge extends BridgeAbstract {
|
||||
<?PHP
|
||||
class MyBridge extends BridgeAbstract {
|
||||
const NAME = 'Unnamed bridge';
|
||||
const URI = '';
|
||||
const DESCRIPTION = 'No description provided';
|
||||
const MAINTAINER = 'No maintainer';
|
||||
const PARAMETERS = array(); // Can be omitted!
|
||||
const CACHE_TIMEOUT = 3600; // Can be omitted!
|
||||
|
||||
public function collectData(){
|
||||
// Implement your bridge here!
|
||||
public function collectData() {
|
||||
$item = array(); // Create an empty item
|
||||
|
||||
$item['title'] = 'Hello World!';
|
||||
|
||||
$this->items[] = $item; // Add item to the list
|
||||
}
|
||||
}
|
||||
// Imaginary empty line!
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
Please remove the comments from the template before opening a PR!
|
||||
Loading…
Add table
Add a link
Reference in a new issue