Create and Configure a Component
Any DevExtreme UI component 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.
<div id="buttonContainer"></div>
DevExtreme supplies a jQuery plugin for each UI component. To create, for example, the Button UI component within the buttonContainer element, use the dxButton() plugin as the following code shows.
$(function () {
$("#buttonContainer").dxButton();
});To configure a UI component, pass an object to the plugin as shown in the following code. Properties of this object mirror the properties of the UI component.
$(function () {
$("#buttonContainer").dxButton({
text: "Click me!",
onClick: function () {
alert("Hello world!");
}
});
});See Also
- API Reference.WidgetName.Configuration, for example, API Reference.Button.Configuration
Get a Single Property
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");Set a Single Property
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
dataGridInstance.option("dataSource", []);
dataGridInstance.option("editing.mode", "batch");
// ---------- or ----------
$("#dataGridContainer").dxDataGrid("option", "dataSource", []);
$("#dataGridContainer").dxDataGrid("option", "editing.mode", "batch");Set Several Properties
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
dataGridInstance.option({
dataSource: [],
editing: {
mode: "cell"
}
});
// ---------- or ----------
$("#dataGridContainer").dxDataGrid({
dataSource: [],
editing: {
mode: "cell"
}
});When you pass an object to the option(options) method or to the jQuery plugin at runtime as shown in the previous code, properties specified in this object will be merged with the properties that were specified at design time.
This works properly unless the properties were specified as arrays. If the latter is true, set new properties between beginUpdate() and endUpdate() method calls. The following code sample demonstrates the described technique using an example of the valueAxis array in the Chart UI component:
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 UI component method, pass its name to the jQuery plugin.
var allSeries = $("#chartContainer").dxChart("getAllSeries");If a method accepts arguments, pass them right after the method's name.
var fruitsSeries = $("#chartContainer").dxChart("getSeriesByName", "fruits");As an alternative, you can obtain the UI component instance first, and then call any method of this instance.
var chartInstance = $("#chartContainer").dxChart("instance");
var allSeries = chartInstance.getAllSeries();
var fruitsSeries = chartInstance.getSeriesByName("fruits");See Also
Get a UI Component Instance
Use the following code to get a UI component instance:
var chartInstance = $("#chartContainer").dxChart("instance");If the UI component is not yet instantiated, this code throws an E0009 exception that you can handle with a try...catch block:
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 UI component class's static getInstance(element) method. This method returns undefined if the UI component is not instantiated for the element:
var element = document.getElementById("chartContainer");
var chartInstance = DevExpress.viz.dxChart.getInstance(element);
if (chartInstance) {
// Your code goes here
}Subscribe to an Event
You can subscribe to an event using a configuration property. All event handling properties are given names that begin with on.
$("#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.
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
// Subscribes to the "cellClick" and "selectionChanged" events
dataGridInstance
.on({
"cellClick": cellClickHandler,
"selectionChanged": selectionChangedHandler
});
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.
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.
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
// Detaches all handlers from the "cellClick" event
dataGridInstance.off("cellClick")If you subscribed to an event using an onEventName property, you can unsubscribe from it by setting this property to undefined.
var dataGridInstance = $("#dataGridContainer").dxDataGrid("instance");
dataGridInstance.option("onCellClick", undefined);