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

All widgets 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 a configuration object as the plugin parameter. The properties of this object represent the widget's configuration options. To specify them, set the required values to the configuration object's properties.

JavaScript
$(function () {
    var showHelloWorld = function () {
        alert("Hello world!");
    };

    $("#buttonContainer").dxButton({
        onClick: showHelloWorld,
        text: "Click me!"
    });
});
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 menuInstance = $("#menuContainer").dxMenu("instance");
var menuOptions = menuInstance.option();

// ---------- or ----------
var menuOptions = $("#menuContainer").dxMenu("option");

Get the Value of a Single Option

JavaScript
var menuInstance = $("#menuContainer").dxMenu("instance");
var menuDataSource = menuInstance.option("dataSource");
var submenuMode = menuInstance.option("showSubmenuMode.name");

// ---------- or ----------
var menuDataSource = $("#menuContainer").dxMenu("option", "dataSource");
var submenuMode = $("#menuContainer").dxMenu("option", "showSubmenuMode.name");

Set a Single Option

JavaScript
var menuInstance = $("#menuContainer").dxMenu("instance");
menuInstance.option("dataSource", []);
menuInstance.option("showSubmenuMode.name", 'onClick');

// ---------- or ----------
$("#menuContainer").dxMenu("option", "dataSource", []);
$("#menuContainer").dxMenu("option", "showSubmenuMode.name", 'onClick');

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 menuInstance = $("#menuContainer").dxMenu("instance");
menuInstance.option({
    dataSource: [],
    showSubmenuMode: {
        name: 'onClick'
    }
});

// ---------- or ----------
$("#menuContainer").dxMenu({
    dataSource: [],
    showSubmenuMode: {
        name: 'onClick'
    }
});

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 menuInstance = $("#menuContainer").dxMenu("instance");

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

JavaScript
menuInstance.repaint();
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
$("#menuContainer").dxMenu({
    onItemClick: function (info) {
        // Handles the "itemClick" event
    },
    onSelectionChanged: function (info) {
        // 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 even to attach several handlers to a single event.

JavaScript
// Subscribes to the "itemClick" and "selectionChanged" events
menuInstance
    .on({
        "itemClick": handler1,
        "selectionChanged": handler2
    });
JavaScript
// Attaches several handlers to the "itemClick" event
menuInstance
    .on("itemClick", handler1)
    .on("itemClick", handler2);

Unsubscribe from an Event

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

JavaScript
menuInstance.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 "itemClick" event leaving other handlers (if any) intact
menuInstance
    .off("itemClick", handler1)

// Detaches all handlers from the "itemClick" event
menuInstance
    .off("itemClick")

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

JavaScript
menuInstance.option("onItemClick", 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
$("#menuContainer").remove();