= ActsAsEventable

This "acts_as" module makes it extremely simple to add events to a model that will be stored in a table for later querying or reporting on. The events have an event type, which also corresponds to how the event is triggered.

An example of acts_as_eventable's use would be if you needed to track every time a particular object was viewed on your site. You could setup and event type of 'view', then simply call my_object.view from the the controller's show method (assuming a restful design is in play, of course). This would trigger an entry in the event table, noting the object that was viewed.

The events can be anything you want, and you can call the methods from anywhere. It works whether the object is a first-class Active Record object, or an associated object (via has_xxx or belongs_to).

This is the initial commit, and I have not written any tests or comments in the code as of yet. Soon come, mon!

== Install

Acts As Eventable is hosted on github. It may be installed as a gem or a plugin. To install as a gem, do the following:

sudo gem install netphase-acts_as_eventable

To install as a plugin, do this:

script/plugin install git://github.com/netphase/acts_as_eventable.git

You may also get the latest from github.com by cloning from git://github.com/netphase/acts_as_eventable.git

== Setup

This code does not require changing any current database tables. It only requires adding one migration for two new tables which contain the event types and track the events.

If you are using acts_as_eventable as a plugin, you can run this to create the migration:

script/generate acts_as_eventable_migration

If you are using the gem, create a migration with the following:

def self.up create_table :event_types do |t| t.string :name end

 create_table :events do |t|
   t.integer :eventable_id, :default => 0, :null => false
   t.string :eventable_type, :limit => 25, :default => "", :null => false
   t.integer :event_type_id

   t.timestamps
 end
 add_index :events, [:eventable_id, :eventable_type]  
 add_index :events, :event_type_id

end

def self.down drop_table :events drop_table :event_types end

IMPORTANT! Acts as Eventable relies on acts_as_enumerated to cache the event types. You need to install the enumerations_mixin plugin.

To get it, do this:

script/plugin install http://svn.protocool.com/public/plugins/enumerations_mixin

== Using acts_as_eventable

First off, after you run the migration above, you need to populate your event_types table with whatever kind of events you are going to track. Let's look at the example of a coupon website.

For our coupon site, we want to know every time someone views, prints or clips a coupon. In that case, I would put the following items in a database population migration or fixture:

EventType.enumeration_model_updates_permitted = true EventType.create :name => "print" EventType.create :name => "clip" EventType.create :name => "view"

Please note that the enumeration_model_updates_permitted = true line is required whenever you are updating the event_types table, because acts_as_eventable uses acts_as_enumerated for the EventType model (please make sure you have the enumerations_mixin plugin to support this as I have not yet added it).

Now with your event types setup, you are ready to log events on your objects. Let's suppose we have a Coupon object that is living in a lovely RESTfully architected application.

First, in the Coupon model, you add this:

class Coupon < ActiveRecord::Base
acts_as_eventable end

In the CouponController's show method, you can do this:

def show @coupon = Coupon.find(params[:id]) @coupon.view end

Now, whenever someone views that individual coupon, an entry will be logged in the events table that looks like this:

+----+--------------+----------------+---------------+---------------------+---------------------+ | id | eventable_id | eventable_type | event_type_id | created_at | updated_at | +----+--------------+----------------+---------------+---------------------+---------------------+ | 1 | 6 | Coupon | 3 | 2009-06-15 17:37:47 | 2009-06-15 17:37:47 | +----+--------------+----------------+---------------+---------------------+---------------------+

Pretty cool! Notice, we did not add any other methods to Coupon object. The code automatically gives the coupon object the methods that correspond to the names of the event types!

Now, you can actually call the event type items anything you want. Because these items are added as methods to whatever object you are making eventable, you may have to come up with some interesting names to prevent name collisions. But, they are purely arbitrary. Just know that the event type name is the same as the method name you will call on your eventable object. One more thing: make sure the name can be a valid :symbol. It is important for the rails internals in this case.

So, does it work with associated objects, you ask? As a matter of fact, it does! Let's say you had a ClippedCoupon model, and it was defined as such:

class ClippedCoupon < ActiveRecord::Base belongs_to :coupon belongs_to :user # just makes our example make more sense - need to know who clipped it! end

Notice, I did not make this object acts_as_eventable. Just an ordinary association, because we are tracking Coupons, not necessarily ClippedCoupons.

Now, if I want to know if the coupon gets clipped, I would put this in my create method in the ClippedCouponController (again, assuming your app is RESTful):

def create @clipped_coupon = ClippedCoupon.create(:coupon_id => params[:coupon_id], :user_id => current_user.id) @clipped_coupon.coupon.clip end

Bam! You have just made the following entry into the events table: +----+--------------+----------------+---------------+---------------------+---------------------+ | id | eventable_id | eventable_type | event_type_id | created_at | updated_at | +----+--------------+----------------+---------------+---------------------+---------------------+ | 2 | 7 | Coupon | 2 | 2009-06-15 18:01:40 | 2009-06-15 18:01:40 | +----+--------------+----------------+---------------+---------------------+---------------------+

And voila! You now have the basis for reporting events on your objects. I will leave that part up to your imagination for now.

There are a couple of other minor methods in the code, and I am sure I will add a bunch more. I will update this README once I have tests and more methods for you to play with.

For now, enjoy!

= Credits acts_as_eventable was created by Netphase, LLC.

Netphase is Chris Beck and Scott Nedderman.

We'd love to here how you like acts_as_eventable. If you use it in one of your projects, please drop us a line.

For more information or updates on this plugin, visit http://github.com/netphase/acts_as_eventable/tree/master

Also, check out our other projects at http://netphase.com. We are available for consulting work. Contact us for your next project.

Copyright (c) 2009 Chris Beck, released under the MIT license