mirror/RSS-Bridge.rss-bridge
1
0
Fork 0
mirror of https://github.com/RSS-Bridge/rss-bridge.git synced 2025-06-28 16:00:14 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

[Documentation] Move all wiki pages into the repo and make it pretty (#2494)

Browse source
This commit is contained in:
Bocki 2022-03-22 21:33:29 +01:00 • committed by GitHub
parent 16470e8119
commit 76f5de3d0f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
53 changed files with 4215 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/05_Bridge_API/01_How_to_create_a_new_bridge.md Normal file
View file

@ -0,0 +1,30 @@
Create a new file in the `bridges/` folder (see [Folder structure](../04_For_Developers/03_Folder_structure.md)).
The file name must be named according to following specification:
* It starts with the full name of the site
* All white-space must be removed
* The first letter of a word is written in upper-case, unless the site name is specified otherwise (example: Freenews, not FreeNews, because the site is named 'Freenews')
* The first character must be upper-case
* The file name must end with 'Bridge'
* The file type must be PHP, written in **small** letters (seriously!) ".php"
**Examples:**
Site | Filename
-----|---------
Wikipedia | **Wikipedia**Bridge.php
Facebook | **Facebook**Bridge.php
GitHub | **GitHub**Bridge.php
Freenews | **Freenews**Bridge.php
The file must start with the PHP tags and end with an empty line. The closing tag `?>` is [omitted](http://php.net/basic-syntax.instruction-separation).
**Example:**
```php
<?php
// PHP code here
// This line is empty (just imagine it!)
```
The next step is to extend one of the base classes. Refer to one of an base classes listed on the [Bridge API](../05_Bridge_API/index.md) page.

456
docs/05_Bridge_API/02_BridgeAbstract.md Normal file
View file

@ -0,0 +1,456 @@
`BridgeAbstract` is a base class for standard bridges. It implements the most common functions to simplify the process of adding new bridges.
***
# Creating a new bridge
You need four basic steps in order to create a new bridge:
[**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
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>
![example card](../images/screenshot_bridgeabstract_example_card.png)
***
![example atom](../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](./01_How_to_create_a_new_bridge.md) 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
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)
```
<details><summary>Show example</summary><div>
```PHP
<?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!)
```
</div></details><br>
**Notice**: `const PARAMETERS` can be used to request information from the user. Refer to [these instructions](#parameters) for more information.
## Step 4 - Implement a function to collect feed data
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`.
<details><summary>Show example</summary><div>
```PHP
<?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!)
```
</div></details><br>
For more details on the `collectData` function refer to [these instructions](#collectdata).
***
# Template
Use this template to create your own bridge. Please remove any unnecessary comments and parameters.
```php
<?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() {
$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!)
```
# PARAMETERS
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.
For information on how to read parameter values during execution, please refer to the [getInput](../06_Helper_functions/index.md#getinput) function.
***
## Adding parameters to a bridge
Parameters are specified as part of the bridge class. An empty list of parameters is defined as `const PARAMETERS = array();`
<details><summary>Show example</summary><div>
```PHP
<?PHP
class MyBridge extends BridgeAbstract {
/* ... */
const PARAMETERS = array(); // Empty list of parameters (can be omitted)
/* ... */
}
```
</div></details><br>
Parameters are organized in two levels:
[**Level 1**](##level-1---context) - Context
[**Level 2**](##level-2---parameter) - Parameter
## Level 1 - Context
A context is defined as a associative array of parameters. The name of a context is displayed by RSS-Bridge.
<details><summary>Show example</summary><div>
```PHP
const PARAMETERS = array(
'My Context 1' => array(),
'My Context 2' => array()
);
```
**Output**
![bridge context named](../images/bridge_context_named.png)
</div></details><br>
_Notice_: The name of a context can be left empty if only one context is needed!
<details><summary>Show example</summary><div>
```PHP
const PARAMETERS = array(
array()
);
```
</div></details><br>
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 `global`.
<details><summary>Show example</summary><div>
```PHP
const PARAMETERS = array(
'global' => array() // Applies to all contexts!
);
```
</div></details>
## Level 2 - Parameter
Parameters are placed inside a context. They are defined as associative array of parameter specifications. Each parameter is defined by it's internal input name, a definition in the form `'n' => array();`, where `n` is the name with which the bridge can access the parameter during execution.
<details><summary>Show example</summary><div>
```PHP
const PARAMETERS = array(
'My Context' => array(
'n' => array()
)
);
```
</div></details><br>
The parameter specification consists of various fields, listed in the table below.
<details><summary>Show example</summary><div>
```PHP
const PARAMETERS = array(
'My Context' => array(
'n' => array(
'name' => 'Limit',
'type' => 'number',
'required' => false,
'title' => 'Maximum number of items to return',
'defaultValue' => 10
)
)
);
```
**Output**
![context parameter](../images/context_parameter_example.png)
</div></details>
***
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: `text`)
`required` | no | Boolean | `true`, `false` | Specifies if the parameter is required or not (default: `false`). Not supported for lists and checkboxes.
[`values`](#list-values) | no | associative array | | name/value pairs used by the HTML option tag, required for type '`list`'
`title` | no | Text | | Used as tool-tip when mouse-hovering over the input box
`pattern` | no | Text | | Defines a pattern for an element of type `text`. The pattern should be mentioned in the `title` attribute!
`exampleValue` | no | Text | | Defines an example value displayed for elements of type `text` and `number` when no data has been entered yet
[`defaultValue`](#defaultvalue) | no | | | Defines the default value if left blank by the user
#### 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'
)
...
```
#### 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
***
# queriedContext
The queried context is defined via `PARAMETERS` and can be accessed via `$this->queriedContext`.
It provides a way to identify which context the bridge is called with.
Example:
```PHP
...
const PARAMETERS = array(
'By user name' => array(
'u' => array('name' => 'Username')
),
'By user ID' => array(
'id' => array('name' => 'User ID')
)
);
...
```
In this example `$this->queriedContext` will either return **By user name** or **By user ID**. The queried context might return no value, so the best way to handle it is by using a case-structure:
```PHP
switch($this->queriedContext){
case 'By user name':
break;
case 'By user ID':
break;
default: // Return default value
}
```
# collectData
The `collectData` 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 [Issue](https://github.com/RSS-Bridge/rss-bridge/issues) on GitHub. Existing bridges are also a good source to learn implementing your own bridge.
## Implementing the `collectData` function
Implementation for the `collectData` 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)
Elements collected by this function must be stored in `$this->items`. The `items` 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.
<details><summary>Show example</summary><div>
```PHP
$item = array(); // Create a new item
$item['title'] = 'Hello World!';
$this->items[] = $item; // Add item to the list
```
</div></details><br>
Additional keys may be added for custom APIs (ignored by RSS-Bridge).
## Item parameters
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.
```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())
$item['author'] // Name of the author for this item
$item['content'] // Content in HTML format
$item['enclosures'] // Array of URIs to an attachments (pictures, files, etc...)
$item['categories'] // Array of categories / tags / topics
$item['uid'] // A unique ID to identify the current item
```
All formats support these parameters. The formats `Plaintext` and `JSON` also support custom parameters.
# getDescription
The `getDescription` function returns the description for a bridge.
**Notice:** By default **RSS-Bridge** returns the contents of `const DESCRIPTION`, so you only have to implement this function if you require different behavior!
```PHP
public function getDescription(){
return self::DESCRIPTION;
}
```
# getMaintainer
The `getMaintainer` function returns the name of the maintainer for a bridge.
**Notice:** By default **RSS-Bridge** returns `const MAINTAINER`, so you only have to implement this function if you require different behavior!
```PHP
public function getMaintainer(){
return self::MAINTAINER;
}
```
# getName
The `getName` function returns the name of a bridge.
**Notice:** By default **RSS-Bridge** returns `const NAME`, so you only have to implement this function if you require different behavior!
```PHP
public function getName(){
return self::NAME;
}
```
# getURI
The `getURI` function returns the base URI for a bridge.
**Notice:** By default **RSS-Bridge** returns `const URI`, so you only have to implement this function if you require different behavior!
```PHP
public function getURI(){
return self::URI;
}
```
# getIcon
The `getIcon` function returns the URI for an icon, used as favicon in feeds.
If no icon is specified by the bridge, RSS-Bridge will use a default location: `static::URI . '/favicon.ico'` (i.e. "https://github.com/favicon.ico") which may or may not exist.
```PHP
public function getIcon(){
return static::URI . '/favicon.ico';
}
```
# detectParameters
The `detectParameters` function takes a URL and attempts to extract a valid set of parameters for the current bridge.
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, or an empty array if the bridge requires no parameters. If the URL is not relevant for this bridge the function should return `null`.
**Notice:** Implementing this function is optional. By default **RSS-Bridge** tries to match the supplied URL to the `URI` constant defined in the bridge which may be enough for bridges without any parameters defined.
```PHP
public function detectParameters($url){
$regex = '/^(https?:\/\/)?(www\.)?(.+?)(\/)?$/';
if(empty(static::PARAMETERS)
&& preg_match($regex, $url, $urlMatches) > 0
&& preg_match($regex, static::URI, $bridgeUriMatches) > 0
&& $urlMatches[3] === $bridgeUriMatches[3]) {
return array();
} else {
return null;
}
}
```

104
docs/05_Bridge_API/03_FeedExpander.md Normal file
View file

@ -0,0 +1,104 @@
`FeedExpander` extends [`BridgeAbstract`](./02_BridgeAbstract.md) and adds functions to collect data from existing feeds.
**Usage example**: _You have discovered a site that provides feeds which are hidden and inaccessible by normal means. You want your bridge to directly read the feeds and provide them via **RSS-Bridge**_
To create a new Bridge extending `FeedExpander` you must implement all required functions of [`BridgeAbstract`](./02_BridgeAbstract.md). `FeedExpander` additionally provides following functions:
* [`parseItem`](#the-parseitem-function)
* [`getName`](#the-getname-function)
* [`getURI`](#the-geturi-function)
* [`getDescription`](#the-getdescription-function)
Find a [template](#template) at the end of this file.
**Notice:** For a standard feed only `collectData` need to be implemented. `collectData` should call `$this->collectExpandableDatas('your URI here');` to automatically load feed items and header data (will subsequently call `parseItem` for each item in the feed). You can limit the number of items to fetch by specifying an additional parameter for: `$this->collectExpandableDatas('your URI here', 10)` (limited to 10 items).
## The `parseItem` function
This function receives one item from the current feed and should return one **RSS-Bridge** item.
The default function does all the work to get the item data from the feed, whether it is RSS 1.0,
RSS 2.0 or Atom 1.0. If you have to redefine this function in your **RSS-Bridge** for whatever reason,
you should first call the parent function to initialize the item, then apply the changes that you require.
**Notice:** The following code sample is just an example. Implementation depends on your requirements!
```PHP
protected function parseItem($feedItem){
$item = parent::parseItem($feedItem);
$item['content'] = str_replace('rssbridge','RSS-Bridge',$feedItem->content);
return $item;
}
```
### Helper functions
The `FeedExpander` already provides a set of functions to parse RSS or Atom items based on the specifications. Where possible make use of these functions:
Function | Description
---------|------------
`parseATOMItem` | Parses an Atom 1.0 feed item
`parseRSS_0_9_1_Item` | Parses an RSS 0.91 feed item
`parseRSS_1_0_Item` | Parses an RSS 1.0 feed item
`parseRSS_2_0_Item` | Parses an RSS 2.0 feed item
In the following list you'll find the feed tags assigned to the the **RSS-Bridge** item keys:
Function | uri | title | timestamp | author | content
---------|-----|-------|-----------|--------|--------
`parseATOMItem` | id | title | updated | author | content
`parseRSS_0_9_1_Item` | link | title | | | description
`parseRSS_1_0_Item` | link | title | dc:date | dc:creator | description
`parseRSS_2_0_Item` | link, guid | title | pubDate, dc:date | author, dc:creator | description
## The `getName` function
Returns the name of the current feed.
```PHP
return $this->name;
```
**Notice:** Only implement this function if you require different behavior!
## The `getURI` function
Return the uri for the current feed.
```PHP
return $this->uri;
```
**Notice:** Only implement this function if you require different behavior!
## The `getDescription` function
Returns the description for the current bridge.
```PHP
return $this->description;
```
**Notice:** Only implement this function if you require different behavior!
# Template
This is the template for a new bridge:
```PHP
<?php
class MySiteBridge extends FeedExpander {
const MAINTAINER = 'No maintainer';
const NAME = 'Unnamed bridge';
const URI = '';
const DESCRIPTION = 'No description provided';
const PARAMETERS = array();
const CACHE_TIMEOUT = 3600;
public function collectData(){
$this->collectExpandableDatas('your feed URI');
}
}
// Imaginary empty line!
```

157
docs/05_Bridge_API/04_XPathAbstract.md Normal file
View file

@ -0,0 +1,157 @@
`XPathAbstract` extends [`BridgeAbstract`](./02_BridgeAbstract.md) and adds functionality for generating feeds based on _XPath expressions_. It makes creation of new bridges easy and if you're familiar with XPath expressions this class is probably the right point for you to start with.
At the end of this document you'll find a complete [template](#template) based on these instructions.
***
# Required constants
To create a new Bridge based on `XPathAbstract` your inheriting class should specify a set of constants describing the feed and the XPath expressions.
It is advised to override constants inherited from [`BridgeAbstract`](./02_BridgeAbstract.md#step-3---add-general-constants-to-the-class) aswell.
## Class constant `FEED_SOURCE_URL`
Source Web page URL (should provide either HTML or XML content). You can specify any website URL which serves data suited for display in RSS feeds
## Class constant `XPATH_EXPRESSION_FEED_TITLE`
XPath expression for extracting the feed title from the source page. If this is left blank or does not provide any data `BridgeAbstract::getName()` is used instead as the feed's title.
## Class constant `XPATH_EXPRESSION_FEED_ICON`
XPath expression for extracting the feed favicon URL from the source page. If this is left blank or does not provide any data `BridgeAbstract::getIcon()` is used instead as the feed's favicon URL.
## Class constant `XPATH_EXPRESSION_ITEM`
XPath expression for extracting the feed items from the source page. Enter an XPath expression matching a list of dom nodes, each node containing one feed article item in total (usually a surrounding `<div>` or `<span>` tag). This will be the context nodes for all of the following expressions. This expression usually starts with a single forward slash.
## Class constant `XPATH_EXPRESSION_ITEM_TITLE`
XPath expression for extracting an item title from the item context. This expression should match a node contained within each article item node containing the article headline. It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node.
## Class constant `XPATH_EXPRESSION_ITEM_CONTENT`
XPath expression for extracting an item's content from the item context. This expression should match a node contained within each article item node containing the article content or description. It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node.
## Class constant `XPATH_EXPRESSION_ITEM_URI`
XPath expression for extracting an item link from the item context. This expression should match a node's attribute containing the article URL (usually the href attribute of an `<a>` tag). It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node. Attributes can be selected by prepending an `@` char before the attributes name.
## Class constant `XPATH_EXPRESSION_ITEM_AUTHOR`
XPath expression for extracting an item author from the item context. This expression should match a node contained within each article item node containing the article author's name. It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node.
## Class constant `XPATH_EXPRESSION_ITEM_TIMESTAMP`
XPath expression for extracting an item timestamp from the item context. This expression should match a node or node's attribute containing the article timestamp or date (parsable by PHP's strtotime function). It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node. Attributes can be selected by prepending an `@` char before the attributes name.
## Class constant `XPATH_EXPRESSION_ITEM_ENCLOSURES`
XPath expression for extracting item enclosures (media content like images or movies) from the item context. This expression should match a node's attribute containing an article image URL (usually the src attribute of an <img> tag or a style attribute). It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node. Attributes can be selected by prepending an `@` char before the attributes name.
## Class constant `XPATH_EXPRESSION_ITEM_CATEGORIES`
XPath expression for extracting an item category from the item context. This expression should match a node or node's attribute contained within each article item node containing the article category. This could be inside <div> or <span> tags or sometimes be hidden in a data attribute. It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node. Attributes can be selected by prepending an `@` char before the attributes name.
## Class constant `SETTING_FIX_ENCODING`
Turns on automatic fixing of encoding errors. Set this to true for fixing feed encoding by invoking PHP's `utf8_decode` function on all extracted texts. Try this in case you see "broken" or "weird" characters in your feed where you'd normally expect umlauts or any other non-ascii characters.
# Optional methods
`XPathAbstract` offers a set of methods which can be overridden by derived classes for fine tuning and customization. This is optional. The methods provided for overriding can be grouped into three categories.
## Methods for providing XPath expressions
Usually XPath expressions are defined in the class constants described above. By default the following base methods just return the value of its corresponding class constant. However deriving classed can override them in case if XPath expressions need to be formed dynamically or based on conditions. In case any of these methods is defined, the method's return value is used instead of the corresponding constant for providing the value.
### Method `getSourceUrl()`
Should return the source Web page URL used as a base for applying the XPath expressions.
### Method `getExpressionTitle()`
Should return the XPath expression for extracting the feed title from the source page.
### Method `getExpressionIcon()`
Should return the XPath expression for extracting the feed favicon from the source page.
### Method `getExpressionItem()`
Should return the XPath expression for extracting the feed items from the source page.
### Method `getExpressionItemTitle()`
Should return the XPath expression for extracting an item title from the item context.
### Method `getExpressionItemContent()`
Should return the XPath expression for extracting an item's content from the item context.
### Method `getExpressionItemUri()`
Should return the XPath expression for extracting an item link from the item context.
### Method `getExpressionItemAuthor()`
Should return the XPath expression for extracting an item author from the item context.
### Method `getExpressionItemTimestamp()`
Should return the XPath expression for extracting an item timestamp from the item context.
### Method `getExpressionItemEnclosures()`
Should return the XPath expression for extracting item enclosures (media content like images or movies) from the item context.
### Method `getExpressionItemCategories()`
Should return the XPath expression for extracting an item category from the item context.
### Method `getSettingFixEncoding()`
Should return the Fix encoding setting value (bool true or false).
## Methods for providing feed data
Those methods are invoked for providing the HTML source as a base for applying the XPath expressions as well as feed meta data as the title and icon.
### Method `provideWebsiteContent()`
This method should return the HTML source as a base for the XPath expressions. Usually it merely returns the HTML content of the URL specified in the constant `FEED_SOURCE_URL` retrieved by curl. Some sites however require user authentication mechanisms, the use of special cookies and/or headers, where the direct retrival using standard curl would not suffice. In that case this method should be overridden and take care of the page retrival.
### Method `provideFeedTitle()`
This method should provide the feed title. Usually the XPath expression defined in `XPATH_EXPRESSION_FEED_TITLE` is used for extracting the title directly from the page source.
### Method `provideFeedIcon()`
This method should provide the feed title. Usually the XPath expression defined in `XPATH_EXPRESSION_FEED_ICON` is used for extracting the title directly from the page source.
### Method `provideFeedItems()`
This method should provide the feed items. Usually the XPath expression defined in `XPATH_EXPRESSION_ITEM` is used for extracting the items from the page source. All other XPath expressions are applied on a per-item basis, item by item, and only on the item's contents.
## Methods for formatting and filtering feed item attributes
The following methods are invoked after extraction of the feed items from the source. Each of them expect one parameter, the value of the corresponding field, which then can be processed and transformed by the method. You can override these methods in order to format or filter parts of the feed output.
### Method `formatItemTitle()`
Accepts the items title values as parameter, processes and returns it. Should return a string.
### Method `formatItemContent()`
Accepts the items content as parameter, processes and returns it. Should return a string.
### Method `formatItemUri()`
Accepts the items link URL as parameter, processes and returns it. Should return a string.
### Method `formatItemAuthor()`
Accepts the items author as parameter, processes and returns it. Should return a string.
### Method `formatItemTimestamp()`
Accepts the items creation timestamp as parameter, processes and returns it. Should return a unix timestamp as integer.
### Method `cleanImageUrl()`
Method invoked for cleaning feed icon and item image URL's. Extracts the image URL from the passed parameter, stripping any additional content. Furthermore makes sure that relative image URL's get transformed to absolute ones.
### Method `fixEncoding()`
Only invoked when class constant `SETTING_FIX_ENCODING` is set to true. It then passes all extracted string values through PHP's `utf8_decode` function.
### Method `generateItemId()`
This method plays in important role for generating feed item ids for all extracted items. Every feed item needs an unique identifier (Uid), so that your feed reader updates the original item instead of adding a duplicate in case an items content is updated on the source site. Usually the items link URL is a good candidate the the Uid.
***
# Template
Use this template to create your own bridge. Please remove any unnecessary comments and parameters.
```PHP
<?php
class TestBridge extends XPathAbstract {
const NAME = 'Test';
const URI = 'https://www.unbemerkt.eu/de/blog/';
const DESCRIPTION = 'Test';
const MAINTAINER = 'your name';
const CACHE_TIMEOUT = 3600;
const FEED_SOURCE_URL = 'https://www.unbemerkt.eu/de/blog/';
const XPATH_EXPRESSION_ITEM = '/html[1]/body[1]/section[1]/section[1]/div[1]/div[1]/div[1]/div[1]/div[1]/div[*]/article[1]';
const XPATH_EXPRESSION_ITEM_TITLE = './/a[@target="_self"]';
const XPATH_EXPRESSION_ITEM_CONTENT = './/div[@class="post-content"]';
const XPATH_EXPRESSION_ITEM_URI = './/a[@class="more-btn"]/@href';
const XPATH_EXPRESSION_ITEM_AUTHOR = '/html[1]/body[1]/section[1]/div[2]/div[1]/div[1]/h1[1]';
const XPATH_EXPRESSION_ITEM_TIMESTAMP = './/time/@datetime';
const XPATH_EXPRESSION_ITEM_ENCLOSURES = './/img/@data-src';
const SETTING_FIX_ENCODING = false;
}
```

9
docs/05_Bridge_API/index.md Normal file
View file

@ -0,0 +1,9 @@
A _Bridge_ is an class that allows **RSS-Bridge** to create an RSS-feed from a website. A _Bridge_ represents one element on the [Welcome screen](../01_General/04_Screenshots.md) and covers one or more sites to return feeds for. It is developed in a PHP file located in the `bridges/` folder (see [Folder structure](../04_For_Developers/03_Folder_structure.md)) and extends one of the base classes of **RSS-Bridge**:
Base class | Description
-----------|------------
[`BridgeAbstract`](./02_BridgeAbstract.md) | This class is intended for standard _Bridges_ that need to filter HTML pages for content.
[`FeedExpander`](./03_FeedExpander.md) | This class is an extension of `HttpCachingBridgeAbstract`, designed to load existing feeds into **RSS-Bridge**
[`XPathAbstract`](./04_XPathAbstract.md) | This class is meant as an alternative base class for bridge implementations. It offers preliminary functionality for generating feeds based on _XPath expressions_.
For more information about how to create a new _Bridge_, read [How to create a new Bridge?](./01_How_to_create_a_new_bridge.md)