ActsAsEventOwner is an ActiveRecord extension that adds calendar event management to any ActiveRecord model. Models that declare themselves as acts_as_event_owner gain two has_many associations- one for the event specifications, and one for the event occurrences.

ActsAsEventOwner supports recurring events, with roughly the same recurrence rule capabilities as Apple’s iCal application. Under the hood, ActsAsEventOwner uses ri_cal to provide recurring event support.

ActsAsEventOwner is available both as a gem and as a plugin.

To install as a plugin, just do

  script/plugin install git://github.com/dburkes/acts_as_event_owner_.git

You’ll also need to install the ri_cal gem by the method of your choice (bundler, system gems, etc).

To install as a gem, use your preferred method of gem installation, e.g. Bundler, config.gem, etc.

After installation, generate a migration to add ActsAsEventOwner tables to your database:

  script/generate acts_as_event_owner_migration
  rake db:migrate

If you want to use the acts_as_event_owner rake tasks, put the following in your Rakefile:

  if Gem.searcher.find('acts_as_event_owner')
    Dir["#{Gem.searcher.find('acts_as_event_owner').full_gem_path}/**/tasks/*.rake"].each { |ext| load ext }
  end

Just add it to your Gemfile, like so:

  gem 'acts_as_event_owner'

Then do:

  bundle install

After installation, generate a migration to add ActsAsEventOwner tables to your database:

  rails generate acts_as_event_owner:migration
  rake db:migrate

  class User < ActiveRecord::Base
    acts_as_event_owner
  end

  @user = User.create :name => 'Alvin Seville'
  @user.event_specifications.create :description => 'acquire cheese balls',
    :start_at => Date.today.to_time,
    :repeat => :daily,
    :generate => false

  @user.events # => []

  @user.events.generate :from => Date.today.to_time, :to => Date.today.to_time + 1.week

  # override the description on a per-generate basis
  @user.events.generate :from => Date.today.to_time - 1.day, :to => Date.today.to_time + 1.week,
    :attributes => { :description => 'acquire cheese balls, like, right away!' }

  @user.events # => (8 ActsAsEventOwner::EventOccurrence objects)

  @user.events.past # => (1 ActsAsEventOwner::EventOccurrence objects)
  @user.events.upcoming #=> (7 ActsAsEventOwner::EventOccurrence objects)

You can create your own migrations to add custom fields to the event objects- just make sure that you add the same fields to both the event_specifications and event_occurrences tables.

When you create an EventSpecification, set the value of your custom fields, then, later, when you call generate, the values of those fields in the EventSpecification will be copied over to any generated EventOcurrence records.

Just like you can do with the standard :description attribute, you can override the default value of your custom fields with the :attributes parameter when you call generate.

ActsAsEventOwner supports recurrence rules roughly equivalent to those supported by Apple’s iCal application. Examples are:

  EventSpecification.create :description => 'pick up laundry',
    :start_at => Time.parse("4:00pm")

  EventSpecification.create :description => 'walk the dog',
    :start_at => Time.parse("8:00am"),
    :repeat => :per_hour,
    :target => [8,13,18]

  EventSpecification.create :description => 'eat breakfast',
    :start_at => Time.parse("7:30am"),
    :repeat => :daily

  EventSpecification.create :description => 'call mom',
    :start_at => Time.parse("10:30am"),
    :repeat => :daily,
    :frequency => 3

  EventSpecification.create :description => 'go to the gym',
    :start_at => Time.parse("6:30am"),
    :repeat => :weekly,
    :on => [ :mo, :we, :fr ]

  EventSpecification.create :description => 'clean the bathroom',
    :start_at => Time.parse("8:00pm"),
    :repeat => :weekly,
    :frequency => 2, :on => [ :th ]

  EventSpecification.create :description => 'pick up paycheck',
    :start_at => Time.parse("9:30am"),
    :repeat => :monthly,
    :on => [ 10, 25 ]

  EventSpecification.create :description => 'run a marathon',
    :start_at => Time.parse("6:30am"),
    :repeat => :monthly,
    :on_the => :last,
    :target => [ :sa ]

  EventSpecification.create :description => 'wine tasting',
    :start_at => Time.parse("6:30pm"),
    :repeat => :monthly,
    :on_the => :last,
    :target => :wkday

  EventSpecification.create :description => 'pay taxes',
    :start_at => Time.parse("4/15/2010 5:00pm"),
    :repeat => :yearly

  EventSpecification.create :description => 'freak out',
    :start_at => Time.zone.now,
    :repeat => :yearly,
    :frequency => 2,
    :on => [ 5 ],
    :on_the => :second,
    :target => [ :th ],
    :until => Time.parse("12/31/2012")

A rake task is included to generate occurrences of recurring events. For example, you might run this out of a cron job each day to generate any recurring events for the next 30 days, or whatever.

  rake acts_as_event_owner:generate_events FROM=9/1/2010 TO=10/1/2010

ActsAsEventOwner was developed for Josh Pigford and Sabotage Media LLC, for use in their excellent Critterly product. Big thanks to Josh and Sabotage for agreeing to make ActsAsEventOwner available by open source!