Widget Basics - jQuery

NOTE
This article assumes that you have successfully linked all the necessary scripts. If not, read the Installation guide first.

From this article, you will learn how to perform basic operations on a DevExtreme widget using jQuery tools. Similar articles are available for the AngularJS and Knockout frameworks.

Create and Configure a Widget

Any 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="chartContainer" style="height:400px; max-width:800px"></div>

DevExtreme supplies a jQuery plugin for each widget.

To create, for example, the dxChart widget within the chartContainer element, use the dxChart() plugin as the following code shows.

JavaScript
$(function () {
    $("#chartContainer").dxChart();
});

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

JavaScript
$(function () {
    $("#chartContainer").dxChart({
        dataSource: [
            { fruit: 'Oranges', total: 10 },
            { fruit: 'Apples', total: 15 },
            { fruit: 'Bananas', total: 9 }
        ],
        series: { argumentField: 'fruit', valueField: 'total' }
    });
});
See Also
  • Reference | WidgetName | Configuration - describes all options of a specific DevExtreme widget.

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 All Options

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

// ---------- or ----------
var chartOptions = $("#chartContainer").dxChart("option");

Get the Value of a Single Option

JavaScript
var chartInstance = $("#chartContainer").dxChart("instance");
var chartDataSource = chartInstance.option("dataSource");
var legendVisibility = chartInstance.option("legend.visible");

// ---------- or ----------
var chartDataSource = $("#chartContainer").dxChart("option", "dataSource");
var legendVisibility = $("#chartContainer").dxChart("option", "legend.visible");

Set a Single Option

JavaScript
var chartInstance = $("#chartContainer").dxChart("instance");
chartInstance.option("dataSource", []);
chartInstance.option("legend.visible", true);

// ---------- or ----------
$("#chartContainer").dxChart("option", "dataSource", []);
$("#chartContainer").dxChart("option", "legend.visible", true);
NOTE
If you perform a chain of option changes, wrap it up into the beginUpdate() and endUpdate() function calls. It prevents the widget from unnecessary refreshing and event raising. Better yet, use an object instead if you need to change several options at once.

Set Several Options

JavaScript
var chartInstance = $("#chartContainer").dxChart("instance");
chartInstance.option({
    dataSource: [],
    legend: {
        visible: true
    }
});

// ---------- or ----------
$("#chartContainer").dxChart({
    dataSource: [],
    legend: {
        visible: true
    }
});
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.

Call Methods

To call a method, you need to obtain the widget instance first.

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

After that, you can call any method of that instance.

JavaScript
var series = chartInstance.getAllSeries();
See Also
  • Reference | WidgetName | Methods - describes all methods of a specific DevExtreme widget.

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
$("#chartContainer").dxChart({
    onLegendClick: function (info) {
        // Handles the "legendClick" event
    },
    onArgumentAxisClick: function (info) {
        // Handles the "argumentAxisClick" event
    }
});

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

JavaScript
// Subscribes to the "legendClick" and "argumentAxisClick" events
chartInstance
    .on({
        "legendClick": handler1,
        "argumentAxisClick": handler2
    });
JavaScript
// Attaches several handlers to the "legendClick" event
chartInstance
    .on("legendClick", handler1)
    .on("legendClick", handler2);

Unsubscribe from an Event

To detach all the handlers that you attached with the on() method, call the off() method without arguments.

JavaScript
chartInstance.off();

Also, you can call this method to detach a specific handler from an event or all handlers from a particular event.

JavaScript
// Detaches the "handler1" from the "legendClick" event leaving other handlers (if any) intact
chartInstance
    .off("legendClick", handler1)
JavaScript
// Detaches all handlers from the "legendClick" event
chartInstance
    .off("legendClick")

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

JavaScript
chartInstance.option("onLegendClick", undefined);
See Also
  • Reference | WidgetName | Events - describes all events that a specific widget fires.

Destroy a Widget

To destroy a DevExtreme widget, remove the DOM node associated with this widget.

JavaScript
$("#chartContainer").remove();