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.

Quick Note

Not all of this works yet. This is just a prerelease. README driven development FTW!

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 an optional 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.

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.