Manipulate a Widget

The widgets supplied with the DevExtreme data visualization library are easily configured at the stage of their creation. Meanwhile, there may be the cases when you need to obtain or alternate one or more options of the already existing widget. This topic provides information on how to get access and modify widget options during the application flow.

Access a Widget

To get or set a widget option during application flow, obtain the instance object of the widget. For this purpose, use the widget's jQuery plugin. Pass the "instance" string as the parameter, as demonstrated in the code sample below.

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

Operate with Options

Once you have the instance of a widget accessed, you can get or set one or more widget options. Different techniques to perform these operations are detailed below.

jQuery Approach

Use the following techniques when working with options in code.

Get All Options

To obtain all the widget options at once, use the one of the following approaches.

  • Use the widget's option() method.
    This method returns an object containing all the options of the widget. The following code sample demonstrates how to use the option() method.

    JavaScript
    var chart = $("#chartContainer").dxChart("instance");
    var chartOptions = chart.option();
  • Use the widget's jQuery plugin.
    Pass the "option" string as a parameter.

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

Get Option Value by Name

To get the value of a particular option, perform one of the following actions.

  • Use the widget's option(optionName) method.
    Pass a full path to the field representing the required option in the configuration object as the optionName parameter. In the code sample below the value of the background | visible option of the dxRangeSelector widget is assigned to the visibleBackground variable.

    JavaScript
    var rangeSelector = $("#rangeSelectorContainer").dxRangeSelector("instance");
    var visibleBackground = rangeSelector.option("background.visible");
  • Use the widget's jQuery plugin.
    Pass the "option" string as the first parameter and a full path to the field representing the required option in the configuration object as the second parameter.

    JavaScript
    var visibleBackground = $("#rangeSelectorContainer").dxRangeSelector("option", "background.visible");
  • Get the widget's configuration object and access any of its fields in the usual way, using the dot separator.

    JavaScript
    var visibleBackground = $("#rangeSelectorContainer").dxRangeSelector("instance").option().background.visible;

Set Option Value

To set the value of a particular widget option, pick from the approaches similar to the detailed above.

  • Use the widget's option(optionName, optionValue) method.
    Pass a full path to the field representing the required option in the configuration object as the optionName parameter, and the value to be assigned - as the optionValue parameter. In the code sample below, the value of the background | visible option of the dxRangeSelector widget is set to true.

    JavaScript
    var rangeSelector = $("#rangeSelectorContainer").dxRangeSelector("instance");
    rangeSelector.option("background.visible", "true");
  • Use the widget's jQuery plugin.
    Pass the "option" string as the first parameter, a full path to the field representing the required option in the configuration object as the second parameter, and the value to be assigned - as the third parameter.

    JavaScript
    $("#rangeSelectorContainer").dxRangeSelector("option", "background.visible", "true");

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

NOTE: If you perform a chain of option changes, wrap it into the beginUpdate() and endUpdate() functions calls. It prevents the widget from unnecessary refreshings and event raisings. In this case, widget will be refreshed at the end of the transaction.

Set Several Options

You can set several options at once.

  • Use the widget's option(options) method.
    Pass the object containing the options to be changed and their new values as the options parameter. The following code sample illustrates this approach for the dxRangeSelector widget.

    JavaScript
    var rangeSelector = $("#rangeSelectorContainer").dxRangeSelector("instance");
    rangeSelector.option({
        background: {
            visible: false
        },
        sliderMarker: {
            invalidRangeColor: 'red'
        }
    });
  • Use the widget's jQuery plugin.
    Pass the configuration object as a parameter.

    JavaScript
    $("#rangeSelectorContainer").dxRangeSelector({
        background: {
            visible: false
        },
        sliderMarker: {
            invalidRangeColor: 'red'
        }
    });

    NOTE: This approach recalls the way you configure the widget. If the widget is already created in the specified container, the options defined in the passed object will be merged with those in the configuration object at the next call of the widget's plugin.

Knockout Approach

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

JavaScript
var viewModel = {
    linearGaugeOptions: {
        title: "Title",
        scale: {
            startValue: 0,
            endValue: 100,
            majorTick: {
                showCalculatedTicks: false,
                customTickValues: [0, 15, 60, 100]
            }
        },
        //...
    }),
    //...
};
HTML
<div data-bind="dxLinearGauge: linearGaugeOptions"></div>

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

