Narrator¶ ↑

<img src=“https://badge.fury.io/rb/narrator.png” alt=“Gem Version” /> <img src=“https://travis-ci.org/jweakley/narrator.png?branch=master” alt=“Build Status” /> <img src=“https://gemnasium.com/jweakley/narrator.png” alt=“Dependency Status” /> <img src=“https://coveralls.io/repos/jweakley/narrator/badge.png” alt=“Coverage Status” />

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).

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

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

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.

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.

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.

Automagical Narration

class ArticlesController < ApplicationController
  narrate_resource

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

• Coming Soon

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`.

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.