Migration to Newer Versions

4.6.1 -> 5.0

Tree => TreeView

Starting from version 5.0, the Tree component is replaced with the TreeView one. Tree will still be supported, but we highly recommend to use TreeView instead.

window.dhx4 => window.dhx

In the version 5.0 the window.dhx4 variable is replaced with the window.dhx one.

4.3 -> 4.4

Since version 4.4, some load methods of Grid and Tree were deprecated. You can find the details of their new usage below:


Up to version 4.3From version 4.4
Function names changed
myGrid.loadCSV(csvFile, afterCall, "csv")myGrid.load(csvFile, afterCall, "csv")
myGrid.loadCSVString(csvString, afterCall, "csv") myGrid.parse(csvString, "csv")
myGrid.loadJSArrayFile(jsarrayFile, afterCall, "jsarray")myGrid.load(jsarrayFile, afterCall, "jsarray")
myGrid.loadJSArray(JSArray, afterCall "jsarray")myGrid.parse(JSArray, "jsarray")
myGrid.loadJSON(jsonFile, afterCall, "json")myGrid.load(jsonFile, afterCall, "json")
myGride.loadJSONObject(jsonObject, afterCall, "json")myGrid.parse(jsonObject, "json")
myGrid.loadXML(xmlFile, afterCall, "xml")myGrid.load(xmlFile, afterCall, "xml")
myGrid.loadXMLString(xmlString, afterCall,"xml") myGrid.parse(xmlString, "xml")


Up to version 4.3From version 4.4
Function names changed
myTree.loadCSV(csvFile, afterCall, "csv")myTree.load(csvFile, afterCall, "csv")
myTree.loadCSVString(csvString, afterCall, "csv") myTree.parse(csvString, "csv")
myTree.loadJSArrayFile(jsarrayFile, afterCall, "jsarray")myTree.load(jsarrayFile, afterCall, "jsarray")
myTree.loadJSArray(JSArray, afterCall "jsarray")myTree.parse(JSArray, "jsarray")
myTree.loadJSON(jsonFile, afterCall, "json")myTree.load(jsonFile, afterCall, "json")
myTree.loadJSONObject(jsonObject, afterCall, "json")myTree.parse(jsonObject, "json")
myTree.loadXML(xmlFile, afterCall, "xml")myTree.load(xmlFile, afterCall, "xml")
myTree.loadXMLString(xmlString, afterCall,"xml") myTree.parse(xmlString, "xml")

3.6 -> 4.1

Changes in Ajax API

dhtmlxAjax => ajax

Instead of dhtmlxAjax you should use dhx.ajax for ajax operations. See dhtmlxAjax API for details.

Handling errors

Instead of dhtmlxError.catchError you should use onLoadXMLError handler.


Similar to doXpath in older version of API you can use xmltop and xpath methods

var root = dhx.ajax.xmltop("rows", xml_object);
var nodes = dhx.ajax.xpath(xpath_expression, root_node);
  • "rows" - name of root XML tag
  • xml_object - raw xml object, result of dhx.ajax
  • xpath_expression - path expression used to select nodes or node-sets in XML
  • root_node - node from which XPath will be applied, you can use xmltop to get it

3.6 -> 4.0

Changes in the content of package

From version 4.0 the codebase folder contains the dhtmlx.js and dhtmlx.css files - the compilation of all dhtmlx components. So instead of including separate js files for each component you can include a single .js and a single .css files.

The default skin is "skyblue". To set a different skin you need to include the related css file - skins/web/dhtmlx.css for the "web" skin or skins/terrace/dhtmlx.css for the "terrace" skin.

You don't need to include the files dhtmlxdataprocessor.js and connector.js additionally, as they're part of the dhtmlx.js file.

Including separate files

1) If you need separate js files for some components, you can take them from the
sources/{component name}/codebase folders.

In the version 3.6 the file dhtmlxcommon.js was placed in the folder of each component separately. Now you can find this file in sources/dhtmlxCommon/codebase. The files dhtmlxdataprocessor.js, connector.js and dhtmlxcontainer.js are also located here.

2) To use styles and skins for Grid in the version 3.6 you should have included the file dhtmlxgrid.css together with one of the skin files from codebase/skins/ folder, such as dhtmlxgrid_dhx_skyblue.css, for example.

Now the only thing you should do is to include one of the css files from sources/dhtmlxGrid/codebase/skins/dhtmlxgrid_skin_name.css.

