Migration From Older Versions

5.0 -> 5.1

Smart rendering and horizontal scroll features required a complete remaking of the timeline markup. It affected Timeline, TreeTimeline and all modes of these views.

The most notable change is that HTML elements TABLE, TR, TD were removed from the markup and replaced with DIVs with appropriate class names.

If you use table tags in CSS selectors for styling the timeline, an action will be needed in order to migrate such CSS. The overall DOM structure didn't undergo many changes, thus migration would mostly require rewriting several CSS selectors in order for them to match the new markup.

For the reference, here is a sample of CSS selectors before and after the update given below.


  • .dhx_cal_data > table > tbody > tr > td.dhx_matrix_scell - the lefthand label column
  • .dhx_cal_data > table > tbody > tr > td > div.dhx_matrix_line - the timeline row with date cells
  • .dhx_cal_data > table > tbody > tr > td > div.dhx_matrix_line > table > tbody > tr > td.dhx_matrix_cell - a single date cell inside a timeline row


  • .dhx_cal_data .dhx_timeline_table_wrapper .dhx_timeline_label_row .dhx_matrix_scell - the lefthand label column
  • .dhx_cal_data .dhx_timeline_data_wrapper .dhx_matrix_line - the timeline row with date cells
  • .dhx_cal_data .dhx_timeline_data_wrapper .dhx_matrix_line .dhx_matrix_cell - a single date cell inside a timeline row

4.4 -> 5.0

Removed skins

Glossy and Classic skins were deprecated and removed since v5.0. If you use them, you'll either need to migrate to another skin or keep using a corresponding CSS file from an older version.

Major CSS refactoring

Release of v5.0 involves a major CSS overhaul, which may create issues with updating heavily CSS-customized applications: the existing styles may stop working due to the specificity of renewed dhtmlxScheduler styles. There is no general solution for this, the migration will require investigating and correcting CSS issues.

POST route in the REST mode fixed

The update also fixes the POST (insert) route of dataProcessor in the REST mode, the request no longer sends a temporary event id to the server.

The following route:

POST /api/{tempId}
POST /api/1234567890

should be changed to this one:

POST /api

4.x -> 4.3

Since v.4.3 the extensions Week Agenda View, Grid View, Timeline View, Units View, Multisection Events are no longer available in the Standard Edition that is distributed under GNU GPL v2.

If you still want to use them, you may either continue using the version 4.2 (or older), or obtain either Commercial or Enterprise license.

Please check the license details here.

3.6 -> 4.0

Public API is fully backward compatible.

Changed defaults

  • The default skin is changed to "terrace", ext/dhtmlxscheduler_dhx_terrace.js is removed. To change the skin back to the classic one, just include the related CSS file (codebase/dhtmlxscheduler_classic.css). For more details check Skins.

  • multi_day is enabled by default, and if you want to revert such a behavior, add:

scheduler.config.multi_day = false;

Custom skins

Scheduler detects the used skin, based on the name of the CSS file, so if you are using a custom skin (which is not based on "terrace"), rename its css file to dhtmlxscheduler_{skin name}.css. Also, you can disable the skin auto-detection by adding the following line before scheduler.init:

scheduler.skin = "{skin name}";

Deprecated API

The following API is deprecated: getEventText, getEventStartDate, getEventEndDate, setEventText, setEventStartDate, setEventEndDate (those methods are still available, but will be removed in Scheduler 5.x).

Instead, you can use scheduler.getEvent() and set/get properties directly from the event object.

3.6 -> 3.7

Fully backward compatible

3.5 -> 3.6

Fully backward compatible

3.0 -> 3.5

Public API is fully backward compatible.

  • 'Mark now' functionality was moved to the dhtmlxscheduler_limit.js extension.
  • Scheduler now accepts JSON generated by dhtmlxConnector. If there are no special reasons to use XML, consider switching to JSON (will decrease file size and, as a result, increase load speed).

2.3 -> 3.0

Public API is fully backward compatible.

For private API, check Scheduler 3.0.

  • File structure was changed a bit - ext/dhtmlxscheduler_ext.css and dhtmlxscheduler_recurring.css were removed (all styles now available in the dhtmlxscheduler.css).
  • Several templates arguments were changed to match the rest of them: scheduler.templates.agenda_text, scheduler.templates.map_text now use (start_date, end_date, event) as incoming parameters. Before only 'event' was used.

2.2 -> 2.3

  • full backward compatibility
  • Swedish locale file was renamed according to the iso 639-1
sources/locale_se.js => sources/locale_sv.js
sources/locale_recurring_se.js => sources/locale_recurring_sv.js

2.1 -> 2.2

  • full backward compatibility
  • 'createUnitsView' command accepts different set of parameters, but previous syntax will work as well

2.0 -> 2.1

  • formatting rules were corrected, now %d and %m always return 2 digits, if you need the previous behavior, use %j and %n accordingly
  • path to files inside the package is changed a bit
codebase/dhtmlxgrid_recurring.js => codebase/ext/dhtmlxgrid_recurring.js
codebase/dhtmlxgrid_recurring.css => codebase/ext/dhtmlxgrid_recurring.css
codebase/dhtmlxgrid_units.js => codebase/ext/dhtmlxgrid_units.js

1.0 -> 2.0

  • API and data format are fully backward compatible
  • 'onEventChanged' and 'onEventAdded' events will not fire during data loading
  • Spanish locale renamed from locale_sp.js to locale_es.js
  • 'drag_create' option now controls only the ability to create a new event by dnd, creating a new event by dblclick now is controlled by 'dblclick_create'
Back to top