Narrator <img src=“https://secure.travis-ci.org/jweakley/narrator.png?branch=master” />

Narrator is an activity library for Ruby on Rails that allow you to track what is happening on models and later use to build an activity or news stream. Tracking is done at the controller level with a simple narrate_resource command (which was inspired by the simplicity of Ryan Bates’ CanCan gem).

Installation

In Rails 3 add this line to your application’s Gemfile and run the bundle command.

gem "narrator"

Once you have the Narrator gem installed you will need to run the generator:

rails generate narrator:install

This generator will add the migrations needed for the activity tracking. Currently this only works for ActiveRecord.

After the migration has been added you will need to migrate your database to run the new migration.

rake db:migrate

Getting Started

Narrator expects a current_user method to exist in the controller. First, set up some authentication (such as Authlogic or Devise).

1. Mark a Model as Narratable

Any model that we would like to have tracked by narrator needs to have narratable_model added to it.

class Article
  narratable_model
  ...
end

See Narrated Model for more details and features.

1. Mark a Model as Narratable

Any model that we would like to create activites (normally just User) needs to have narratable_actor added to it.

class User
  narratable_actor
  ...
end

See Narrated Actor for more details and features.

3. Narrate the Model’s activities from the controller

The narrate method in the controller will narrate something important.

def create
  ...
  @article = Article.new(params[:article])
  ...
  narrate @article if @article.save
  ....
end

In this example, if the article is successfully saved, an activity gets logged for the article.

See Tracked Activities for more details and features with tracked activities.

Future Features

Automagical Narration

class ArticlesController < ApplicationController
  narrate_resource

  def create
    ...
    respond_with @article
    # @article is automaticly tracked if it is valid
  end
end

Wiki Docs

• Coming Soon

Questions or Problems?

If you have any issues with Narrator which you cannot find the answer in the documentation, please add an issue on GitHub. Alternatively you can fork the project and send a pull request (limit one high five and/or fist bump per contribution).

Please ensure the tests are passing by running ‘bundle` and `rake`.

Special Thanks

Narrator was inspired in part by Ryan Bates railcasts and CanCan.

Internet high fives and/or fist bumps to the Narrator contributors.

This gem is created by Joe Weakley and is under the MIT License.