Migrate to the New Version

After downloading and installing a new version of DevExtreme libraries, update your projects. This article will guide you through the upgrade process. If you experience any problems while upgrading your projects, please refer to our Support Center.

NOTE
Avoid installing different DevExtreme versions concurrently. If you install an older version, you need to uninstall the current one beforehand.

General Instructions for Major and Minor Versions

Whether you upgrade your projects from another major version or from a previous minor version to a 15.2.X DevExtreme version, follow the following general instructions.

Upgrade VS DevExtreme Applications

Use the Project Converter tool for the Visual Studio projects that were created using DevExtreme Project Templates.

There are two ways of accessing the Project Converter.

  • Open your solution/project in Visual Studio. Right click the solution/project to display the context menu and choose Upgrade DevExtreme Solution to the Latest Version... (or equivalently /Upgrade DevExtreme Project to the Latest Version...).

    Invoke Project Converter

  • Run the ProjectConverter.exe program from the folder where DevExtreme is installed. By default, it is located in the "...\Program Files (x86)\DevExpress 15.2\DevExtreme\Tools\" folder.

Specify the path to the project(s) to be upgraded in the Project folder text box.

Project Converter

Review the advanced options. Check Process Subdirectories if you also want to upgrade files in any subdirectories. Check Create Backup Files to create copies of the original files that are about to be upgraded (Project Converter will add a .bak extension to the file names of the copies), so that you can recreate the original project should you encounter any problems.

NOTE
We recommend that you check Create Backup Files if you have customized layouts or stylesheets in your projects. By doing so, you will be able to extract your customized layouts or stylesheets from those file copies to merge with the new versions.

Finally, click Upgrade and the Project Converter will upgrade your project(s) to the new version.

Upgrade Apps with DevExreme Scripts

Follow the steps below to manually upgrade your applications that use DevExtreme libraries.

  • Update Scripts
    Copy the new JavaScript files from the [Sources]/Lib/js DevExtreme folder to the equivalent folder in your applications.

  • Update Stylesheets
    Copy the new CSS files from the [Sources]/Lib/css DevExtreme folder to the equivalent folder in your applications.

    NOTE
    The css folder must include the icons folder with font icons.
  • Update Layouts
    Copy the new layout files from the [Sources]/Lib/layouts DevExtreme folder to the equivalent folder in your applications.

  • Updated the Export Folder
    If you are also using the Export feature, copy the new files from the [Sources]/Exporter folder to the same folder in your apps.

You can find all these resources within your DevExtreme package.

NOTE
If you customized layouts or stylesheets in your apps, do not replace them, but rather merge them with the ones supplied by the new DevExtreme version.

Upgrade Custom Themes

If you built your custom themes based on the DevExtreme predefined themes in a Theme Builder, update them each time a new product version (a minor or a major one) is released. This is needed to apply the changes that may possibly be performed in the predefined themes that you used as a base.

When you built your custom theme in a Theme Builder, you saved the differences from the base theme by using the Export feature to a file (there are instructions in the Save the Changes topic). Follow the steps below to apply these differences to the corresponding newly released base theme.

  • Open the Theme Builder.

  • Press Import. Paste the differences that you saved in the JSON format (using the Export feature) to the invoked window. Click Apply.

  • Check that all your differences are applied and perform customizations if required.

Learn What is New

New Major Features

Get introduced with the key features that have been implemented in DevExtreme major version 15.2: What's New.

Learn More Details

Learn detailed information on new features and resolved issues in major version 15.2, and all the successive minor versions: What's New in 15.2.

Deprecated API and Breaking Changes

We always do our best to minimize the impact each new version may have on your projects. Occasionally, however, it is necessary to change the behavior of our tools and/or make certain members deprecated. We do this to improve the quality of our products. Take a look at the deprecated API and the list of breaking changes that accompany each release.

  • Deprecated API
    Run an application updated to the newest DevExtreme version. The browser console will contain information about the deprecated API used in this application and the new members to be used instead. Although the application keeps working with the deprecated API, we still recommend that you use the new API in it. In DevExtreme, deprecated API will remain functional for two more versions of our tools, at which time it will be removed with an announcement about the possible occurrence of breaking changes.

  • Breaking Changes
    Take into account the breaking changes in each release and upgrade your apps according to the instructions given for each breaking change.

