"rss" Macro
Reference
Description
The rss Macro displays the latest entries of an RSS feed in a wiki page, each one as a link to the entry.
In the Macro list of the editors it appears as "RSS", in the "Content" category. It is built on the "box" Macro: by default the entries are framed in a box topped by the feed's title. For a step-by-step procedure, see Display an RSS Feed in a Page.
Usage
{{rss feed="https://example.org/feed.rss"/}}The Macro is standalone only: it cannot be used inside a paragraph. Its content is optional; when present, it is parsed as wiki content and displayed in the box, between the feed's title and its entries.
The feed must be reachable from the XWiki server, over HTTP or HTTPS, and the server must start answering within 5 seconds.
RSS Display 15.7+ The XWiki server only fetches feeds hosted on public addresses: a URL pointing to the XWiki server itself or to a private network, such as an intranet, is refused, and so is any URL the feed redirects to. Retrieving the feed must also take less than 10 seconds, and the feed must be smaller than 5 MB.
The content of each entry, displayed with content="true", is HTML from a remote site: it is cleaned in restricted mode before being displayed, which removes scripts and other active content.
Output and CSS Classes
The output carries the following CSS classes, which a skin or a skin extension can style.
| Class | Element |
|---|---|
| rssfeed | The element containing the whole output, with or without decoration. |
| rsschanneltitle | The feed's title, a link to the feed's site followed by an RSS icon. Only with decoration="true". |
| rssitemtitle | The title of each entry, a link to the entry. |
| rssitemdescription | The content of each entry. Only with content="true". |
Errors
When the feed cannot be read, the Macro displays an error instead of the feed.
| Message | Cause |
|---|---|
| The required 'feed' parameter is missing | feed is empty. |
| Unsupported protocol for the feed URL [<url>], only http and https are allowed | RSS Display 15.7+ The URL, or a URL it redirects to, is neither an http nor an https URL. |
| Access to [<url>] is not allowed | RSS Display 15.7+ The URL, or a URL it redirects to, points to the XWiki server itself or to a private network. |
| Too many redirects when trying to reach [<url>] | RSS Display 15.7+ The URL redirects more than 5 times. |
| Failed to retrieve the feed from [<url>] | RSS Display 15.7+ The URL cannot be fetched (for example an unknown host, a 404 or no answer within 5 seconds), retrieving it takes more than 10 seconds, the feed is larger than 5 MB, or what it returns is not a feed. The exact cause is logged at DEBUG level by the org.xwiki.contrib.rssdisplay.internal.DefaultRomeFeedFactory logger. |
| No feed found at [<url>] | The URL returned no feed. |
RSS Display <15.7 A server that did not answer within 5 seconds was reported as Connection timeout when trying to reach [<url>], and the other failures as Error processing [<url>] : <cause>.
Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| feed | yes | a URL | none | The URL of the RSS feed. |
| count | no | a positive integer | 10 | The maximum number of entries to display. |
| content | no | true, false | false | When true, displays the content of each entry under its title. |
| image | no | true, false | false | When true and the feed declares an image, displays that image at the top of the box. |
| decoration | no | true, false | true | When true, frames the entries in a box topped by the feed's title and an RSS icon. When false, displays only the list of entries. |
| width | no | a CSS width, in px or % | the full width of the page | The width of the box. |
| title | no | wiki content | none | Displayed at the top of the box, above the feed's title. |
| cssClass | no | a space-separated list of CSS class names | none | Added to the classes of the box, so this feed can be styled on its own. |
| encoding | no | a character encoding name, such as UTF-8 | guessed | The encoding used to read the feed. By default it is guessed from the feed's byte order mark and XML declaration; set it when the feed displays garbled characters. |
Examples
Entries Without Decoration
{{rss feed="https://forum.xwiki.org/latest.rss" count="3" decoration="false"/}}
Feed Image and Entry Content in a Narrower Box
{{rss feed="https://www.flickr.com/services/feeds/photos_public.gne?format=rss_200&tags=xwiki" image="true" content="true" width="50%" count="1"/}}
A Custom Title and an Introduction
{{rss feed="https://forum.xwiki.org/latest.rss" count="5" title="**XWiki forum**" cssClass="news"}}
The latest topics of the XWiki forum.
{{/rss}}
