Widget Basics - Knockout

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 the Knockout framework. Similar articles are available for the jQuery library and the AngularJS framework.

Create and Configure a Widget

DevExtreme supplies a custom Knockout binding for each widget. All DevExtreme widgets are added to the application in the same manner.

To create, for example, the Menu widget, add a <div> element to the <body> tag of your page and use the dxMenu binding as the following code shows.

HTML
<div data-bind="dxMenu: { }"></div>

To configure a widget, add properties to the object passed to the widget binding. Note that these properties mirror the options of the widget.

HTML
<div data-bind="dxMenu: {
    dataSource: [
        {
            text: "Tutorials",
            items: [
                { text: "VS Integration" },
                { text: "UI Widgets" },
                { text: "Data Visualization" },
                { text: "Data Layer" }
            ]
        },
        ...
    ],
    selectByClick: true
}"></div>
See Also
  • Reference | WidgetName | Configuration - describes all options of a specific DevExtreme widget.

You can initialize a widget option with the value of a view model property. For example, the following code declares the menuItems property within a view model. The dataSource option of a Menu is initialized with the value of this property.

JavaScript
var viewModel = {
    menuItems = [
        {
            text: "Tutorials",
            items: [
                { text: "VS Integration" },
                { text: "UI Widgets" },
                { text: "Data Visualization" },
                { text: "Data Layer" }
            ]
        },
        ...
    ]
};

ko.applyBindings(viewModel);
HTML
<div data-bind="dxMenu: {
    dataSource: menuItems,
    selectByClick: true
}"></div>

As an alternative, you can declare the whole object of widget options in the view model and pass it to the widget binding.

JavaScript
var viewModel = {
    menuOptions: {
        dataSource: [
            {
                text: "Tutorials",
                items: [
                    { text: "VS Integration" },
                    { text: "UI Widgets" },
                    { text: "Data Visualization" },
                    { text: "Data Layer" }
                ]
            },
            ...
        ],
        selectByClick: true
    }
};

ko.applyBindings(viewModel);
HTML
<div data-bind="dxMenu: menuOptions"></div>

Change Options

Once you specify options in the configuration object, you may need to change them dynamically.

To be able to change a widget option, declare its value an observable.

JavaScript
var viewModel = {
    checkBoxOptions: {
        // ...
        value: ko.observable(true)
    }
};

viewModel.changeObservables = function () {
    viewModel.checkBoxOptions.value(false);
};

ko.applyBindings(viewModel);

Now, if you change an observable in code, the widget receives the changes and updates the UI. And vice versa, if a user changes something in the UI, the observable gets updated.

NOTE: Options containing array and specified on the second (or further) level of the configuration object cannot be made observable.

Call Methods

To call a method, you need to obtain the widget instance first. You can use jQuery to do this.

JavaScript
var menuInstance = $("#menuContainer").dxMenu("instance");

As an alternative, you can save the widget instance in a view model property once the widget is initialized.

JavaScript
var viewModel = {
    menuInstance: {},
    menuOptions: {
        // ...
        onInitialized: function (e) {
            viewModel.menuInstance = e.component;    
        }
    }
};

ko.applyBindings(viewModel);

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

JavaScript
viewModel.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
var viewModel = {
    menuOptions: {
        // ...
        onItemClick: function (info) {
            // Handles the "itemClick" event
        },
        onSelectionChanged: function (info) {
            // Handles the "selectionChanged" event
        }
    }
};

ko.applyBindings(viewModel);

NOTE: You can obtain the widget instance, using the component field of the event arguments object.

JavaScript
var viewModel = {
    . . .
    onSelectionChanged: function (info) {
        DevExpress.ui.notify("The " + info.component.option("value") + " was selected", "success", 3000);
    }
}

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);

NOTE: In case you need information about calling methods, see the Call Methods topic.

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();

You can also 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 of a specific DevExtreme widget.

Destroy a Widget

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

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