Skip to main content

Migrating from 3.x

The current v4 release is rewritten from the ground up, and have a lot of major breaking changes.

The last 3.x release was from October 2016, and was built on top of a vanilla JS codebase from 2012.

After 7 years, the javascript scene has seen some changes, such as the maturity of ECMAScript, babel, and other various bundler tools, as well as newer versions of the underlying d3.js libraries used by Cal-Heatmap.

Aside from some bugfixes and new features, the v4 branch has been rewritten from the ground up as ES modules, and transpiled to support older browsers. This direction allows an easier code maintainability and readability than the previous single file 3k lines codebase.

Most of the breaking changes come from the settings renaming, and methods removal.

Major changes

  • All functions using callbacks have been migrated to use a Promise instead
  • Code base rewritten in Typescript, and ESnext (babel transpiled for older browser support)
  • New plugin system to extend/modify calendar capabilities
  • New Template system to use user-created calendar layout
  • All dates handling delegated to dayjs
  • Bundles for ESM, UMD
  • Support for D3.js v6 and v7

Default settings update

  • animationDuration has been decreased from 500ms to 200ms.

New settings

domain.sort

Control the sort order of the domains

date.locale

Set a custom date locale. Default to en

data.x

Instruct the calendar how to extract the date from your dataset

data.y

Instruct the calendar how to extract the value from your dataset

data.groupY

Instruct the calendar how to aggregate values from same time range

subDomain.color

Dynamically color the subDomain's label

scale

New option, grouping previous functions from legend and legendColors, to control how to colorize your dataset

Renamed/moved settings

label.align

Renamed to label.textAlign.

label

Moved inside the domain namespace.

date

date is now a namespace, grouping all date related options. Old date option has been moved to date.start

minDate

Moved to date.min

maxDate

Moved to date.max

highlight

Moved to date.highlight

data

data is now a namespace, grouping all data related options. Old data option has been moved to data.source

dataType

Moved to data.type

domain

domain is now a namespace, grouping all domain related options. Old doamin option has been moved to subDomain.type

domainGutter

Moved to domain.gutter

domainMargin

Moved to domain.padding

domainDynamicDimension

Moved to domain.dynamicDimension

domainLabelFormat

Moved to domain.label

subDomain

subDomain is now a namespace, grouping all subDomain related options. Old subDomain option has been moved to subDomain.type

cellSize

Moved to subDomain.width and subDomain.height

cellRadius

Moved to subDomain.radius

cellPadding

Moved to subDomain.gutter

subDomainTextFormat

Moved to subDomain.label

Removed settings

weekStartOnMonday

Use a custom date.locale, or a custom Template.

legend, displayLegend, legendCellSize, legendCellPadding, legendCellMargin, legendVerticalPosition, legendHorizontalPosition, legendOrientation, legendTitleFormat

Removed, migrated to Legend plugin

legendColors

Moved to a new option inside scale.

subDomainDateFormat, subDomainTitleFormat, itemName

Removed, use Tooltip text

tooltip

Removed, migrated to Tooltip plugin.

afterLoadData

CalHeatmap is not expecting a strict opinionated data structure anymore, and accept an array of object, just like d3.js. See data.x, data.y and data.groupY

colLimit, rowLimit

To customize the layout of the subDomains, a new Template system has been introduced

nextSelector, previousSelector

The same objective can be achieved by adding an onClick() event on your desired DOM Element, and call next() or previous() on the calendar instance.

considerMissingDataAsZero

Data are treated as they are, you can preprocess/transform them using data.y and data,.groupY options.

itemNamespace

Obsolete, was only used internally to namespace the nextSelector and previousSelector onclick events.

New methods

  • on(eventName, callback) has been added, to replace all old callback functions.

See Events for the complete list of events

afterLoad and onComplete removed

These events are now obsolete, as all methods now return a promise.

Renamed methods

  • init(options) renamed to paint(options). This method can now be called multiple times with new options, and will update the calendar dynamically, instead of redrawing it from scratch.
  • update(data, afterLoad, updateMode) renamed to fill(data), to reflect that it's for updating data only, and not the options. It now accepts only data as its only argument, all other arguments can be set via paint()
  • destroy(callback) do not take a callback argument anymore, and returns a Promise.

Removed methods

rewind()

The same objective can be achieved by calling jumpTo() with your initial start date on the calendar instance.

showLegend(), removeLegend(), setLegend()

The same objective can be achieved by calling paint({}, [[Legend, LEGEND_OPTIONS]]) on the calendar instance.

highlight

The same objective can be achieved by calling paint({ date: { highlight: [YOUR_DATES] } }) on the calendar instance.

getSVG

Delegated to a plugin

Over changes

  • All the CSS classes used for data coloring have been removed. The scale option allow a more precise color customization.
  • All the x_ subDomains variants aside from x_day have been removed. You can re-created them with a custom template.
  • The mouse cursor do not change to pointer when hovering on a subDomain cell automatically when there is an onClick event registered, since there is no reliable way to detect if an onClick listener is registered anymore.
  • Test suite migrated to Jest, and start testing on browserstack against a matrix of browsers.