mirror/RSS-Bridge.rss-bridge
1
0
Fork 0
mirror of https://github.com/RSS-Bridge/rss-bridge.git synced 2025-07-22 19:55:02 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated BridgeAbstract (markdown)

LogMANOriginal 2018-09-15 19:21:28 +02:00
parent 91cfa0bf2e
commit 04172923b7
1 changed files with 98 additions and 114 deletions
Download patch file Download diff file Expand all files Collapse all files

212
BridgeAbstract.md

@ -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**) # Creating a new bridge
- [`getDescription`](The-getDescription-function)
- [`getMaintainer`](The-getMaintainer-function)
- [`getName`](The-getName-function)
- [`getURI`](The-getURI-function)
- [`getIcon`](The-getIcon-function)
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 ```PHP
const NAME // Name of the Bridge <?PHP
const URI // URI to the target website of the bridge ("http://....") class MyBridge extends BridgeAbstract {
const DESCRIPTION // A brief description of the Bridge
const MAINTAINER // Name of the maintainer }
const PARAMETERS // (optional) Definition of additional parameters // 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) const CACHE_TIMEOUT // (optional) Defines the maximum duration for the cache in seconds (default: 3600)
``` ```
Find a description of `const PARAMETERS` [below](#parameters) <details><summary>Show example</summary><div>
The default values are :
```PHP ```PHP
const NAME = 'Unnamed bridge'; <?PHP
const URI = ''; class MyBridge extends BridgeAbstract {
const DESCRIPTION = 'No description provided'; const NAME = 'My Bridge';
const MAINTAINER = 'No maintainer'; const URI = 'https://github.com/RSS-Bridge/rss-bridge/wiki/BridgeAbstract';
const PARAMETERS = array(); const DESCRIPTION = 'Returns "Hello World!"';
const CACHE_TIMEOUT = 3600; 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 ```PHP
const PARAMETERS = array(array(...), array(...)); <?PHP
const PARAMETERS = array('First usage' => array(...), 'Second usage' => array(...)); 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 For more details on the `collectData` function refer to [these instructions](The-collectData-function).
const PARAMETERS = array('global' => array(...));
```
### 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 # 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
<?php <?PHP
class MySiteBridge extends BridgeAbstract { class MyBridge extends BridgeAbstract {
const NAME = 'Unnamed bridge'; const NAME = 'Unnamed bridge';
const URI = ''; const URI = '';
const DESCRIPTION = 'No description provided'; const DESCRIPTION = 'No description provided';
const MAINTAINER = 'No maintainer'; const MAINTAINER = 'No maintainer';
const PARAMETERS = array(); // Can be omitted!
const CACHE_TIMEOUT = 3600; // Can be omitted!
public function collectData(){ public function collectData() {
// Implement your bridge here! $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!