Skip to content
Show multiple, overlapping events across calendar days and rows. Rails plugin.
Ruby JavaScript
Branch: master
Clone or download
Tasveer Singh
Tasveer Singh Added MooTools javascript support with generator
Updated README
Latest commit 131d6de Apr 15, 2011
Type Name Latest commit message Commit time
Failed to load latest commit information.
generators/event_calendar Added MooTools javascript support with generator Apr 15, 2011
lib Added MooTools javascript support with generator Apr 15, 2011
spec Be compatible with RSpec 2. Dec 30, 2010
.gitignore Be compatible with RSpec 2. Dec 30, 2010
CHANGELOG.rdoc Update the changelog. Mar 3, 2011
MIT-LICENSE first commit Jul 23, 2009
Rakefile Bump gem version to 2.3.2. Dec 30, 2010
VERSION Version bump to 2.3.3 Mar 3, 2011
event-calendar.gemspec Regenerate gemspec for version 2.3.3 Mar 3, 2011
init.rb refactored the plugin pattern to allow for class attributes. these at… May 16, 2010
install.rb first commit Jul 23, 2009
uninstall.rb first commit Jul 23, 2009



Easily show multiple, overlapping events across calendar days and rows.

See for a screenshot.

After install, the “calendar” method will be available within your views.

To customize the look, modify the included stylesheet and/or change the default options.


Rails 2

script/plugin install git://

To generate the necessary static files AND the example below:

script/generate event_calendar

Rails 3

As a gem:

gem install event-calendar

Add this to your Gemfile:

gem 'event-calendar', :require => 'event_calendar'

Or as a plugin:

rails plugin install git://

To generate the necessary static files AND the example below:

rails generate event_calendar

Generator Options

script/generate event_calendar --help

--static-only: Only generate the stylesheet and javascript
--use-jquery: Generate jQuery javascript
--use-mootools: Generate MooTools javascript
--use-all-day: Include an 'all_day' field on events, and display appropriately

You can change the default event model name (Event) and controller/view name (Calendar) by passing in two name arguments:

script/generate event_calendar EventModel ControllerName

Generated Files

Make sure to include the stylesheet and javascript in your layout/view.

Static files


Unless the –static-only option is given, the following will be generated. Names will differ if name arguments were passed to the generator.


class CreateEvents < ActiveRecord::Migration
  def self.up
    create_table :events do |t|
      t.string :name
      t.datetime :start_at
      t.datetime :end_at


  def self.down
    drop_table :events

At minimum we need to have start_at and end_at fields. Altnernatively, you can configure the columns to be used by passing options to has_event_calendar.

If the '–use-all-day' option is passed to the generator, it will also add a boolean all_day field. Set :start_at to be any time on the day of the event and set :all_day to true.

An event can also have a color field (any string which is a valid CSS color) which determines the color of the event. Or simply override the default virtual attribute on the model. For example, if events are associated to a calendar model, then the events can get their color from the calendar.


class Event < ActiveRecord::Base

  # To specify the columns to use call it like this:
  # has_event_calendar :start_at_field  => 'custom_start_at', :end_at_field => 'custom_end_at'



Rails 2:

map.calendar '/calendar/:year/:month', :controller => 'calendar', :action => 'index', :requirements => {:year => /\d{4}/, :month => /\d{1,2}/}, :year => nil, :month => nil

Rails 3:

match '/calendar(/:year(/:month))' => 'calendar#index', :as => :calendar, :constraints => {:year => /\d{4}/, :month => /\d{1,2}/}


