Manipulate a Widget

This article describes how to access a widget instance at runtime. You will also learn how to modify widget options and handle events.

Access a Widget

You may need to access a widget during application flow to specify its properties or call its functions. To access a widget instance, use its jQuery plugin and pass "instance" as a parameter. The following code demonstrates how to do this.

JavaScript
var button = $("#buttonContainer").dxButton("instance");

Use the widget's instance to access its members. In addition, you can get and set widget configuration options.

Change Options

Once you specify options in the configuration object, you may need to change them dynamically. Depending on which approach you used to create a widget, use the corresponding technique to change a specified value.

jQuery Approach

Use the following techniques when working with options in code.

Get Option Value

When you have an instance of a widget accessed, you can get or set its configuration options at runtime. To do this, use one of the following approaches.

  • Use option() function of a widget instance

    Call the option function passing the name of the option whose value you want to get.

    JavaScript
    var button = $("#buttonContainer").dxButton("instance");
    var buttonText = button.option('text');
  • Use the widget's plugin

    Call the function that represents the widget's jQuery plugin passing "option" as the first parameter and the name of the required option as the second parameter.

    JavaScript
    var buttonText = $("#buttonContainer").dxButton('option','text');

Set an Option

To set a configuration option to a new value, pick from two approaches analogous to the approaches used for getting the option value presented above.

  • Use the option() function of a widget instance

    Call the option function passing the option name as the first parameter and a new value as the second value.

    JavaScript
    var button = $("#buttonContainer").dxButton("instance");
    button.option('text', 'Click');
  • Use the widget's plugin

    Call the function that represents the widget's jQuery plugin passing "option" as the first parameter, the name of the required option as the second parameter and a new value for the option as the third parameter.

    JavaScript
    $("#buttonContainer").dxButton('option','text','Click');

After an option change, the widget will be refreshed automatically.

NOTE: If you perform a chain of option changes, wrap it by the calls of the widget's beginUpdate and endUpdate functions. In this instance, the changes will be applied all together after the end of the transaction.

Set Several Options

You can set more than one option at a time. In such a case, define a configuration object whose properties represent the options that are set to new values. Choose the appropriate approach to pass this object.

  • Use the option() function of a widget instance

    JavaScript
    var button = $("#buttonContainer").dxButton("instance");
    button.option({
        text: 'Click',
        type: 'danger'
    });
  • Use the widget's plugin

    JavaScript
    $("#buttonContainer").dxButton({
        text: 'Click',
        type: 'danger'
    });

    NOTE: This approach recalls the way you create a widget. However, if there is a widget created in a specified container, the next time the widget's plugin is called with the configuration object specified, the options will be merged.

Knockout Approach

When using a Knockout approach to create a widget, some of the widget options or all of them are bound to ViewModel fields.

JavaScript
var viewModel = {
    buttonText = "Click me";
};
HTML
<div data-bind="dxButton: { text: buttonText }"></div>

Therefore, to get an option value, get the value of the corresponding ViewModel field.

JavaScript
var text = viewModel.buttonText;

To change an option value dynamically during application flow and update the widget in response to the option change, utilize observables.

JavaScript
var viewModel = {
    buttonText = ko.observable("Click me");
};

viewModel.changeText = function () {
    viewModel.buttonText('Title has been changed');
};

NOTE: Only options that are specified on the first level of the configuration object can be made observable.

Angular Approach

When using the Angular approach, you can set configuration options to the values that are specified in scope or set an entire object from the scope as a configuration object of a widget.

HTML
<div ng-controller="Controller">
    <div dx-button="{ text: buttonText, clickAction: showHelloWorld }"></div>
</div>
JavaScript
function Controller($scope) {
    $scope.buttonText = "Click me!";
    $scope.showHelloWorld = function() {
       alert("Hello world!");
    }
}

Therefore, to get an option value, get the value of the corresponding field of the $scope object.

JavaScript
var text = $scope.buttonText;

To change an option value dynamically during application flow and update the widget in response to the option change, provide the two-way binding between the required option and the corresponding $scope field. Options with two-way binding should be set within an object that is assigned to the bindingOptions field of the widget's configuration object.

HTML
<div ng-controller="Controller">
    <div dx-text-box="{ bindingOptions: { value: 'user.name' } }"></div>
</div>
JavaScript
function Controller($scope) {
    $scope.user = {
       name: "Jack"
    }
}

In the code above, the value option value is set as a path to the required field of the scope's object. At the same time, you can specify a child scope for the bindingOptions object to avoid repeating long paths. To do this, use the data field of the widget's configuration object.

HTML
<div ng-controller="Controller">
    <div dx-text-box="{ data: 'user', bindingOptions: { 'value': 'name' } }"></div>
</div>
JavaScript
function Controller($scope) {
    $scope.user = {
       name: "Jack"
    }
}

NOTE: The name of an option within the bindingOptions wrapper object should be enclosed by quotes.

Handle Events

To enable end-user interaction, most DevExtreme widgets include options that take on handler functions. These functions are performed when a certain event occurs. Clicks and other widget events can be handled in such a manner.

HTML
<div data-bind="dxButton: { clickAction: function() { alert('Clicked!') } }"></div>

If you use widgets within the DevExtreme framework, you can assign Actions to these options as well as a handler function. An action can navigate to an external or internal URL or to a specified view with or without parameters. Below are examples of how actions of different types are assigned to the Button widget's clickAction option.

HTML
<div data-bind="dxButton: { clickAction: 'http://www.example.com' }"></div>
<div data-bind="dxButton: { clickAction: '#details' }"></div>
<div data-bind="dxButton: { clickAction: '#User/{id}' }"></div>