<p><code>BridgeAbstract</code> is a base class for standard bridges. It implements the most common functions to simplify the process of adding new bridges.</p>
<p><code>BridgeAbstract</code> is a base class for standard bridges.
It implements the most common functions to simplify the process of adding new bridges.</p>
<hr/>
<h1><aid="creating-a-new-bridge"href="#creating-a-new-bridge"class="Permalink"aria-hidden="true"title="Permalink">#</a>Creating a new bridge</h1>
<p>You need four basic steps in order to create a new bridge:</p>
@@ -116,18 +117,26 @@
<ahref="#step-2---add-a-class-extending-bridgeabstract"><strong>Step 2</strong></a> - Add a class, extending <code>BridgeAbstract</code>
<ahref="#step-3---add-general-constants-to-the-class"><strong>Step 3</strong></a> - Add general constants to the class
<ahref="#step-4---implement-a-function-to-collect-feed-data"><strong>Step 4</strong></a> - Implement a function to collect feed data</p>
<p>These steps are described in more detail below. At the end of this document you’ll find a complete <ahref="#template">template</a> based on these instructions. The pictures below show an example based on these instructions:</p>
<p>These steps are described in more detail below.
At the end of this document you’ll find a complete <ahref="#template">template</a> based on these instructions.
The pictures below show an example based on these instructions:</p>
<p>Make sure to read these instructions carefully. Please don’t hesitate to open an <ahref="https://github.com/RSS-Bridge/rss-bridge/issues"class="Link--external"rel="noopener noreferrer">Issue</a> if you have further questions (or suggestions). Once your bridge is finished, please open a <ahref="https://github.com/RSS-Bridge/rss-bridge/pulls"class="Link--external"rel="noopener noreferrer">Pull Request</a>, in order to get your bridge merge into RSS-Bridge.</p>
<p>Make sure to read these instructions carefully.
Once your bridge is finished, please open a <ahref="https://github.com/RSS-Bridge/rss-bridge/pulls"class="Link--external"rel="noopener noreferrer">Pull Request</a>,
in order to get your bridge merge into RSS-Bridge.</p>
<hr/>
<h2><aid="step-1-create-a-new-file"href="#step-1-create-a-new-file"class="Permalink"aria-hidden="true"title="Permalink">#</a>Step 1 - Create a new file</h2>
<p>Please read <ahref="How_to_create_a_new_bridge.html">these instructions</a> on how to create a new file for RSS-Bridge.</p>
<h2><aid="step-2-add-a-class-extending-bridgeabstract"href="#step-2-add-a-class-extending-bridgeabstract"class="Permalink"aria-hidden="true"title="Permalink">#</a>Step 2 - Add a class, extending <code>BridgeAbstract</code></h2>
<p>Your bridge needs to be a class, which extends <code>BridgeAbstract</code>. The class name must <strong>exactly</strong> match the name of the file, without the file extension.</p>
<p>Your bridge needs to be a class, which extends <code>BridgeAbstract</code>.
The class name must <strong>exactly</strong> match the name of the file, without the file extension.</p>
<p><strong>Notice</strong>: <code>const PARAMETERS</code> can be used to request information from the user. Refer to <ahref="#parameters">these instructions</a> for more information.</p>
<p><strong>Notice</strong>: <code>const PARAMETERS</code> can be used to request information from the user.
Refer to <ahref="#parameters">these instructions</a> for more information.</p>
<h2><aid="step-4-implement-a-function-to-collect-feed-data"href="#step-4-implement-a-function-to-collect-feed-data"class="Permalink"aria-hidden="true"title="Permalink">#</a>Step 4 - Implement a function to collect feed data</h2>
<p>In order for RSS-Bridge to collect data, you must implement the <strong>public</strong> function <code>collectData</code>. This function takes no arguments and returns nothing. It generates a list of feed elements, which must be placed into the variable <code>$this->items</code>.</p>
<p>In order for RSS-Bridge to collect data, you must implement the <strong>public</strong> function <code>collectData</code>.
This function takes no arguments and returns nothing.
It generates a list of feed elements, which must be placed into the variable <code>$this->items</code>.</p>
<details><summary>Show example</summary><div>
<pre><codeclass="language-PHP"><?PHP
class MyBridge extends BridgeAbstract {
const NAME = 'My Bridge';
const URI = 'https://rss-bridge.github.io/rss-bridge/Bridge_API/BridgeAbstract.html';
<p>You can specify additional parameters in order to customize the bridge (i.e. to specify how many items to return). This document explains how to specify those parameters and which options are available to you.</p>
<p>You can specify additional parameters in order to customize the bridge (i.e. to specify how many items to return).
This document explains how to specify those parameters and which options are available to you.</p>
<p>For information on how to read parameter values during execution, please refer to the <ahref="../Helper_functions/index.html#getinput">getInput</a> function.</p>
<hr/>
<h2><aid="adding-parameters-to-a-bridge"href="#adding-parameters-to-a-bridge"class="Permalink"aria-hidden="true"title="Permalink">#</a>Adding parameters to a bridge</h2>
<p>Parameters are specified as part of the bridge class. An empty list of parameters is defined as <code>const PARAMETERS = [];</code></p>
<p>Parameters are specified as part of the bridge class.
An empty list of parameters is defined as <code>const PARAMETERS = [];</code></p>
<details><summary>Show example</summary><div>
<pre><codeclass="language-PHP"><?PHP
<pre><codeclass="language-PHP"><?php
class MyBridge extends BridgeAbstract {
/* ... */
const PARAMETERS = []; // Empty list of parameters (can be omitted)
@@ -221,7 +239,8 @@ class MyBridge extends BridgeAbstract {
@@ -238,7 +257,8 @@ class MyBridge extends BridgeAbstract {
];
</code></pre>
</div></details><br>
<p>You can also define a set of parameters that will be applied to every possible context of your bridge. To do this, specify a context named <code>global</code>.</p>
<p>You can also define a set of parameters that will be applied to every possible context of your bridge.
To do this, specify a context named <code>global</code>.</p>
@@ -349,27 +369,27 @@ where <code>n</code> is the name with which the bridge can access the parameter
<p>List values are defined in an associative array where keys are the string displayed in the combo list of the <strong>RSS-Bridge</strong> web interface, and values are the content of the <option> HTML tag value attribute.</p>
<pre><codeclass="language-PHP">...
'type' => 'list',
'values' =>array(
'values' =>[
'Item A' => 'itemA'
'Item B' => 'itemB'
)
]
...
</code></pre>
<p>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:</p>
<p>In this example <code>$this->queriedContext</code> will either return <strong>By user name</strong> or <strong>By user ID</strong>. The queried context might return no value, so the best way to handle it is by using a case-structure:</p>
<p>In this example <code>$this->queriedContext</code> will either return <strong>By user name</strong> or <strong>By user ID</strong>.
The queried context might return no value, so the best way to handle it is by using a case-structure:</p>
<p>The <code>collectData</code> function is responsible for collecting data and adding items to generate feeds from. If you are unsure how to solve a specific problem, please don’t hesitate to open an <ahref="https://github.com/RSS-Bridge/rss-bridge/issues"class="Link--external"rel="noopener noreferrer">Issue</a> on GitHub. Existing bridges are also a good source to learn implementing your own bridge.</p>
<p>The <code>collectData</code> function is responsible for collecting data and adding items to generate feeds from.
If you are unsure how to solve a specific problem, please don’t hesitate to open an <ahref="https://github.com/RSS-Bridge/rss-bridge/issues"class="Link--external"rel="noopener noreferrer">Issue</a> on GitHub.
Existing bridges are also a good source to learn implementing your own bridge.</p>
<h2><aid="implementing-the-collectdata-function"href="#implementing-the-collectdata-function"class="Permalink"aria-hidden="true"title="Permalink">#</a>Implementing the <code>collectData</code> function</h2>
<p>Implementation for the <code>collectData</code> function is specific to each bridge. However, there are certain reoccurring elements, described below. RSS-Bridge also provides functions to simplify the process of collecting and parsing HTML data (see “Helper Functions” on the sidebar)</p>
<p>Elements collected by this function must be stored in <code>$this->items</code>. The <code>items</code> variable is an array of item elements, each of which is an associative array that may contain arbitrary keys. RSS-Bridge specifies common keys which are used to generate most common feed formats.</p>
<p>Implementation for the <code>collectData</code> function is specific to each bridge.
However, there are certain reoccurring elements, described below. RSS-Bridge also provides functions to simplify the process of collecting and parsing HTML data (see “Helper Functions” on the sidebar)</p>
<p>Elements collected by this function must be stored in <code>$this->items</code>.
The <code>items</code> variable is an array of item elements, each of which is an associative array that may contain arbitrary keys.
RSS-Bridge specifies common keys which are used to generate most common feed formats.</p>
<details><summary>Show example</summary><div>
<pre><codeclass="language-PHP">
$item = []; // Create a new item
<pre><codeclass="language-PHP">$item = [];
$item['title'] = 'Hello World!';
$this->items[] = $item; // Add item to the list
$this->items[] = $item;
</code></pre>
</div></details><br>
Additional keys may be added for custom APIs (ignored by RSS-Bridge).
<p>Additional keys may be added for custom APIs (ignored by RSS-Bridge).</p>
<p>The item array should provide as much information as possible for RSS-Bridge to generate feature rich feeds. Find below list of keys supported by RSS-Bridge.</p>
<p>The item array should provide as much information as possible for RSS-Bridge to generate feature rich feeds.
Find below list of keys supported by RSS-Bridge.</p>
<pre><codeclass="language-PHP">$item['uri'] // URI to reach the subject ("https://...")
$item['title'] // Title of the item
$item['timestamp'] // Timestamp of the item in numeric or text format (compatible for strtotime())
@@ -440,118 +460,107 @@ $item['uid'] // A unique ID to identify the current item
<p>All formats support these parameters. The formats <code>Plaintext</code> and <code>JSON</code> also support custom parameters.</p>
<p>The <code>getDescription</code> function returns the description for a bridge.</p>
<p><strong>Notice:</strong> By default <strong>RSS-Bridge</strong> returns the contents of <code>const DESCRIPTION</code>, so you only have to implement this function if you require different behavior!</p>
<pre><codeclass="language-PHP"> public function getDescription(){
return self::DESCRIPTION;
}
<p><strong>Notice:</strong> By default <strong>RSS-Bridge</strong> returns the contents of <code>const DESCRIPTION</code>,
so you only have to implement this function if you require different behavior!</p>
<pre><codeclass="language-PHP">public function getDescription()
<p>The <code>getMaintainer</code> function returns the name of the maintainer for a bridge.</p>
<p><strong>Notice:</strong> By default <strong>RSS-Bridge</strong> returns <code>const MAINTAINER</code>, so you only have to implement this function if you require different behavior!</p>
<pre><codeclass="language-PHP"> public function getMaintainer(){
return self::MAINTAINER;
}
<p><strong>Notice:</strong> By default <strong>RSS-Bridge</strong> returns <code>const MAINTAINER</code>,
so you only have to implement this function if you require different behavior!</p>
<pre><codeclass="language-PHP">public function getMaintainer()
<p>The <code>getName</code> function returns the name of a bridge.</p>
<p><strong>Notice:</strong> By default <strong>RSS-Bridge</strong> returns <code>const NAME</code>, so you only have to implement this function if you require different behavior!</p>
<pre><codeclass="language-PHP"> public function getName(){
return self::NAME;
}
<p><strong>Notice:</strong> By default <strong>RSS-Bridge</strong> returns <code>const NAME</code>,
so you only have to implement this function if you require different behavior!</p>
<pre><codeclass="language-PHP">public function getName()
<p>The <code>getURI</code> function returns the base URI for a bridge.</p>
<p><strong>Notice:</strong> By default <strong>RSS-Bridge</strong> returns <code>const URI</code>, so you only have to implement this function if you require different behavior!</p>
<pre><codeclass="language-PHP"> public function getURI(){
return self::URI;
}
<p><strong>Notice:</strong> By default <strong>RSS-Bridge</strong> returns <code>const URI</code>,
so you only have to implement this function if you require different behavior!</p>
<pre><codeclass="language-PHP">public function getURI()
<p>The <code>getIcon</code> function returns the URI for an icon, used as favicon in feeds.</p>
<p>If no icon is specified by the bridge, RSS-Bridge will use a default location: <code>static::URI . '/favicon.ico'</code> (i.e. “https://github.com/favicon.ico”) which may or may not exist.</p>
<pre><codeclass="language-PHP"> public function getIcon(){
return static::URI . '/favicon.ico';
}
<p>If no icon is specified by the bridge,
RSS-Bridge will use a default location: <code>static::URI . '/favicon.ico'</code> (i.e. “https://github.com/favicon.ico”) which may or may not exist.</p>
<pre><codeclass="language-PHP">public function getIcon()
<p>The <code>detectParameters</code> function takes a URL and attempts to extract a valid set of parameters for the current bridge.</p>
<p>If the passed URL is valid for this bridge, the function should return an array of parameter -> value pairs that can be used by this bridge, including context if available, or an empty array if the bridge requires no parameters. If the URL is not relevant for this bridge, the function should return <code>null</code>.</p>
<p><strong>Notice:</strong> Implementing this function is optional. By default, <strong>RSS-Bridge</strong> tries to match the supplied URL to the <code>URI</code> constant defined in the bridge, which may be enough for bridges without any parameters defined.</p>
<pre><codeclass="language-PHP">public function detectParameters($url){
<p><strong>Notice:</strong> This function is also used by the <ahref="../For_Developers/Actions.html#findfeed">findFeed</a> action. This action allows an user to get a list of all feeds corresponding to an URL.</p>
<p><strong>Notice:</strong> This function is also used by the <ahref="../For_Developers/Actions.html#findfeed">findFeed</a> action.
This action allows an user to get a list of all feeds corresponding to an URL.</p>
<p>You can implement automated tests for the <code>detectParameters</code> function by adding the <code>TEST_DETECT_PARAMETERS</code> constant to your bridge class constant.</p>
<p><code>TEST_DETECT_PARAMETERS</code> is an array, with as key the URL passed to the <code>detectParameters</code>function and as value, the array of parameters returned by <code>detectParameters</code></p>
<p><code>BridgeAbstract</code> implements helper methods to make it easier for bridge maintainers to create bridges. Use these methods whenever possible instead of writing your own.</p>
<ul>
<li>
<ahref="#savecachevalue">saveCacheValue</a>
</li>
<li>
<ahref="#loadcachevalue">loadCacheValue</a>
</li>
</ul>
<p><code>BridgeAbstract</code> implements helper methods to make it easier for bridge maintainers to create bridges.
Use these methods whenever possible instead of writing your own.</p>
<p>Within the context of the current bridge, stores a value by key in the cache. The value can later be retrieved with <ahref="#loadcachevalue">loadCacheValue</a>.</p>
<p>Within the context of the current bridge, loads a value by key from cache. Optionally specifies the cache duration for the key. Returns <code>null</code> if the key doesn’t exist or the value is expired.</p>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
dvikan