3) The components Chart and DataView require the file dhtmlxcore.js to be included instead of the dhtmlxcommon.js file.

4) Since version 4.0 you don't need to include any additional extensions on the page. All of them are included into dhtmlx.js.

Common principles of API migration

1) In the new version of DHTMLX Library the names of some methods were changed. We've made these changes as the previous names of the methods under question didn't reflect their functionality precisely, which could cause ambiguity or misunderstanding.

2) Since the release of the latest version of DHTMLX library some functionality has been removed. It was made as this functionality is no longer needed and therefore isn't supported.

3) Functionality moved from object to object

There were changes in the methods of layout components (Layout, Windows, Accordion, Tabbar). It concerns the methods that don't operate on the components in whole, but affect their cells (windows, tabs) directly.

Such methods have earlier been called through myLayout object and now they are called through myLayout.cells() object. Be careful, as the names of these methods are also changed to more logical ones.

4) In the version 4.0 the methods loadXML() and loadXMLString() are replaced by the methods load and loadStruct. The load() method loads data to the component via xml or json and the loadStruct() method loads component's configuration via xml or json.

These new methods send POST request by default, and to prevent caching in some browsers extra param like "dhxr0123456789" is added. To disable this additional param, set the cache property to true: dhx.ajax.cache=true.

To send GET request instead of POST the property method is used: dhx.ajax.method = "get".


Up to version 3.6From version 4.0
Function names changed
myAcc.loadJSON(data, callback)myAcc.loadStruct(data, callback)
myAcc.loadXML(data, callback)myAcc.loadStruct(data, callback)
myAcc.setSkinParameters(ofsBetween, ofsCont)myAcc.setOffset(ofsBetween)
Functionality was removed
myAcc.setEffect(mode)Since 4.0 effects are enabled for modern browsers by default
Functionality moved from object to object
myAcc.setIcon(id, icon) myAcc.cells(id).setIcon(icon)
myAcc.clearIcon(id) myAcc.cells(id).clearIcon()
myAcc.setActive(id) myAcc.cells(id).open()
myAcc.isActive(id) myAcc.cells(id).isOpened()
myAcc.openItem(id) myAcc.cells(id).open()
myAcc.closeItem(id) myAcc.cells(id).close()
myAcc.moveOnTop(id) myAcc.cells(id).moveOnTop()
myAcc.setItemHeight(id,h) myAcc.cells(id).setHeight(h)
myAcc.setText(id,text) myAcc.cells(id).setText(text)
myAcc.getText(id) myAcc.cells(id).getText()
myAcc.showItem(id) myAcc.cells(id).show()
myAcc.hideItem(id) myAcc.cells(id).hide()
myAcc.isItemHidden(id) myAcc.cells(id).isVisible()


Views functionality was changed:

Until 3.6 you could attach components to a view without switching to it:


Starting from 4.0, firstly you need to show a view and then attach components to it:

// firstly make a view active
// then attach any components


Up to version 3.6From version 4.0
Function names changed
new dhtmlXColorPickerInput()new dhtmlXColorPicker()
myColorPicker.setOnSelectHandler(function(){})myColorPicker.attachEvent("onSelect", function(){})
myColorPicker.setOnCancelHandler(function(){})myColorPicker.attachEvent("onCancel", function(){})
Functionality was removed
myColorPicker.init()initialized automatically
myColorPicker.setImagePath(path)no longer used


Up to version 3.6From version 4.0
Function names changed
myCombo.loadXML(url, call)myCombo.load(url, call)
myCombo.loadXMLString(url, call)myCombo.load(url, call)
Functionality was removed
myCombo.enableOptionAutoHeight()adjusted automatically
myCombo.render()rendered automatically
myCombo.attachChildCombo() Related sample:  Grouping combos


From version 4.0 the files dhtmlxgrid.js and dhtmlxgridcell.js are united into one file named dhtmlxgrid.js.


Up to version 3.6From version 4.0
Functions' names changed
Functionality was removed
myLayout.setEffect()Since 4.0 effects are enabled for modern browsers by default
myLayout.setImagePath()Used for windows, since 4.0 windows don't use imagePath, icons can be set in css
Functionality moved from object to object
myLayout.setCollapsedText(id, text)myLayout.cells(id).setCollapsedText(text)

Access to cells by index removed

Layout has a possibility to access cells by id - myLayout.cells(id) or by index - myLayout.items[]. Until 3.6 both methods had used to get cell object, since version 4.0 we've kept only accessing cells by id. The access to cells by index still works if the file "dhtmlxlayout_deprecated.js" is included on the page.

