Calendars in web applications

Every once in a while you'll need to have a calendar on a website. Creating one from scratch is quite a lot of work and probably not a good use of your time, unless the calendar is really a key part of the site and you want full control over all aspects of it.

Fullcalendar is a really nice jQuery plugin that provides a lot of control on how you want the calendar to look and the resulting calendar both works and looks great.

In this case the plugin is used together with the data provided by the Events controller in a Rails application.

Fullcalendar plugin

The Fullcalendar site has extensive documentation about how to configure the plugin. This section contains just the basics required to get the calendar displayed on the site.

Initializing the calendar

The page where the calendar should be displayed, should have a placeholder element where the calendar is added, for example, a div with the id of #calendar:

<div id="calendar"></div>

The calendar can, as basically every other jQuery plugin, be initialized with the following code. The events configuration option is used to define where the event data comes from, in this case a json request to the application, which will be handled by the index action of the events controller:

$('#calendar').fullCalendar({
    events: '/events.json'
});

Data input

There are multiple ways to provide data to the plugin:

  • as an array in Javascript
  • as a response to a JSON request
  • as a function

Rails is a good framework for providing API's by default so returning the data for a JSON request looks like a good option. One way to provide further flexibility is to use the RABL (Ruby API Builder Language) gem RABL on Github.

Installing the gem

gem 'rabl'
gem 'json'

and doing

$ bundle update

Controller

The Fullcalendar plugin makes a request when it needs the data to be shown. The request is of form

GET "/events.json?start=1330297200&end=1333922400&_=1330990656934

The events controller should handle the timestamps provided in the request to filter out data that is not required for displaying of the calendar. For the purposes of this example, the following basic code would do the job but return all events:

def index
    @events = Event.all
end

RABL template

When using RABL, a template for the response needs to be defined in the views folder. In this case the file would be named

app/views/events/index.json.rabl

The template defines which parameters should be returned by the controller. There are also a number of other ways the response can be customized. It is possible to rename attributes, include data from child objects and execute Ruby code to add conditions on the data to display.

# a collection of events is returned
collection @events

# the attributes are returned as defined in the DB
attributes :id, :title

# attributes can be renamed or new attributes can be defined with the following syntax
node(:start) { |event| event.start_date }
node(:end) { |event| event.end_date }

# The URL of an event can be added with the following code. Also URL helpers can be used
node(:url) { |event| event_url(event) }

# Event formatting can be affected in the template 
# and Ruby code can be executed
node(:color) { |event| event.start_date - 2.weeks < Time.now ? 'red' : 'green' } 

Rails by default includes the root object in JSON, which doesn't work with the Fullcalendar plugin. That can be changed by adding an initializer file with the following contents:

Rabl.configure do |config|
    config.include_json_root = false
end

Summary

This quick overview should provide the basic information on how to integrate Fullcalendar jQuery plugin to a Rails application. RABL is a very good fit for providing the data with an easy way to customize it further for the needs of the plugin and your application.