SocialFeed.js

Easily create a feed with your latest interactions on different social media. SocialFeed.js was inspired by the compiled feed on http://gnab.org/, and was designed to be very modular and plugable.

At this moment the following features are implemented:

Github
Vimeo
Youtube Video Uploads
Disqus
RSS Feeds
Delicious

However, extending SocialFeed.js is a simple task. See Extending SocialFeed.js for more information.

See SocialFeed.js in use at my personal site. For a complete example two SocialFeeds, Require.JS, extending modules, using with Handlebar, etc see the source code for http://mikaelb.net/ at https://github.com/mikaelbr/mikaelbr.github.io.

Installation & Usage

Requirements

jQuery

Install

Manually Download

Installing SocialFeed.js is simple. Just download the raw JavaScript file and optionally the CSS file.

Using Bower

bower install socialfeed

Import all dependancies and the SocialFeed.js code.

<html>
  <head>
    <title>SocialFeed.js</title>
    <link rel="stylesheet" type="text/css" href="socialfeed.min.css">
  </head>
  <body>
    <div id="socialfeed"></div>
    <!-- Import Scripts -->
    <script src="components/jquery/jquery.js"></script>
    <script src="components/socialfeed/socialfeed.min.js"></script>
  </body>
</html>

Usage

SocialFeed.js is very modular, and every different social site is implemented as it's own module. By default, no social site is added, you have to explicitly add every social function. This to be as customizable as possible.

SocialFeed has a simple constructor. If you only pass it a jQuery event, all module items will be rendered, but you can restrict this by passing the count-option. Even if count is 5, all module items are fetched from the different APIs, but only the first 5 are rendered.

Constructor:

new SocialFeed({
    el: '#foo' // selector or jQuery object for wrapper element.
  , count: 10 // defaults to 1000
  , offset: 10 // defaults to 0. Start rendering from offset.
});

If you set offset to N, the first N items won't show.

Shortcut:

new SocialFeed('#foo');

Let's see how we can add Github and Delicious as a part of the feed (using the template as defined above.):

var sfeed = new SocialFeed({
                el: $("#socialfeed")
              , count: 10
            })
            .addModule(new SocialFeed.Modules.Github('mikaelbr')) // argument: username
            .addModule(new SocialFeed.Modules.Delicious('mikaelbr')) // argument: username
            .start();

This will populate the #socialfeed element when data from both of the social sites are loaded.

Note, if you omit the start(). Nothing will happen. SocialFeed() waits until explicitly told to initiate.

Disqus requires a public API key to access data, so we have an extra argument when adding the module:

var sfeed = new SocialFeed($("#socialfeed"))
                  .addModule(new SocialFeed.Modules.Disqus('mikaelbr', 'OEMdBc63xd0MZGKiVV5JgExTqdO7OSYkjgv613LJ8Py89y44pcoSKeBrelZjepVS'))
                  .start();

Built in Modules

Every built in module is under the namespace SocialFeed.Modules.

Module	Description
`Github(username[, hideEvents = None])`	Shows all your events on github, including create repositories, starring, forking, pull requesting, pushing.
`Vimeo(username[, hideEvents = None])`	Shows your activity on Vimeo, including like, add comment and upload.
`YouTubeUploads(username[, count = 10])`	Shows uploaded YouTube videos. Sorted by updated time, not published.
`Disqus(username, public_api_key)`	Show your public comments made on Disqus.
`Delicious(username)`	Shows your shared bookmarks.
`RSS(rssUrl, count)`	Fetches the `count` number of posts from your RSS feed at `rssUrl`

API

SocialFeed exposes several functions and events.

Methods

Method	Description
`.start()`	Initiate SocialFeed.js.
`.reload()`	Reload content. Fetch new data from social channels.
`.loadNumEntries(number)`	Load the next `number` items, if more to load.
`.nextBulk()`	Loads the next bulk of items. If constructor initiated with count 10, load next 10.
`.addModule(Module)`	Add a new module to the feed.
`.on(eventType, callback)`	Listen for an event on the feed. See Events

Events

To listen for a event use:

var sfeed = new SocialFeed($("#socialfeed"));
sfeed.on('eventName', function() { /* body */ });

