• Stars
    star
    451
  • Rank 96,968 (Top 2 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created about 13 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

An easy-to-use rss plugin for jquery with templating.

jquery.rss Build Status

This plugin can be used to read a RSS feed and transform it into a custom piece of HTML.

πŸ’₯ Deprecation warning πŸ’₯

Please note this plugin is no longer maintained. The related backend server was also taken down. You can still use it but would have to host the Feedr service on your own.

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(
  // You can either provide a single feed URL or a list of URLs (via an array)
  "http://feeds.feedburner.com/premiumpixels",
  {
    // how many entries do you want?
    // default: 4
    // valid values: any integer
    limit: 10,

    // want to offset results being displayed?
    // default: false
    // valid values: any integer
    offsetStart: false, // offset start point
    offsetEnd: false, // offset end point

    // will request the API via https
    // default: false
    // valid values: false, true
    ssl: true,

    // which server should be requested for feed parsing
    // the server implementation is here: https://github.com/sdepold/feedr
    // default: feedrapp.info
    // valid values: any string
    host: "my-own-feedr-instance.com",

    // option to seldomly render ads
    // ads help covering the costs for the feedrapp server hosting and future improvements
    // default: true
    // valid values: false, true
    support: false,

    // outer template for the html transformation
    // default: "<ul>{entries}</ul>"
    // valid values: any string
    layoutTemplate: "<div class='feed-container'>{entries}</div>",

    // inner template for each entry
    // default: '<li><a href="{url}">[{author}@{date}] {title}</a><br/>{shortBodyPlain}</li>'
    // valid values: any string
    entryTemplate: "<p>{title}</p>",

    // additional token definition for in-template-usage
    // default: {}
    // valid values: any object/hash
    tokens: {
      foo: "bar",
      bar: function(entry, tokens) {
        return entry.title;
      }
    },

    // formats the date with moment.js (optional)
    // default: 'dddd MMM Do'
    // valid values: see http://momentjs.com/docs/#/displaying/
    dateFormat: "MMMM Do, YYYY",

    // localizes the date with moment.js (optional)
    // default: 'en'
    dateLocale: "de",

    // Defines the format which is used for the feed.
    // Default: null (utf8)
    // valid values: https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
    encoding: "ISO-8859-1",

    // Defined the order of the feed's entries.
    // Default: undefined (keeps the order of the original feed)
    // valid values: All entry properties; title, link, content, contentSnippet, publishedDate, categories, author, thumbnail
    // Order can be reversed by prefixing a dash (-)
    order: "-publishedDate",

    // formats the date in whatever manner you choose. (optional)
    // this function should return your formatted date.
    // this is useful if you want to format dates without moment.js.
    // if you don't use moment.js and don't define a dateFormatFunction, the dates will
    // not be formatted; they will appear exactly as the RSS feed gives them to you.
    dateFormatFunction: function(date) {},

    // a callback, which gets triggered when an error occurs
    // default: function() { throw new Error("jQuery RSS: url don't link to RSS-Feed") }
    error: function() {},

    // a callback, which gets triggered when everything was loaded successfully
    // this is an alternative to the next parameter (callback function)
    // default: function(){}
    success: function() {},

    // a callback, which gets triggered once data was received but before the rendering.
    // this can be useful when you need to remove a spinner or something similar
    onData: function() {}
  },

  // callback function
  // called after feeds are successfully loaded and after animations are done
  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:

<!-- layoutTemplate: -->
"<outer-html>{entries}</outer-html>"

<!-- entryTemplate: -->
"<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

More Repositories

1

node-imageable

On-demand image manipulation middleware for express and connect.
JavaScript
168
star
2

rsvm

Rust Version Manager
Shell
128
star
3

feedrapp

A service for parsing RSS and Atom feeds.
JavaScript
44
star
4

node-imageable-server

On-demand image manipulation server in node.js
JavaScript
40
star
5

sequel-paranoid

A plugin for the Ruby ORM Sequel, that allows soft deletion of database entries.
Ruby
28
star
6

vanilla-rss

An easy-to-use vanilla JavaScript library to read and render RSS feeds.
JavaScript
22
star
7

octo.erl

Erlang wrapper for the Github API.
Erlang
16
star
8

sequel-bit_fields

A sequel plugin that allows the use of integer columns to represent a big number of flags.
Ruby
13
star
9

connect-form

urlencoded / multipart form parsing middleware for Connect
JavaScript
11
star
10

asteroids-workshop

Building Asteroids in JavaScript
JavaScript
7
star
11

release-tools

A tiny collection of release helpers.
JavaScript
7
star
12

jquery.google-search

Execute google searches within your client-side javascript
JavaScript
6
star
13

cubi

JavaScript
6
star
14

noegnud

Entry for 2019's js13kGames
JavaScript
5
star
15

contentful-ghost-importer

A CLI that imports data from ghost to contentful.
JavaScript
5
star
16

contentful_blog

Demo project that shows how to use Contentful as backend for a blog.
Ruby
5
star
17

jquery.skeleton

A skeleton builder for jquery plugins. Included is BusterJS for testing and Google Closure Compiler for minification.
JavaScript
5
star
18

simpleSli.de

a jQuery slideshow plugin
4
star
19

Autocompleter.Local.MultiContent

Extension of the script.aculo.us Autocompleter.Loca for connecting a selection with a data set.
JavaScript
3
star
20

gulp-busterjs

BusterJS runner for gulp
JavaScript
3
star
21

myspaceid-sdk

Improved copy of the myspaceid-ruby-sdk
Ruby
3
star
22

node-nmagick

A node wrapper for ImageMagick
3
star
23

node-security-brown-bag

Scenarios for the brown bag session about secure node applications
JavaScript
3
star
24

bugs-bunny

A round-robin approach for daily bug cleanup.
JavaScript
2
star
25

express-view-helpers

JavaScript
2
star
26

kollekt-node

An experiment about udp throughput in node.js.
JavaScript
2
star
27

jquery.char-counter

A jQuery plugin for counting and limiting the characters in a textarea.
JavaScript
2
star
28

node-aws

AWS seed for node.js
JavaScript
2
star
29

js-basics-tdd

JavaScript
2
star
30

PixelCloud-Client-Node

JavaScript
2
star
31

NoSpec

Spec framework for node.js
JavaScript
2
star
32

javascript-basics

Learning materials for getting started with JavaScript
JavaScript
2
star
33

nodeable

Prototype inspired helper package for node.js
JavaScript
2
star
34

identify.js

Parse identify (image-magick) output into JS object.
2
star
35

node-image-test

1
star
36

dashboard

JavaScript
1
star
37

com.depold.helpers

JavaHelpers
Java
1
star
38

buster-user-agent-parser

JavaScript
1
star
39

pivotal-time-travel

JavaScript
1
star
40

pixel-quest

MMORPG for js13kgames.
JavaScript
1
star
41

gulp-markdown-code-blocks

Gulp task for running markdown-code-blocks.
JavaScript
1
star
42

jaspin-test-repo

a test repo for jaspin
1
star
43

npm-runner

Shell
1
star
44

js-basics-graphql

JavaScript
1
star
45

PixelCloud-Client-Ruby

1
star
46

file-usage-analyzer

finds unused files in a directory according to a nginx log file
1
star
47

jaspin

Node.JS based Dropbox inspired solution for inhouse networks.
1
star
48

buster-test

JavaScript
1
star
49

jquery.templar

A super simple and dynamic templating engine.
JavaScript
1
star
50

js-basics-cookies-sessions

How to manage sessions and cookies in JavaScript
JavaScript
1
star
51

workshop-docker-k8s

Source code for our Docker + Kubernetes workshop
JavaScript
1
star
52

delete-duplicates

Deletion script that interprets Synology's duplication reports and deletes the duplicate files.
JavaScript
1
star
53

rateable_attributes

A reimplementation of acts_as_rateable but with support for multiple attributes for a specific model.
Ruby
1
star