15.2 Version Specifics

When upgrading from a previous major version to version 15.2.X, take into account the following changes.

iOS and Android Themes Update

Make a note that the outdated Windows 8 themes have been deprecated and will no longer ship with DevExtreme. The modern Windows 10 themes are used instead.

  • CSS Themes

    When upgrading your DevExtreme application, the deprecated CSS themes and links to these themes will be automatically removed.

    If you manually upgraded your DevExtreme app, note that your css folder now does not include the deprecated themes. Thus, remove links to these themes in the application page as well.

    To learn more about the CSS themes that are now supplied with DevExreme, refer to the Predefined Themes article.

  • Data Visualization Themes

    The Windows themes used for Data Visualization Widgets in previous versions now correspond to the modern Windows 10 themes. Moreover, the 'win8.white' and 'win8.black' theme names are deprecated. Use the 'win10.white' and 'win10.black' theme names instead from now on.

    To learn more about the themes that are now supplied for Data Visualization widgets, refer to the Appearance Customization article.

Switch dxVectorMap to Layers

With version 15.2, the dxVectorMap widget supports multiple layers. The introduced feature requires the widget configuration structure to be changed. This article describes what changes should be made in the dxVectorMap configuration to make it up to date.

The main idea of the update is making the areas and markers a single type of objects — layers. A single map can now contain several layers of a 'marker' type, as well as several 'area' layers and 'line' layers. Earlier, the areas and markers were configured in separate objects — areaSettings and markerSettings, now areas and markers are layers of a different type.

The most significant change you should make in your code is making layers array elements from the objects assigned to the areaSettings and markerSettings options.

To distinguish an 'area' layer from a 'marker' layer, set the type option to a corresponding value in each object. If your markerSettings object contains the type option, change its name to the elementType. The example below demonstrates the required changes.

JavaScript
 /* The obsolete code */
var vectorMapConfiguration = {
    areaSettings: {
        /* The areaSettings object contents */
    },
    markerSettings: {
        type: /* The type of markers */
        /* The markerSettings object contents */
    }
    // ...
}

/* The up to date code */
var vectorMapConfiguration = {
    layers: [{
        type: 'area',
        /* The areaSettings object contents */
    }, {
        type: 'marker',
        elementType: /* The type of markers */
        /* The markerSettings object contents */
    }]
    // ...
}

Next, you should move the mapData and markers options to the corresponding layers. The layers | data option is designed to replace the obsolete mapData and markers options. The example below demonstrates the required changes in code.

JavaScript
 /* The obsolete code */
var vectorMapConfiguration = {
    mapData: /* The mapData value */,
    markers: /* The markers value */,
    // ...
}

/* The up to date code */
var vectorMapConfiguration = {
    layers: [{
        type: 'area',
        data: /* The mapData value */,
    }, {
        type: 'marker',
        data: /* The markers value */,
    }]
    // ...
}

If you have a function assigned to the customize option in any of your layers, notice that the object passed to it as an argument and the returning value has changed. The new customize function should take an array of a layer elements instead of an individual area/marker and return nothing. Instead of returning the object with the options to change, use the Layer Element | applySettings(settings) method. Change your customize function code as follows.

JavaScript
 /* The obsolete code */
var vectorMapConfiguration = {
    areaSettings: {
        // ...
        customize: function (area) {
            if (/* A condition against the area object */) {
                return {
                    /* An areaSettings options to change for an individual area */
                };
            }
        }
    },
    // ...
}

/* The up to date code */
var vectorMapConfiguration = {
    layers: [{
        // ...
        type: 'area',            
        customize: function (elements) {
            $.each(elements, function (_, element) {
                if (/* A condition against the element object */) {
                    element.applySettings({
                        /* A layer options to change for an individual layer element */
                    });
                }
            });
        }
    }]
    // ...
}