or for Modules:

var mod = new SocialFeed.Modules.Github('mikaelbr');
mod.on('eventName', function() { /* body */ });

Events for a feed

Event Type	Passed arguments	Description
`start`	None	Triggered when `.start()` is called
`reload`	None	Triggered when `.reload()` is called
`addModule`	Module	Triggered when module is added
`moduleAdded`	Module	Triggered when module is added and fetched
`preFetch`	None	Triggered before fetching data from modules.
`postFetch`	AllModules[]	Triggered when all modules are fetched
`dataReady`	SortedHTMLList, AllModules[]	Triggered when all data is generated as HTML.
`rendered`	SortedHTMLList{from _offset, to count}	Triggered when rendering new items. Passes the sorted HTML list with the rendered entities.
`nextBulk`	None	Triggered when `.nextBulk()` is called.
`loadNumEntries`	Number	Triggered when `.loadNumEntries()` is called.
`error`	Module, jqXHR, AjaxOptions	Triggered when error fetching some module data.

Events for a module

Event Type	Passed arguments	Description
`error`	Module, jqXHR, AjaxOptions	Triggered on error fetching module data.
`fetched`	Module, jqXHR, AjaxOptions	Triggered when data for module is fetched.

Extending SocialFeed.js

Adding new Social sites.

You can easily add new modules to SocialFeed.js. See code for example:

var NewModule = SocialFeed.Modules.extend({
  init: function(ident, count) {
    // Constructor. Omit to use default one with only "ident".
    this.ident = ident;
    this.count = count;
  }

  , url: function () {
    // URL can also be a string, but having it as a function
    // allows us to pass the ident value. ident is the first argument
    // to the module constructor.
    return 'http://path.to.some/document.json?user=' + this.ident + '&count=' + this.count;
  }

  , parse: function (resp) {
    // resp is the response from the AJAX call. Return a list of entities.
    return resp.result;
  }

  , orderBy: function (item) {
    // orderBy must be implemented. Return a numeric value to sort by.
    // item is an entity from the results.
    return -(new Date(item.created_at)).getTime();
  }

  , render: function (item) {
    // Return HTML representation of an entity.
    return '<p>' + item.message + '</p>';
  }
});

var sfeed = new SocialFeed($("#socialfeed"))
                  .addModule(new NewModule('mikaelbr', 10))
                  .start();

Extend/Alter behaviour of existing module

You can change original behaviour of the pre-defined modules by extending them and overwriting their methods.

Example:

var Disqus = SocialFeed.Modules.Disqus.extend({
  render: function (item) {
    return '<p>Allways show this message!</p>';
  }
});

var sfeed = new SocialFeed($("#socialfeed"))
                  .addModule(new Disqus('mikaelbr', 'OEMdBc63xd0MZGKiVV5JgExTqdO7OSYkjgv613LJ8Py89y44pcoSKeBrelZjepVS'))
                  .start();

Examples

See examples for more code snippets and help.

Changelog

v0.3.7: Added Vimeo as a module.
v0.3.6-2: Simplified the constructor, to take a element selector instead of jQuery element.
v0.3.6-1: Event type clean up.
v0.3.6: Added AMD definition.
v0.3.5: Major bugfix: Browserify now wraps scripts in a SIAF. SocialFeed.js no longer destroys everything it touches.
v0.3.4:
- Added RSS Module
- Added ES5 Shims
- Bugfix: Reloading fixed.

Contribute

SocialFeed.js is very open for contributions. If you have built a module you think should be built in or find a bug, please send a pull request.

Also feel free to post issues at https://github.com/mikaelbr/SocialFeed.js/issues.

Contribution guide

To set-up SocialFeed.js to run locally, do the following:

$ git clone git://github.com/mikaelbr/SocialFeed.js.git
$ cd SocialFeed.js/

Install dependencies

$ make deps

This will install both the client side deps and browser side.

Build

After making your changes, bundle a new version of SocialFeed.js.

From root, run

make bundle

This will build the JavaScript, compile LESS files and minify both. You can find the bundled files in the root directory.

mikaelbr/SocialFeed.js

mikaelbr

Reviews

Repository Details