From 04172923b7da515ed52042b17c5f94892810d391 Mon Sep 17 00:00:00 2001 From: LogMANOriginal Date: Sat, 15 Sep 2018 19:21:28 +0200 Subject: [PATCH] Updated BridgeAbstract (markdown) --- BridgeAbstract.md | 212 +++++++++++++++++++++------------------------- 1 file changed, 98 insertions(+), 114 deletions(-) diff --git a/BridgeAbstract.md b/BridgeAbstract.md index 50f3f87..4262f0e 100644 --- a/BridgeAbstract.md +++ b/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**) -- [`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: + +
Show pictures
+ +[[images/screenshot_bridgeabstract_example_card.png]] + +[[images/screenshot_bridgeabstract_example_atom.png]] + +

+ +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` + +
Show example
```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 +
+ +## 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 : +
Show example
```PHP -const NAME = 'Unnamed bridge'; -const URI = ''; -const DESCRIPTION = 'No description provided'; -const MAINTAINER = 'No maintainer'; -const PARAMETERS = array(); -const CACHE_TIMEOUT = 3600; +

-Parameters are defined in an array, which is used to generate an HTML `
` 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 : +
Show example
```PHP -const PARAMETERS = array(array(...), array(...)); -const PARAMETERS = array('First usage' => array(...), 'Second usage' => array(...)); +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 : +

-```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 \ 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 -items[] = $item; // Add item to the list } } -// Imaginary empty line! -``` - -Please remove the comments from the template before opening a PR! \ No newline at end of file +// This line is empty (just imagine it!) +``` \ No newline at end of file