This is the official landing page for icalRender, a simple Ruby script for rendering iCalendar data fetched from the web.

Contents


What is this all about?

I wrote icalRender to address a specific need that I had: get a list of my upcoming DJ gigs on the sidebar of my blog. While there are no doubt dozens of possible ways of accomplishing this, I decided to use Ruby to write it, largely because I had been learning it and was very keen on putting it to good use. But enough about motivations.

The icalRender concept is a simple one, well-described using the venerable numbered list:

  1. Read a configuration file to find the desired calendar location, start and end date offsets, output template, and output file.
  2. Fetch the calendar via HTTP and parse it using the Ruby iCalendar library.
  3. Pass the calendar object to the ERB template.
  4. Render the template output to the output file.

icalRender works well in a cron-based environment. When run periodically, the generated output can be included in a number of context by many means, such as server-side includes or PHP includes, without taxing the calendar-hosting web server with a request for every page including the calendar.


The Gritty Details

There are only three pieces to the icalRender puzzle, each of which is conveniently isolated into its own file. They are:


icalRender.rb

This script does not necessarily need to be edited (unless you want to, of course). It takes a single optional argument of the configuration file name to use. To run it, you must have the Ruby iCalendar library in your Ruby environment, either by installing the gem in the system location or by setting your RUBYLIB environment variable as such:

export RUBYLIB="/home/user/local/ruby/gems/gems/icalendar-0.96.4/lib

Note that the above example is just that; your actual value and icalendar version may differ.

Once you have your environment set up, you can run the script with no arguments to produce output using the default settings:

$ /path/to/icalRender.rb

If you wish, you can specify an alternate configuration file simply by passing it as the only argument:

$ /path/to/icalRender.rb /path/to/configfile.yaml

To customize the input and output, you’ll need to edit some files….


icalRender.config.yaml

This file contains configuration in a very simple format, YAML. The values are as follows:

Option Description
calendarUrl The HTTP URL of a calendar to fetch.
Default: http://www.google.com/calendar/ical/…/public/basic.ics
startMonthOffset The start date’s offset from the current date in months.
Default: 0
startDayOffset The start date’s offset in days.
Default: 0
endMonthOffset The end date’s offset in months.
Default: 3
endDayOffset The end date’s offset in days.
Default: 0
outputTemplate The output template file name.
Default: eventList.rhtml
outputFile The rendered output file name.
Default: eventList.html


eventList.rhtml

This is the ERB template to which the calendar object is passed. It has full access to the calendar data (filtered by the dates specified in the config file), and can choose to render it in any way you like — it doesn’t even have to be HTML. See the documentation for ERB for more details on how to modify this to your liking.


Enough talk, let me Download!

icalRender will be available for download real soon now!