# RSS

📡 A comprehensive RSS/Atom feed module for BoxLang that brings full-featured feed reading and creation capabilities to your applications!

This module provides powerful RSS and Atom feed capabilities to the [BoxLang](https://boxlang.io/) language, making it easy to read, parse, create, and manage syndication feeds with minimal code.

## ✨ Features

* 📖 **Read**: Parse RSS 2.0, RSS 1.0 (RDF), and Atom feeds from URLs or files
* ✍️ **Create**: Generate RSS 2.0 and Atom feeds with full metadata support
* 🎙️ **iTunes Podcast**: Auto-detect and parse iTunes podcast extensions (23 additional fields)
* 📹 **Media RSS**: Auto-detect and parse Media RSS extensions (thumbnails, content, player)
* 🔄 **Multiple Sources**: Read from multiple feed URLs simultaneously and merge results
* 🎯 **Filtering**: Apply custom filters to feed items during reading
* 📄 **Pagination**: Limit items with `maxItems` parameter
* 🔌 **Flexible Output**: Return results as structs, save to files, or get raw XML
* 🏢 **Enterprise Grade**: Built and Supported by Ortus Solutions
* 🔁 **CFML Compatible**: Drop-in replacement for CFML's `cffeed` tag

## 🥊 What's Included

This module provides the following BoxLang functions and components:

### Built-In Functions (BIFs)

* **`rss()`** - Simple function for reading RSS/Atom feeds with minimal configuration

### Components

* **`<bx:feed>`** - Full-featured component for reading and creating RSS/Atom feeds with extensive configuration options

Both the BIF and component support:

* Reading RSS 2.0, RSS 1.0 (RDF), and Atom feeds
* Creating RSS 2.0 and Atom feeds
* iTunes podcast and Media RSS extensions
* Multiple output formats and filtering options

## 📦 Installation

### Install via CommandBox

If you are using CommandBox for your web applications, simply run:

```bash
box install bx-rss
```

The module will automatically register and be available as `bxrss` in your BoxLang applications.

## 🚀 Quick Start

### Using the BIF (Easiest Way)

The simplest way to read an RSS feed is with the `rss()` function:

```javascript
feedData = rss( "https://example.com/feed.xml" );

println( "Found #feedData.items.size()# items" );
println( "Feed title: #feedData.channel.title#" );
```

### Using the Component

You can also use the `<bx:feed>` component for more control:

```javascript
bx:feed
    action="read"
    source="https://example.com/feed.xml"
    result="feedData";

println( "Found #feedData.items.size()# items" );
println( "Feed title: #feedData.channel.title#" );
```

That's it! 🎉 You now have feed data parsed and ready to use.

💡 **Pro Tip**: The `rss()` BIF is perfect for quick feed reading, while the component gives you more options like multiple output variables, file writing, and creating feeds.

## 🔧 Feed Actions

The module supports two core operations:

### 📖 Read

Parse existing RSS/Atom feeds from URLs or files.

* **Use Case**: Display blog posts, news articles, podcast episodes
* **Returns**: Struct with `items` array and `channel` metadata
* **Features**: Auto-detection of extensions, filtering, pagination, multiple output options
* **Extension Support**: Automatically includes iTunes podcast and Media RSS fields when present

### ✍️ Create

Generate new RSS/Atom feeds from your data.

* **Use Case**: Expose your content as RSS/Atom feeds, create podcasts
* **Returns**: XML string, file output, or both
* **Features**: Full metadata control, multiple item formats, character escaping
* **Formats**: RSS 2.0 or Atom

## 💡 Examples

### Basic Examples

#### 📖 Simple Feed Read

Read and display feed items:

```javascript
bx:feed
    action="read"
    source="https://example.com/blog/feed.xml"
    result="feedData";

println( "Blog: #feedData.channel.title#" );
println( "Items: #feedData.items.size()#" );

feedData.items.each( function( item ) {
    println( "- #item.title#: #item.link#" );
} );
```

💡 **Use Case**: Display latest blog posts or news articles.

#### 🎙️ Read iTunes Podcast Feed

Automatically detects and includes iTunes podcast fields:

```javascript
bx:feed
    action="read"
    source="https://feeds.example.com/podcast.xml"
    result="podcast";

println( "Podcast: #podcast.channel.title#" );
println( "Author: #podcast.channel.itunesAuthor#" );

podcast.items.each( function( episode ) {
    println( "Episode: #episode.itunesTitle#" );
    println( "Duration: #episode.itunesDuration#" );
    println( "Season #episode.itunesSeason# Episode #episode.itunesEpisode#" );
} );
```

💡 **Use Case**: Display podcast episodes with rich metadata.

#### 📹 Read Media RSS Feed

Automatically detects and includes Media RSS thumbnail/content fields:

```javascript
bx:feed
    action="read"
    source="https://vimeo.com/channels/staffpicks/videos/rss"
    result="videos";

videos.items.each( function( video ) {
    println( "Video: #video.title#" );
    if( !isNull( video.mediaThumbnail ) ) {
        println( "Thumbnail: #video.mediaThumbnail.url#" );
        println( "Size: #video.mediaThumbnail.width#x#video.mediaThumbnail.height#" );
    }
} );
```

💡 **Use Case**: Display video feeds with thumbnails.

#### 🎯 Filtered Feed Reading

Apply custom filters to feed items:

```javascript
bx:feed
    action="read"
    source="https://news.example.com/feed.xml"
    result="recentNews"
    maxItems="10";

println( "Latest 10 news items:" );
recentNews.items.each( function( item ) {
    println( "- #item.title# (#dateFormat( item.publishedDate )#)" );
} );
```

💡 **Use Case**: Display latest N items from a feed.

#### 📄 Multiple Output Options

Use different output variables simultaneously:

```javascript
bx:feed
    action="read"
    source="https://example.com/feed.xml"
    result="fullFeed"
    properties="metadata"
    query="items"
    xmlVar="rawXml"
    outputFile="/tmp/cached-feed.xml"
    overwrite="true";

// fullFeed has both items and channel
println( "Full structure: #fullFeed.items.size()# items" );

// metadata has only channel info
println( "Feed title: #metadata.title#" );

// items has only the items array
println( "Just items: #items.size()# entries" );

// rawXml has the original XML
println( "XML length: #rawXml.len()# characters" );
```

💡 **Use Case**: Flexible data access for different use cases.

#### ✍️ Create RSS Feed

Generate an RSS 2.0 feed from your data:

```javascript
feedProps = {
    "version": "rss_2.0",
    "title": "My Blog",
    "link": "https://myblog.com",
    "description": "Latest posts from my blog",
    "publishedDate": now()
};

feedItems = [
    {
        "title": "First Post",
        "link": "https://myblog.com/post-1",
        "description": "This is my first blog post",
        "publishedDate": now(),
        "author": "john@example.com"
    },
    {
        "title": "Second Post",
        "link": "https://myblog.com/post-2",
        "description": "Another great post",
        "publishedDate": dateAdd( "d", -1, now() ),
        "author": "john@example.com"
    }
];

bx:feed
    action="create"
    properties=feedProps
    data=feedItems
    xmlVar="feedXml"
    outputFile="/var/www/feeds/blog.xml"
    overwrite="true";

println( "Feed created with #feedItems.size()# items" );
```

💡 **Use Case**: Expose your content as an RSS feed.

### Advanced Examples

#### 🎙️ Create iTunes Podcast Feed

Generate a podcast feed with iTunes extensions:

```javascript
podcastProps = {
    "version": "rss_2.0",
    "title": "My Podcast",
    "link": "https://mypodcast.com",
    "description": "Weekly tech discussions",
    "publishedDate": now(),
    "itunesAuthor": "John Doe",
    "itunesSubtitle": "Tech Talk",
    "itunesSummary": "In-depth discussions about technology",
    "itunesImage": "https://mypodcast.com/artwork.jpg",
    "itunesExplicit": "false",
    "itunesCategories": ["Technology", "Business"]
};

episodes = [
    {
        "title": "Episode 1: Getting Started",
        "link": "https://mypodcast.com/episode-1",
        "description": "Our first episode",
        "publishedDate": now(),
        "author": "john@example.com",
        "itunesTitle": "Getting Started with Tech",
        "itunesDuration": "00:45:30",
        "itunesEpisode": "1",
        "itunesSeason": "1",
        "itunesEpisodeType": "full",
        "enclosure": {
            "url": "https://mypodcast.com/episodes/episode-1.mp3",
            "type": "audio/mpeg",
            "length": "45000000"
        }
    }
];

bx:feed
    action="create"
    properties=podcastProps
    data=episodes
    outputFile="/var/www/feeds/podcast.xml"
    overwrite="true";
```

💡 **Use Case**: Create a podcast feed for Apple Podcasts, Spotify, etc.

#### 🔄 Read Multiple Feeds

Merge items from multiple feeds:

```javascript
sources = [
    "https://blog1.example.com/feed.xml",
    "https://blog2.example.com/feed.xml",
    "https://blog3.example.com/feed.xml"
];

bx:feed
    action="read"
    source=sources
    result="aggregated"
    maxItems="20";

println( "Aggregated #aggregated.items.size()# items from #sources.size()# feeds" );

// Items are automatically sorted by date
aggregated.items.each( function( item ) {
    println( "[#item.feed#] #item.title#" );
} );
```

💡 **Use Case**: Create a feed aggregator or news reader.

#### 📊 Create Feed from Query

Generate feed from database query results:

```javascript
// Get blog posts from database
posts = queryExecute(
    "SELECT title, url, content, published_date, author_email
     FROM blog_posts
     WHERE status = 'published'
     ORDER BY published_date DESC
     LIMIT 50",
    []
);

feedProps = {
    "version": "rss_2.0",
    "title": "Company Blog",
    "link": "https://company.com/blog",
    "description": "Latest news and updates"
};

// Map query columns to feed fields
columnMap = {
    "title": "title",
    "link": "url",
    "description": "content",
    "publishedDate": "published_date",
    "author": "author_email"
};

bx:feed
    action="create"
    properties=feedProps
    data=posts
    columnMap=columnMap
    outputFile="/var/www/public/feed.xml"
    overwrite="true";
```

💡 **Use Case**: Generate feeds from database content.

#### 🌐 Custom User Agent

Use custom User-Agent for HTTP requests:

```javascript
bx:feed
    action="read"
    source="https://api.example.com/feed.xml"
    result="feedData"
    userAgent="MyApp/2.0 (+https://myapp.com/bot)"
    timeout="30";
```

💡 **Use Case**: Identify your application to feed providers.

## 🎯 Extension Auto-Detection

### How It Works

The RSS module automatically detects and includes extension fields (iTunes podcast, Media RSS) when they are present in a feed, without requiring you to explicitly enable them.

**Auto-Detection Process**:

1. When no `itunes` or `mediaRss` flags are specified, the module starts with the iTunes reader
2. It checks the first item and channel for iTunes-specific fields
3. If no iTunes fields are found, it switches to the Media RSS reader
4. Extension fields are only included in the output when actually present

**Explicit Override**:

```javascript
// Force iTunes reader (even if feed has no iTunes fields)
bx:feed source="feed.xml" result="data" itunes="true";

// Force Media RSS reader (even if feed has iTunes fields)
bx:feed source="feed.xml" result="data" mediaRss="true";
```

### iTunes Podcast Fields

When iTunes podcast extensions are detected, these additional fields are available:

**Channel Level** (in `feedData.channel`):

* `itunesAuthor` - Podcast author
* `itunesSubtitle` - Podcast subtitle
* `itunesSummary` - Longer description
* `itunesImage` - Artwork URL
* `itunesExplicit` - Content rating (true/false)
* `itunesCategories` - Array of category strings
* `itunesOwnerName` - Owner name
* `itunesOwnerEmail` - Owner email

**Item Level** (in each `feedData.items[]`):

* `itunesTitle` - Episode title
* `itunesDuration` - Duration (HH:MM:SS format)
* `itunesEpisode` - Episode number
* `itunesSeason` - Season number
* `itunesEpisodeType` - Type (full, trailer, bonus)
* `itunesExplicit` - Episode content rating
* `itunesAuthor` - Episode author
* `itunesSummary` - Episode summary
* `itunesSubtitle` - Episode subtitle
* `itunesImage` - Episode artwork URL

### Media RSS Fields

When Media RSS extensions are detected, these additional fields are available:

**Item Level** (in each `feedData.items[]`):

* `mediaThumbnail` - Struct with:
  * `url` - Thumbnail image URL
  * `width` - Image width in pixels
  * `height` - Image height in pixels
  * `time` - Time offset (for video thumbnails)
* Additional Media RSS fields as available in the feed

## 🎯 Best Practices

### Performance

* ✅ **Cache feed data** - Cache parsed feeds to reduce HTTP requests
* ✅ **Use maxItems** - Limit items when you don't need the full feed
* ✅ **Set reasonable timeouts** - Default 60s is generous, adjust as needed
* ✅ **Handle failures gracefully** - Feeds can be temporarily unavailable
* ✅ **Validate feed URLs** - Check URLs before attempting to parse

### Feed Creation

* ✅ **Include all required fields** - title, link, description for channel and items
* ✅ **Use absolute URLs** - Ensure all links are fully qualified URLs
* ✅ **Set proper dates** - Use DateTime objects or valid date strings
* ✅ **Validate XML** - Test generated feeds with validators
* ✅ **Use escapeChars** - Enable when content contains HTML/special characters
* ✅ **Provide author info** - Include author/creator information for items

### iTunes Podcasts

* ✅ **Square artwork** - iTunes requires 1400x1400 to 3000x3000 pixels
* ✅ **Set explicit flag** - Always specify explicit/clean content rating
* ✅ **Include categories** - Help users discover your podcast
* ✅ **Add episode metadata** - Season, episode numbers, type (full/trailer/bonus)
* ✅ **Enclosure required** - Each episode must have an audio enclosure

### Security

* ✅ **Validate sources** - Only read from trusted feed URLs
* ✅ **Sanitize output** - Escape feed content when displaying in HTML
* ✅ **Set timeouts** - Prevent long-running operations
* ✅ **Handle errors** - Catch and log parsing failures
* ✅ **Use HTTPS** - Prefer HTTPS URLs for feed sources

## ❓ Troubleshooting

### Feed Reading Issues

**Problem**: Feed fails to parse or returns no items.

**Solutions**:

* ✅ Verify the URL is accessible (try in browser)
* ✅ Check if URL requires authentication
* ✅ Increase timeout for slow-loading feeds
* ✅ Verify feed is valid RSS/Atom (use feed validator)
* ✅ Check for network/firewall issues
* ✅ Review BoxLang logs for parsing errors

### Extension Fields Not Appearing

**Problem**: iTunes or Media RSS fields are missing.

**Solutions**:

* ✅ Verify the feed actually contains extension fields (view XML)
* ✅ Check that extensions are in correct namespace
* ✅ Try forcing reader: `itunes="true"` or `mediaRss="true"`
* ✅ Inspect raw XML with `xmlVar` attribute
* ✅ Validate feed with podcast/media RSS validators

### Feed Creation Problems

**Problem**: Generated feed is invalid or won't display.

**Solutions**:

* ✅ Validate feed XML with online validator (W3C, Podbase)
* ✅ Ensure all required fields are present (title, link, description)
* ✅ Use absolute URLs, not relative paths
* ✅ Check date formats are valid DateTime objects
* ✅ Enable `escapeChars="true"` if content has HTML
* ✅ Verify enclosure URLs are accessible (for podcasts)

### File Output Issues

**Problem**: Feed won't save to file.

**Solutions**:

* ✅ Verify output directory exists and is writable
* ✅ Check file permissions on the target path
* ✅ Enable `overwrite="true"` to replace existing files
* ✅ Use absolute file paths, not relative
* ✅ Ensure sufficient disk space

## 🔗 Resources

* [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
* [Atom 1.0 Specification](https://datatracker.ietf.org/doc/html/rfc4287)
* [iTunes Podcast RSS Tags](https://help.apple.com/itc/podcasts_connect/#/itcb54353390)
* [Media RSS Specification](http://www.rssboard.org/media-rss)
* [Feed Validator](https://validator.w3.org/feed/)
* [Podcast Validator](https://podba.se/validate/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/modularity/rss.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.