# Bridge Documentation

This directory contains custom RSS-Bridge implementations. For detailed documentation on creating and working with bridges, refer to the comprehensive guides in the `Bridge_Docs/` folder.

## Creating a New Bridge File

**File:** [Bridge_Docs/01_How_to_create_a_new_bridge.md](Bridge_Docs/01_How_to_create_a_new_bridge.md)

Basic guide for creating a new bridge file with proper structure. Covers the mandatory `declare(strict_types=1);` declaration and provides a minimal working example using `getSimpleHTMLDOM()` to scrape content.

## BridgeAbstract - Standard Bridge Base Class

**File:** [Bridge_Docs/02_BridgeAbstract.md](Bridge_Docs/02_BridgeAbstract.md)

Complete reference for `BridgeAbstract`, the base class for standard bridges. This is your primary resource for understanding:
- Required constants (NAME, URI, DESCRIPTION, MAINTAINER)
- How to define PARAMETERS for user input (text, number, list, checkbox)
- The `collectData()` method and item structure (title, uri, content, timestamp, author, etc.)
- Context handling with `$this->queriedContext`
- Helper methods like `saveCacheValue()` and `loadCacheValue()`
- Optional methods to override (getName, getURI, getIcon, detectParameters)

**Use this when:** Creating any standard bridge that scrapes HTML content directly.

## FeedExpander - RSS/Atom Feed Extension

**File:** [Bridge_Docs/03_FeedExpander.md](Bridge_Docs/03_FeedExpander.md)

Specialized class for bridges that consume existing RSS/Atom feeds and enhance or modify them. Extends `BridgeAbstract` with feed parsing capabilities.

Key features:
- Automatically parses RSS 1.0, RSS 2.0, and Atom 1.0 feeds
- Override `parseItem()` to modify individual feed items
- Call `$this->collectExpandableDatas('feed_url')` in `collectData()`
- Can limit number of items fetched

**Use this when:** Working with sites that already provide feeds but need enhancement (e.g., content modification, filtering, or expanding truncated content).

## WebDriverAbstract - JavaScript/XHR-Heavy Sites

**File:** [Bridge_Docs/04_WebDriverAbstract.md](Bridge_Docs/04_WebDriverAbstract.md)

For websites that heavily rely on JavaScript or XMLHttpRequest (XHR) to load content. Uses Selenium WebDriver with a real browser instance.

Important notes:
- Requires a running Selenium server (Docker image or local ChromeDriver)
- Very resource-intensive - only use when other methods fail
- Must explicitly wait for elements to appear after page loads or interactions
- Always call `$this->cleanUp()` in a finally block

**Use this when:** The target website loads content dynamically via JavaScript and cannot be scraped with standard HTML parsing methods.

## XPathAbstract - XPath-Based Bridges

**File:** [Bridge_Docs/05_XPathAbstract.md](Bridge_Docs/05_XPathAbstract.md)

Simplified bridge creation using XPath expressions. Ideal if you're familiar with XPath syntax.

Define these constants with XPath expressions:
- `FEED_SOURCE_URL` - The source webpage
- `XPATH_EXPRESSION_ITEM` - Selects each article/item container
- `XPATH_EXPRESSION_ITEM_TITLE` - Extracts title from item context
- `XPATH_EXPRESSION_ITEM_CONTENT` - Extracts content from item context
- `XPATH_EXPRESSION_ITEM_URI` - Extracts link URL
- Additional expressions for author, timestamp, enclosures, categories

Optional methods to override for formatting: `formatItemTitle()`, `formatItemContent()`, `formatItemUri()`, etc.

**Use this when:** You can identify the content you need using XPath expressions, making bridge creation declarative and concise.