EXTRA! EXTRA! READ ALL ABOUT IT!

Need to add a news feed to your application? EXTRA! EXTRA! is just the Gem for you! This is a common need for many social applications. EXTRA! EXTRA! uses MongoDB to give you super fast, super convenient feeds.

Oh, and when I say “news feed”, think “activity feed,” not RSS. The stuff that’s on the dashboard of every social app ever.

Install

EXTRA! EXTRA! will be distributed via Rubygems, so just

$ gem install extraextra

and you’ll be reading the news in no time!

Source

The source of EXTRA! EXTRA! is on GitHub, and can be found here:

http://github.com/steveklabnik/extraextra

It can be cloned via

$ git clone git://github.com/steveklabnik/extraextra.git

Requirements

Ruby 1.9: Sorry for you 1.8 people, 1.9 is the current version of Ruby. I test with 1.9.2.
mongo: If you’re going to use MongoDB…

Usage

The first thing you’ll need to do is configure EXTRA! EXTRA! to connect to your MongoDB:

Extra::Extra.source :host => "localhost", :port => "1337"

To record something newsworthy, just do this:

$ Extra::Extra::! :breaking, user, "has just done something awesome!"

To find out what interesting things a particular user has done:

$ Extra::Extra.read_all_about_it user

$ Extra::Extra.the_scoop user

This returns an array of Extra objects. To find out more about a particular Extra:

$ extra = Extra::Extra::! :sports, user, "hit a home run!"

$ extra.who
 => #<User:0x0000010089ea80> 
$ extra.what
 => "hit a home run"
$ extra.where
 => nil # currently undecided
$ extra.when
 => 1283311813 
$ extra.how
 => nil # currently undecided
$ extra.to_s
 => "Steve hit a home run"

Two things: ‘who’ instantiates the object by sending it the find message, passing an id. So that has to be defined in your user object. Secondly, the name in to_s comes from user#username. If you use something else… I’ll provide a way to override these eventually.

To only see breaking news:

$ Extra::Extra.breaking_news

This will filter out only the news in the ‘breaking’ category. You can pass an optional user:

$ Extra::Extra.breaking_news user

This will only show breaking news for this specific user.

To find out what interesting things a users’s friends have done:

$ Extra::Extra.scope_the_scene user

This also takes a user, just like *_news.

To define what who you’re friends with, make a method on your user model named my_peeps. For a (hypothetical) example:

class User
  def my_peeps
    User.friends.collect(&:id)
  end
end

The my_peeps method should return an Array of ids. This method will be called during scope_the_scene to determine what results get returned.

Roadmap

1.0.0 was the release that implements the most basic functionality that I needed. I plan on integrating EXTRA! EXTRA! into a few of my projects, and seeing what could be useful. But here’s a few things that are rolling around in my brain:

Limits on most queries. This’ll probably get added real quick.
Generators for Rails that cover common use cases.
Possibly allowing for extra metadata to be attached to each Extra.

We’ll just roll with the punches. I’d love to hear some ideas.

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.