User interaction handling options were also changed. A number of options related to areas and markers were removed:

  • the onAreaClick and onMarkerClick should be replaced with the onClick method;
  • the onAreaSelectionChanged and onMarkerSelectionChanged should be replaced by the onSelectionChanged method.

Since the onClick event handler is invoked even when the clicked point is located out of any layer, you should first check the target object for existence, then check what is the clicked layer type, if you need to do so. Refer to the following example code demonstrating the required changes.

JavaScript
 /* The obsolete code */
var vectorMapConfiguration = {
    onAreaClick: function (e) {
        var clickedArea = e.target;
        /* Manipulating a clicked area */
    }
}

/* The up to date code */
var vectorMapConfiguration = {
    onClick: function (e) {
        var clickedElement = e.target;
        if (clickedElement && clickedElement.layer.type == 'area'){
            var clickedArea = clickedElement;
            /* Manipulating a clicked area */
        }
    }
}

The structure of the data source for markers should also be changed. Each element of the markers data array should contain one or two options: coordinates or coordinates and attributes. All other options (text, value, values and url) should be folded into the attributes object. The attribute names are not strict, so you should define them in the configuration of the corresponding map elements (dataField or label | dataField). The following example code demonstrates the required changes.

JavaScript
 /* The obsolete code */
var markers = [{
    coordinates: [-121.2808, 38.3320],
    text: 'Sacramento',
    value: 10
}, {
    coordinates: [-97.75, 30.25],
    text: 'Austin',
    value: 7
}, {
    coordinates: [-73.7572, 42.6525],
    text: 'Albany',
    value: 17
}, {
    coordinates: [-84.2533, 30.455],
    text: 'Tallahassee',
    value: 20
}, {
    coordinates: [-89.65, 39.783],
    text: 'Springfield',
    value: 24
}];

var vectorMapConfiguration = {
    markerSettings: {
        type: 'bubble'
    },
    markers: markers,
    // ...
}

/* The up to date code */
var markers = [{
    coordinates: [-121.2808, 38.3320],
    attributes: {
        text: 'Sacramento',
        value: 10
    }
}, {
    coordinates: [-97.75, 30.25],
    attributes: {
        text: 'Austin',
        value: 7
    }
}, {
    coordinates: [-73.7572, 42.6525],
    attributes: {
        text: 'Albany',
        value: 17
    }
}, {
    coordinates: [-84.2533, 30.455],
    attributes: {
        text: 'Tallahassee',
        value: 20
    }
}, {
    coordinates: [-89.65, 39.783],
    attributes: {
        text: 'Springfield',
        value: 24
    }
}];

var vectorMapConfiguration = {
    layers: [
    // ...
    {
        type: 'marker',
        data: markers,
        elementType: 'bubble',
        dataField: 'value'
        label: {
            dataField: 'text'
        }
    }]
    // ...
}

The legends | source option has also been changed. Now it takes an array containing two options: grouping and layer. The grouping option values can be 'color' or 'size'. The following example code demonstrates the required changes.

JavaScript
 /* The obsolete code */
var vectorMapConfiguration = {
    areaSettings: {
        // ...
        colorGroups: [0, 0.5, 0.8, 1, 2, 3, 100],
        colorGroupingField: "population"
    },
    markerSettings: {
        // ...
        sizeGroups: [0, 8000, 10000, 50000]
    },
    legends: [{
        source: "areaColorGroups",
        // ...
    }, {
        source: "markerSizeGroups",
        // ...
    }]
    //...
}

/* The up to date code */
var vectorMapConfiguration = {
    layers: [{
        type: 'area',
        name: 'myAreas',
        // ...
        colorGroups: [0, 0.5, 0.8, 1, 2, 3, 100],
        colorGroupingField: "population"
    }, {
        type: 'marker',
        name: 'myMarkers',
        // ...
        sizeGroups: [0, 8000, 10000, 50000]
    }],
    legends: [{
        source: {
            layer: 'myAreas',
            grouping: 'color'
        }
        // ...
    }, {
        source: {
            layer: 'myMarkers',
            grouping: 'size'
        }
        // ...
    }]
    //...
}