This plugin can be used to read a RSS feed and transform it into a custom piece of HTML.
Alternatives
A vanilla JavaScript version of this library can be found here: Vanilla RSS.
This plugin uses Feedr, a backend server that parses and converts RSS feeds into its JSON representation. The server was built as a drop-in replacement for Google's former Feed API.
Support
Since version 3.4.0 of jquery.rss, users have the chance to support funding future developments and
covering the costs for the hosting of jquery.rss' respective server side companion app feedr.
Every once in a while supporters will get affiliate links instead of one of the feed's entries.
If you are not interested in supporting the authors of the plugin, then you can easily opt-out of it by setting the respective
support
option. See below for further details.
Thanks in advance!
Installation
Through npm:
$ npm install jquery
$ npm install jquery-rss
const $ = require('jquery');
require('jquery-rss); // This will add the plugin to the jQuery namespace
Through cdnjs:
<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-rss/3.3.0/jquery.rss.min.js"></script>
Setup
<!DOCTYPE html>
<html>
<head>
<title>jquery.rss example</title>
<script src="lib/jquery-1.6.4.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.8.4/moment.min.js"></script>
<script src="dist/jquery.rss.min.js"></script>
<script>
jQuery(function($) {
$("#rss-feeds").rss("http://feeds.feedburner.com/premiumpixels");
});
</script>
</head>
<body>
<div id="rss-feeds"></div>
</body>
</html>
Demo link for above code: http://embed.plnkr.co/WQRoCYLld162uplnz1rc/preview
Note: Moment.js is optional. If you include it, jquery.rss will use it to format dates.
If you do not want to include Moment.js, you may opt for providing your own date formatting function, or for not formatting dates at all.
Options
$("#rss-feeds").rss(
"http://feeds.feedburner.com/premiumpixels",
{
limit: 10,
offsetStart: false,
offsetEnd: false,
ssl: true,
host: "my-own-feedr-instance.com",
support: false,
layoutTemplate: "<div class='feed-container'>{entries}</div>",
entryTemplate: "<p>{title}</p>",
tokens: {
foo: "bar",
bar: function(entry, tokens) {
return entry.title;
}
},
dateFormat: "MMMM Do, YYYY",
dateLocale: "de",
encoding: "ISO-8859-1",
order: "-publishedDate",
dateFormatFunction: function(date) {},
error: function() {},
success: function() {},
onData: function() {}
},
function callback() {}
);
Note about the host option
Since version 3.0.0 the plugin is no longer using the Google Feed API but a drop-in replacement called feedr. That server is currently running on Heroku and might have some downtimes, interruptions or unexpected issues. While I will try to keep those problems as rare as possible, it can totally happen from time to time. I might move the service to some other provide or even improve the infrastructure.
If you don't want to rely on the provided server and instead run your own version, you can just download feedr, install the dependencies and run it. As written above, you can specify the host which is used to parse the feeds with the host
option.
Templating
As seen in the options, you can specify a template in order to transform the json objects into HTML. In order to that, you can either define the outer template (which describes the html around the entries) or the entry template (which describes the html of an entry).
The basic format of those templates are:
"<outer-html>{entries}</outer-html>"
"<any-html>{token1}{token2}</any-html>"
So, let's say you have specified a limit of 2, using the upper pseudo html. This will result in the following:
<outer-html>
<any-html>{token1}{token2}</any-html>
<any-html>{token1}{token2}</any-html>
</outer-html>
There are some predefined tokens:
- url: the url to the post
- author: the author of the post
- date: the publishing date
- title: the title of the post
- body: the complete content of the post
- shortBody: the shortened content of the post
- bodyPlain: the complete content of the post without html
- shortBodyPlain: the shortened content of the post without html
- teaserImage: the first image in the post's body
- teaserImageUrl: the url of the first image in the post's body
- index: the index of the current entry
- totalEntries: the total count of the entries
- feed: contains high level information of the feed (e.g. title of the website)
You can also define custom tokens using the tokens
option:
$("#foo").rss(url, {
entryTemplate: "{dynamic}, {static}, {re-use}",
tokens: {
dynamic: function(entry, tokens) {
return "dynamic-stuff: " + entry.title;
},
"re-use": function(entry, tokens) {
return encodeURIComponent(tokens.teaserImageUrl);
},
static: "static"
}
});
Please make sure to NOT define infinite loops. The following example is really BAD:
$('#foo').rss(url, {
entryTemplate: "{loop}",
tokens: {
whoops: function(entry, tokens) { return tokens.loop() }
loop: function(entry, tokens) { return tokens.whoops() }
}
})
Here is a real-world example:
$("#foo").rss(url, {
layoutTemplate: "<table><tr><th>Title</th></tr>{entries}</table>",
entryTemplate: "<tr><td>{title}</td></tr>"
});
Filtering
The plugin also allows you to filter specific entries in order to only print them:
$("#foo").rss(url, {
limit: 100,
filterLimit: 10,
filter: function(entry, tokens) {
return tokens.title.indexOf("my filter") > -1;
}
});
This will request 100 entries via the Feed API and renders the first 10 matching entries.
Testing
The test suite is using BusterJS. In order to successfully run the tests you will need phantomjs.
If that is installed you only have to run npm test
.
Authors/Contributors