Cal-Heatmap 3 released

The latest 3.x branch of cal-heatmap comes with one new big feature: vertical orientation.


Implementing it was not easy, since other features, like label position on the side, etc, must come along.

A quick summary of all the new features in the v3:

  • Calendar vertical orientation
  • Label can be positioned on all four sides
  • Label can be rotated (-90deg/+90deg)
  • New x_ variants subdomains. Append x_ before a subdomain (eg: x_dat, x_month) to rotated its reading order. More useful when using a vertical orientation.
  • New offset option for the label, for more control on its x/y position.
  • id option was replaced by itemSelector. It now takes a String Selector, compliant with CSS3. You can now use something like body > p:first-child > [title="calendar"]. If the selector returns more than one result, the first one will be used. itemSelector can also directly take a DOM Element object.
  • New domainMargin to add margin around domain.
  • New domainDynamicDimension, to allow the domain width and height to fit its content, since not all the months have the same number of weeks. Disabling it will set all the domains with the same width, and may leave a space between domain.
  • You can now display a text/date inside subDomain cells.
  • highlightToday was replaced by highlight, and takes an array of dates, so you can highlight any subDomain cells.
  • More legend options, so that you can place it either on top or below the calendar, and align it left, center or right. The legend size is now independent from cellSize, and can be set via legendCellSize.
  • Oh, all references to scale was renamed to legend
  • The browsing option was removed. It is now enabled by default, and cal-heatmap will not create the next/previous buttons for you anymore.
  • Two new events methods next() and previous() were added to browse the calendar.
  • If you don’t like the idea of using javascript to navigate the calendar, two new previousSelector and nextSelector options were added to directly attach the next() and previous() methods to a DOM Element on mouse click.
  • Domain Highlighting: you can control the background color of any domain. Opposed to the subDomain highlight option, domain highlighting is passive and controlled solely via CSS.

With this lot of new features and option, almost all options were renamed for consistency. Some option like scale are now renamed legend, some have just been camelCased.

See the new shiny website for details about each features.
I’m pretty satisfied with it, as each option is now properly documented and illustrated with a simple example. You can learn a lot more there than in this post.