Up to version 3.6From version 4.0
Access to cells by index
myLayout.items[] (array)

Offsets (margins)

In all layout versions there is a possibility to set offsets (margins). They are mostly used in full-screen init type. We haven't removed this functionality but updated the used techniques.

Old techniques (all versions up to 3.6):

// init
var myLayout = new dhtmlXLayoutObject(document.body, "3L");
// modify some private properties
myLayout.cont.obj._offsetTop = 10; // top margin
myLayout.cont.obj._offsetLeft = 10; // left margin
myLayout.cont.obj._offsetHeight = -20; // bottom margin
myLayout.cont.obj._offsetWidth = -20; // right margin
// adjust size

New techniques (from version 4.0):

// on init stage
var myLayout = new dhtmlXLayoutObject({
    parent: document.body,
    pattern: "3L",
    offsets: {
        top: 10,
        right: 20,
        bottom: 30,
        left: 40
// at any place in the code
    top: 10,
    right: 20,
    bottom: 30,
    left: 40


Until the version 3.6 layout had the event onResize. If layout was attached to a window, this event was called after the window was resized. Starting from the version 4.0 the event onResizeFinish should be used instead.

myLayout.attachEvent("onResizeFinish", function(){
    // your code here

Related sample:  onResizeFinish event


Up to version 3.6From version 4.0
Function names changed
myMenu.loadXML(xmlFile, onLoad)myMenu.loadStruct(xmlFile, onLoad)
myMenu.loadXMLString(xmlString, onLoad)myMenu.loadStruct(xmlString, onLoad)
Functionality was removed


Up to version 3.6From version 4.0
Function names changed
new dhtmlxSlider()new dhtmlXSlider()
mySlider.setOnChangeHandler(function(){})mySlider.attachEvent("onChange", function(){})
Functionality was removed
mySlider.init()no longer used, initialized on constructor stage
mySlider.setImagePath()no longer used


Up to version 3.6From version 4.0
Function names changed
myTabbar.loadXML(url, onLoad)myTabbar.loadStruct(url, onLoad)
myTabbar.loadXMLString(xmlString, onLoad)myTabbar.loadStruct(xmlString, onLoad)
myTabbar.attachEvent("onTabContentLoaded", function(id){})myTabbar.attachEvent("onContentLoaded", function(id){})
Functionality was removed
myTabbar.normalize()code improved
myTabbar.setStyle()controlled by skin
myTabbar.setImagePath()all images moved to css
myTabbar.setSkinColors()controlled by skin
myTabbar.enableScroll() code improved
myTabbar.enableForceHiding()code improved
myTabbar.enableAutoSize()code improved
myTabbar.setCustomStyle(id, style)you can use html for tabs(id).setText()
myTabbar.setMargin()controlled by skin
myTabbar.setOffset()controlled by skin
myTabbar.setSize(x, y)you need to change parent container's width/height and then call myTabbar.setSizes()
myTabbar.setHrefMode(mode)url or ajax via myTabbar.tabs(id).attachURL()
Functionality moved from object to object
myTabbar.setContent(id, value)myTabbar.tabs(id).attachObject(value)
myTabbar.setContentHTML(id, value)myTabbar.tabs(id).attachHTMLString(value)
myTabbar.hideTab(id, mode)myTabbar.tabs(id).hide(mode)
myTabbar.showTab(id, mode)myTabbar.tabs(id).show(mode)
myTabbar.setLabel(id, text)myTabbar.tabs(id).setText(text)
myTabbar.setContentHref(id, href)myTabbar.tabs(id).attachURL(href, mode)


Up to version 3.6From version 4.0
Function names changed
myToolbar.loadXML(xmlFile, onLoad)myToolbar.loadStruct(xmlFile, onLoad)
myToolbar.loadXMLString(xmlString, onLoad) myToolbar.loadStruct(xmlString, onLoad)
myToolbar.setIconPath(path) myToolbar.setIconsPath(path)


Up to version 3.6From version 4.0
Functionality was removed
myWins.enableAutoViewport()called automatically inside attachViewportTo()
myWins.setImagePath()no longer used
myWins.setEffect()Since 4.0 effects are enabled for modern browsers by default

before 3.6 there were "minmax1" and "minmax2" button names for "maximize/minimize" button, since 4.0 the common name "minmax" is used

Back to top