All docs
V20.2
20.2
20.1
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.
17.1
The page you are viewing does not exist in version 17.1. This link will take you to the root page.
16.2
The page you are viewing does not exist in version 16.2. This link will take you to the root page.

Component Configuration Syntax

Create and Configure a Component

Any DevExtreme widget must be placed in a container. This role is played by a <div> HTML element. Add a <div> to the <body> tag of your page. Make sure that this <div> has the id attribute specified.

HTML
<div id="buttonContainer"></div>

DevExtreme supplies a jQuery plugin for each widget. To create, for example, the Button widget within the buttonContainer element, use the dxButton() plugin as the following code shows.

JavaScript
$(function () {
    $("#buttonContainer").dxButton();
});

To configure a widget, pass an object to the plugin as shown in the following code. Properties of this object mirror the options of the widget.

JavaScript
$(function () {
    $("#buttonContainer").dxButton({
        text: "Click me!",
        onClick: function () {
            alert("Hello world!");
        }
    });
});
See Also

Get and Set Options

All operations with widget options are carried out using the option() method. You can use it to do the following.

Get a Single Option

JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
var dataSource = dataGridInstance.option("dataSource");
var editMode = dataGridInstance.option("editing.mode");

// ---------- or ----------
var dataSource = $("#dataGridContainer").dxDataGrid("option", "dataSource");
var editMode = $("#dataGridContainer").dxDataGrid("option", "editing.mode");

Get All Options

JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
var dataGridOptions = dataGridInstance.option();

// ---------- or ----------
var dataGridOptions = $("#dataGridContainer").dxDataGrid("option");

Set a Single Option

JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
dataGridInstance.option("dataSource", []);
dataGridInstance.option("editing.mode", "batch");

// ---------- or ----------
$("#dataGridContainer").dxDataGrid("option", "dataSource", []);
$("#dataGridContainer").dxDataGrid("option", "editing.mode", "batch");
NOTE
If you perform several option changes, wrap them with the beginUpdate() and endUpdate() method calls. This prevents the widget from being unnecessarily refreshed and from events being raised. Use an object instead if you need to change several options at once.

Set Several Options

JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
dataGridInstance.option({
    dataSource: [],
    editing: {
        mode: "cell"
    }
});

// ---------- or ----------
$("#dataGridContainer").dxDataGrid({
    dataSource: [],
    editing: {
        mode: "cell"
    }
});
NOTE

When you pass an object to the option(options) method or to the jQuery plugin at runtime as shown in the previous code, options specified in this object will be merged with the options that were specified at design time.

This works properly unless the options were specified as arrays. If the latter is true, set new options between beginUpdate() and endUpdate() method calls. The following code sample demonstrates the described technique using an example of the valueAxis array in the Chart widget:

JavaScript
var chart = $("#chartContainer").dxChart({
    // ...
    valueAxis: [{
        name: "axis1",
        // ...
    }, {
        name: "axis2",
        // ...
    }]
}).dxChart("instance");

chart.beginUpdate();
chart.option("valueAxis[0].visible", false);
chart.option("valueAxis[1].grid.visible", false);
chart.endUpdate();

Call Methods

To call a widget method, pass its name to the jQuery plugin.

JavaScript
var allSeries = $("#chartContainer").dxChart("getAllSeries");

If a method accepts arguments, pass them right after the method's name.

JavaScript
var fruitsSeries = $("#chartContainer").dxChart("getSeriesByName", "fruits");

As an alternative, you can obtain the widget instance first, and then call any method of this instance.

JavaScript
var chartInstance = $("#chartContainer").dxChart("instance");
var allSeries = chartInstance.getAllSeries();
var fruitsSeries = chartInstance.getSeriesByName("fruits");
See Also
  • API Reference.WidgetName.Methods, for example, API Reference.Chart.Methods

Get a Widget Instance

Use the following code to get a widget instance:

JavaScript
var chartInstance = $("#chartContainer").dxChart("instance");

If the widget is not yet instantiated, this code throws an E0009 exception that you can handle with a try...catch block:

JavaScript
try {
    var chartInstance = $("#chartContainer").dxChart("instance");
}
catch (err) {
    alert("Exception handled: " + err.message);
}

Instead of the exception, you can get a truthy or falsy value that can be used in conditional statements. To do this, call the widget class's static getInstance(element) method. This method returns undefined if the widget is not instantiated for the element:

JavaScript
var element = document.getElementById("chartContainer");
var chartInstance = DevExpress.viz.dxChart.getInstance(element);
if (chartInstance) {
    // Your code goes here
}

Handle Events

Subscribe to an Event

You can subscribe to an event using a configuration option. All event handling options are given names that begin with on.

JavaScript
$("#dataGridContainer").dxDataGrid({
    onCellClick: function (e) {
        // Handles the "cellClick" event
    },
    onSelectionChanged: function (e) {
        // Handles the "selectionChanged" event
    }
});

As a more flexible solution, you can use the on() method. It allows you to subscribe to events at runtime and attach several handlers to a single event.

JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
// Subscribes to the "cellClick" and "selectionChanged" events
dataGridInstance
    .on({
        "cellClick": cellClickHandler,
        "selectionChanged": selectionChangedHandler
    });
JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
// Attaches several handlers to the "cellClick" event
dataGridInstance
    .on("cellClick", cellClickHandler1)
    .on("cellClick", cellClickHandler2);

Unsubscribe from an Event

To detach a specific handler from an event, call the off(eventName, handler) method.

JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
// Detaches the "cellClickHandler1" from the "cellClick" event leaving other handlers (if any) intact
dataGridInstance.off("cellClick", cellClickHandler1)

You can also use this method to detach all handlers from a particular event.

JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
// Detaches all handlers from the "cellClick" event
dataGridInstance.off("cellClick")

If you subscribed to an event using an onEventName option, you can unsubscribe from it by setting this option to undefined.

JavaScript
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
dataGridInstance.option("onCellClick", undefined);
See Also
  • API Reference.WidgetName.Events, for example, API Reference.DataGrid.Events

Dispose of a Widget

To dispose of a DevExtreme widget, free up the allocated resources by calling the dispose() method. Then, remove the widget's associated DOM node:

JavaScript
$("#dataGridContainer").dxDataGrid("dispose");
$("#dataGridContainer").remove();