JavaScript
var gaugeTitle = viewModel.linearGaugeOptions.title;

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

JavaScript
var viewModel = {
    linearGaugeOptions: {
        title: ko.observable('Title'),
        scale: ko.observable({
            startValue: 0,
            endValue: 100,
            majorTick: {
                showCalculatedTicks: false,
                customTickValues: [0, 15, 60, 100]
            }
        }),
        //...
    }),
    //...
};

viewModel.changeText = function () {
    viewModel.linearGaugeOptions.title('Title has been changed');
    viewModel.linearGaugeOptions.scale({ majorTick: {color: 'Red' } });
};

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

AngularJS Approach

When using an AngularJS approach to create a widget, some of the widget options or all of them are bound to the scope's fields. Therefore, to get an option value, get the value of the corresponding scope field.

Options with two-way binding to scope fields 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-range-selector="{ bindingOptions: { selectedRange: 'selectedRangeInScope' } }"></div>
</div>
JavaScript
function Controller($scope) {
    $scope.selectedRangeInScope = {
       startValue: 10,
       endValue: 20
    }
}

In the code above, the fields of the selectedRangeInScope object to which the dxRangeSelector's selectedRange configuration option is bound in a two-way mode will be changed once an end-user changes the currently selected range. And vice versa, the currently selected range will be changed in response to the change of the fields of the scope's selectedRangeInScope.

If you use two-way binding for an array option, by default, DevExtreme visualization widgets use the $watchCollection listener to track changes in the specified array. This way is faster than using $watch, but it updates a widget only if items are added to or removed from the array.

JavaScript
function Controller($scope) {
    $scope.chartData = [
        { day: "Monday", oranges: 3 },
        { day: "Tuesday", oranges: 2 },
        { day: "Wednesday", oranges: 3 },
        { day: "Thursday", oranges: 4 },
        { day: "Friday", oranges: 6 },
        { day: "Saturday", oranges: 11 },
        { day: "Sunday", oranges: 4 }
    ];
}
HTML
<div ng-controller="Controller">
    <div dx-chart="{
        series: {
            argumentField: 'day',
            valueField: 'oranges',
            type: 'bar'
        },
        bindingOptions: {
            dataSource: 'chartData'
        }
    }"></div>
</div>

If your application requires more deep tracking, use the extended bindingOptions syntax, which enables you to use the $watch listener for tracking changes in an array.

    <!--HTML--><div ng-controller="Controller">
    <div dx-chart="{
        series: {
            argumentField: 'day',
            valueField: 'oranges',
            type: 'bar'
        },
        bindingOptions: {
            dataSource: {
                deep: true,
                dataPath: 'chartData'
            }
        }
    }"></div>
</div>

In this case, the widget is updated even if a field of an array item is changed. To enable deep tracking, assign an object containing the following fields to the option defined within the bindingOptions object.

  • deep
    Specifies whether or not the widget uses deep tracking of changes in array items.

  • dataPath
    Contains the path to the required field of the $scope object enclosed by quotes.

Handle Events

DevExtreme widgets expose events that you can handle to perform custom actions at certain moments of the widget's life cycle. Use one of the following approaches to handle events.

Assign a Handler to a Configuration Option

To attach a handler for a certain event to a widget, use the corresponding configuration option. The options that accept event handling functions have names starting with on.

The following example demonstrates how to use a configuration option to handle an event.

JavaScript
$("#chartContainer").dxChart({
    onLegendClick: function (info) {
        // handle the "legendClick" event here
    }
});

Attach Several Handlers Using the on() Method

To attach several event handlers to a widget, use the on method of that widget. This method has two overloads.

  • on(eventName, eventHandler)
    This method allows you to attach several handlers for an event to a widget.

    JavaScript
    chart
        .on("legendClick", handler1)
        .on("legendClick", handler2)
  • on(events)
    This method allows you to subscribe to several events at one method call.

    JavaScript
    chart
        .on({
            "legendClick": handler1,
            "argumentAxisClick": handler2
        })

To unsubscribe from the events that you handled using the on() method, use the off() method. This method also has two overloads.

  • off(eventName, eventHandler)
    This method allows you to detach a particular handler from a required event.

    JavaScript
    chart
        .off("legendClick", handler1)
        .off("legendClick", handler2)
  • off(eventName)
    This method allows you to detach all handlers from a particular event.

    JavaScript
    chart
        .off("legendClick")

You can find a full list of widget events in the Events reference section.