jQuery Feeds - RSS aggregator for your site

Use the jQuery Feeds Plugin to retrieve and display multiple RSS feeds' entries in chronological order.

Features

• Fetches multiple feeds
• Entries are combined and displayed in chronological order
• Fully customizable markup
• Fully customizable loader
• Manipulate entries' properties
• Uses the Google Feed API to retrieve feeds

Basic usage

Download the production version or the development version and add it to your site:

<script src="jquery.js"></script>
<script src="jquery.feeds.js"></script>

And attach some feeds to a container:

$('#container').feeds({
	feeds: {
		feed1: 'http://url/to/rss/feed',
		feed2: 'http://url/to/another/rss/feed'
		// key: 'url', ...
	}
});

The feeds' keys (i.e. feed1 and feed2 in the example) are used to identify the source of the entries. You can use any alphanum string as a key but try to keep them short and descriptive (e.g. google, jquery, smashingmag).

---

You can also set the max number of items for each feed by using the max option:

$('#container').feeds({
	feeds: {
		// Your feeds ...
	},
    max: 3
});

By default max is set to -1, which means it should fetch the maximum number of entries supported by the Google Feed API (which is 100).

Note: the more feeds you load and the more entries you get the longer it will take the plugin to load them.

Manipulating entries

You can manipulate the properties of each entry by implementing the preprocess callback. Say you want to modify the entries' publishedDate format (inside the callback this corresponds to the current entry):

$('#container').feeds({
    feeds: {
        // Your feeds ...
    },
    preprocess: function ( feed ) {
        // Change the publishedDate format from UTC to dd-mm-yyyy
        var date = new Date(this.publishedDate);
        var pieces = [date.getDate(), date.getMonth(), date.getFullYear()]
        this.publishedDate = pieces.join('-');
    }
});

Tip: you can use js libraries such as moment.js to format your dates.

Available properties are:

• title
• publishedDate
• content
• contentSnippet (< 120 characters, no html tags)
• link
• mediaGroup
• categories
• source (the feed identifier, added by the plugin)
• feedUrl (the url of the rss feed)
• feedTitle (the title of the feed)
• feedLink (the url of the HTML version of the feed)
• feedDescription (the feed description)
• feedAuthor (the feed author)

Refer to the Google developer's guide for more information.

onComplete callback

By implementing the onComplete callback you can manipulate the container after the entries are rendered. Say you want to change all the anchors' target value to _blank (inside the callback this corresponds to the container):

$('#container').feeds({
    feeds: {
        // Your feeds ...
    },
    onComplete: function (entries) {
        $(this).find('a').attr('target', '_blank');
    }
});

Templating

You can change the way the entries are rendered. Just pass a regular HTML string with the entries' property names sorrounded by double curly brackets (e.g. {{title}}) to the entryTemplate option.

$('#container').feeds({
    feeds: {
        // Your feeds ...
    },
    entryTemplate:  '<article>' +
                        '<header>' +
                            '<h1><a href="{{link}}">{{title}}</a></h1>' +
                            '<p>{{publishedDate}}</p>' +
                        '</header>' +
                        '<div>{{contentSnippet}}</div>' +
                        '<footer>' +
                            '<p>via: <a href="{{feedLink}}">{{feedTitle}}</a></p>' +
                        '</footer>' +
                    '</article>'
    }
});

Note: At this moment the properties mediaGroup and categories are not available inside the template.

---

You can change the template of the loader by passing a HTML string to the loadingTemplate option:

$('#container').feeds({
    feeds: {
        // Your feeds ...
    },
    loadingTemplate: '<p>Fetching entries, please wait.</p>'
});

Options

// Feeds to retrieve
feeds: {
    // identifier: url, ...
},

// Maximum number of entries to fetch per feed, -1 for maximum available
max: -1,

// Called when all entries are rendered
onComplete: function( entries ) { },

// Called for each entry
preprocess: function( feed ) { },

// Template injected to container while feeds are loaded
loadingTemplate: '<p class="feeds-loader">Loading entries ...</p>',

// Template used to render each entry
entryTemplate:	'<div class="feeds-entry feeds-source-{{source}}">' + 
				'<a class="feed-entry-title" target="_blank" href="{{link}}" title="{{title}}">{{title}}</a>' +
				'<div class="feed-entry-date">{{publishedDate}}</div>' + 
				'<div class="feed-entry-content">{{contentSnippet}}</div>' + 
				'</div>'

License

Copyright (c) 2012 Camilo Aguilar

Licensed under the MIT and GPL licenses.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

Please don't edit files in the dist subdirectory as they are generated via grunt. You'll find source code in the src subdirectory!