class CalendarController < ApplicationController

  def index
    @month = (params[:month] ||
    @year = (params[:year] ||

    @shown_month = Date.civil(@year, @month)

    @event_strips = Event.event_strips_for_month(@shown_month)

    # To restrict what events are included in the result you can pass additional find options like this:
    # @event_strips = Event.event_strips_for_month(@shown_month, :include => :some_relation, :conditions => 'some_relations.some_column = true')




Some helper methods are created, but you could put this in the view. The key is our calendar method, which takes some options.

module CalendarHelper
  def month_link(month_date)
    link_to(I18n.localize(month_date, :format => "%B"), {:month => month_date.month, :year => month_date.year})

  # custom options for this calendar
  def event_calendar_options
      :year => @year,
      :month => @month,
      :event_strips => @event_strips,
      :month_name_text => I18n.localize(@shown_month, :format => "%B %Y"),
      :previous_month_text => "<< " + month_link(@shown_month.prev_month),
      :next_month_text => month_link(@shown_month.next_month) + " >>"

  def event_calendar
    calendar event_calendar_options do |args|
      event = args[:event]
      %(<a href="/events/#{}" title="#{h(}">#{h(}</a>)

Notice you can pass in a block to the calendar method. In this example I'm passing a link to the event details, and displaying the event's name. If you are using the MooTools javascript, a Tip will be created with the content of the link's title attribute for displaying additional information.


Then in calendar view, simply:

<%= event_calendar %>

In Rails 3, use raw(event_calendar)

Default Options

The default options for the calendar are:

defaults = {
  :year =>,
  :month =>,
  :abbrev => true,
  :first_day_of_week => 0, # See note below when setting this
  :show_today => true,
  :show_header => true,
  :month_name_text =>"%B %Y"),
  :previous_month_text => nil,
  :next_month_text => nil,
  :event_strips => [],

  # it would be nice to have these in the CSS file
  # but they are needed to perform height calculations
  :width => nil,
  :height => 500, 
  :day_names_height => 18,
  :day_nums_height => 18,
  :event_height => 18,
  :event_margin => 1,
  :event_padding_top => 1,

  :use_all_day => false,
  :use_javascript => true,
  :link_to_day_action => false

You can override any of these by passing your options to the calendar method. In the above example, update the event_calendar_options helper method.


  • See the notes in the plugin's calendar_helper.rb for more info.

  • width: Optional, if none is given it will stretch to the containing element.

  • height: Defaults to 500px. This is the approx minimum total height of the calendar. It could be greater if a calendar row(s) need to stretch to fit additional events.

  • use_all_day: If set to true, will check for an 'all_day' boolean field when displaying an event. If it is an all day event, or the event is multiple days, then it will display as usual. Otherwise it will display without a background color bar.


    :use_all_day => true

    If using this option, you probably want to also show times for non-all-day events:

    calendar event_calendar_options do |args|
      event, day = args[:event], args[:day]
      html = %(<a href="/events/#{}" title="#{h(}">)
      html << display_event_time(event, day)
      html << %(#{h(}</a>)
  • use_javascript: If set to false, it won't add custom HTML data attributes that are needed for javascript highlighting. (Note, custom attributes will be valid in HTML 5.) The actual javascript is unobtrusive and found in the event_calendar.js file.

  • link_to_day_action: Will make the calendar's day numbers links to the given Rails action. Note, you'll probably want a corresponding route, controller action, and view to go with this action. Example:

    Helper/View calendar option:

    :link_to_day_action => "day"

    Route (the controller is the same as your other calendar route):

    map.calendar_day "/calendar/:year/:month/:day", :controller => "calendar", :action => "day"


  • If you want to change the first day of the week from the default of Sunday (0), then set the new value in an instance variable and pass it to event_strips_for_month (in the controller), and to the event calendar options (in the helper/view).


    @first_day_of_week = 1
    @event_strips = Event.event_strips_for_month(@shown_month, @first_day_of_week)

    Helper/View calendar options:

    :first_day_of_week => @first_day_of_week
  • If you need access to the events, not just the event strips, then instead of calling event_strips_for_month call these 3 methods:

    start_d, end_d = Event.get_start_and_end_dates(@shown_month) # optionally pass in @first_day_of_week
    @events = Event.events_for_date_range(start_d, end_d)
    @event_strips = Event.create_event_strips(start_d, end_d, @events)
  • The event select color is set in the event_calendar.js file.

ORM Support

Mongoid is supported out of the box with no additional lines of code in the model. Use the has_event_calendar method as you do with ActiveRecord.


To localize month and day names, add the following to your localization file(s) in config/locales:

date -> formats, day_names, abbr_day_names, month_names, abbr_month_names

For example, in es.yml:

      default: "%e/%m/%Y"

    day_names: [Domingo, Lunes, Martes, Miércoles, Jueves, Viernes, Sábado]
    abbr_day_names: [Dom, Lun, Mar, Mie, Jue, Vie, Sab]

    # Don't forget the nil at the beginning; there's no such thing as a 0th month
    month_names: [~, Enero, Febrero, Marzo, Abril, Mayo, Junio, Julio, Agosto, Septiembre, Octubre, Noviembre, Diciembre]
    abbr_month_names: [~, Ene, Feb, Mar, Abr, May, Jun, Jul, Ago, Sep, Oct, Nov, Dic]


  • Jeff Schuil

  • See commit history for list of additional contributors.

  • Thanks to those who have added features, fixed bugs, and/or reported issues.


Copyright © 2009 Elevation, released under the MIT license

You can’t perform that action at this time.