Editor Widgets

This article describes common principles of working with widgets intended to specify Boolean, numeric, string values, etc.

Common Tasks

When working with an editor widget, you can often encounter tasks common for all editor widgets. This section describes the most important common tasks, such as getting and setting the widget value and handling the value change event.

Get And Set a Widget Value

The value of an editor widget is held in the value configuration option. You can use any of the following approaches to get and modify widget value.

jQuery Approach

To specify the initial value for the widget, assign it to the value option within the widget constructor.

JavaScript
$("#textBoxContainer").dxTextBox({ value: "My Text" });

To get the option value at runtime, get the widget instance and call its option(optionName) method passing "value" as a parameter.

JavaScript
var textBox = $("#textBoxContainer").dxTextBox("instance");
var textBoxValue = textBox.option("value");

To modify the option value at runtime, call the option(optionName, optionValue) method of the widget instance. The optionValue parameter should take on the "value" string, while the optionValue parameter ought to take on the required value.

JavaScript
var textBox = $("#textBoxContainer").dxTextBox("instance");
var textBoxValue = textBox.option("value", "New Text");

Knockout Approach

To specify the initial value for the widget using the Knockout approach, add a configuration object containing the value property to the required Knockout binding.

HTML
<div data-bind="dxTextBox: { value: 'My Text' }"></div>

If you need to get or set the widget value at runtime, declare an observable variable and associate it with the value configuration option of the widget.

JavaScript
var textBoxValue = ko.observable("My Text");
HTML
<div data-bind="dxTextBox: { value: textBoxText }"></div>

In this case, you can easily get the widget value by getting the observable variable value.

JavaScript
var text = textBoxValue();

To set widget value, assign a new value to this variable.

JavaScript
textBoxValue("New Text");

Angular Approach

To specify the initial widget value using the Angular approach, add the value property to the widget configuration object and assign the required value to this property.

HTML
<div dx-text-box="{ value: 'My Text' }"></div>

If you need to get or set the widget value at runtime, provide two-way binding between the value option and the corresponding $scope field.

JavaScript
function Controller($scope) {
    $scope.textBoxValue = "My Text";
}
HTML
<div ng-controller="Controller">
    <div dx-text-box="{ bindingOptions: { 'value': 'textBoxValue' }}"></div>
</div>

In this case, widget value is held in the $scope.textBoxValue variable. To modify the widget value, simply assign the required value to this variable.

Handle The Value Change Event

You can use any of the following approaches to handle the widget value change.

jQuery Approach

If you use the jQuery approach, the editor widgets require you to handle the value change event to timely process a new widget value.

Pass the event handler function to the valueChangeAction option when creating the widget...

JavaScript
var valueChangeHandler = function(value){
    //The "value" parameter holds the new widget value.
}
$("textBoxContainer").dxTextBox({
    valueChangeAction: valueChangeHandler
});

...or at runtime.

var myTextBox = $("textBoxContainer").dxTextBox("instance");
myTextBox.option("valueChangeAction", valueChangeHandler);

Note that the handler function includes the value parameter that takes on the new widget value.

Knockout Approach

If you use the Knockout approach, you should use observable variables to timely update values depending on the widget value. But in some cases you may need to process the value change. You can either pass the required handler function to the valueChangeAction option,

JavaScript
var text = ko.observable("");
var valueChangeHandler = function(value){
    alert("The text box value has been changed to " + value);
}
HTML
<div data-bind = dxTextBox: { value: text, valueChangeAction: valueChangeHandler }></div>

or you may subscribe the text observable variable change event.

JavaScript
var text = ko.observable("");
text.subscribe(function(value){
    alert("The text box value has been changed to " + value);
});
HTML
<div data-bind = dxTextBox: { value: text }></div>

Angular Approach

Similarly to the Knockout approach, the Angular approach provides two ways to handle the widget value change. You can either pass the required handler function to the valueChangeAction option,

JavaScript
function Controller($scope) {
    $scope.text = "";
    $scope.valueChangeHandler = function(value) {
        alert("The text box value has been changed to " + value);
    }
}
HTML
<div ng-controller="Controller">
    <div dx-text-box="{ bindingOptions: { 'value': 'text' }, valueChangeAction: valueChangeHandler }"></div>
</div>

or you may use the $watch listener for the text property of the $scope object.

JavaScript
function Controller($scope) {
    $scope.text = "";
    $scope.$watch("text", function(newValue, oldValue) {
        alert("The text box value has been changed from " + oldValue + " to " + newValue);
    });
}
HTML
<div ng-controller="Controller">
    <div dx-text-box="{ bindingOptions: { 'value': 'text' }}"></div>
</div>

Text Editors

The following editor widgets also support the text editor functionality. Text editors are intended to display a string, a numeric or date/time value and allow a user to edit this value.

These widgets are based on the input HTML element. In addition to editor specific options, they include options that enable you to specify handlers for events of the underlying input element (enterKeyAction, focusInAction, focusOutAction, etc.).

JavaScript
var myViewModel = {
    focusInHandler: function() {
        alert("The widget has got focus");
    }
};
ko.applyBindings(myViewModel);
HTML
<div data-bind="dxTextBox: { focusInAction: focusInHandler }"></div>

Text editor widgets support the read-only state, which can be enabled or disabled using the readOnly configuration option. You can also specify the widget placeholder text using the placeholder option. In addition, text editor widgets can show the Clear button that clears the widget value. Use the showClearButton option to specify button visibility.

List of Editor Widgets

The following DevExtreme UI widgets are related to the collection containers category.

dxAutocomplete

The dxAutocomplete widget is a text editor that suggests ways of completing the text being typed.

In addition to common Editor functionality, the dxAutocomplete widget implements Collection Container widget functionality.

Specifying Search parameters

The widget displays only items satisfying the specified criterion. The widget can use the contains or startswith binary operation to filter data items. Assign the required operation name to the searchMode option to specify the search criterion. The default search mode is contains.

By default, the dxAutocomplete widget displays the list of available completions when an end-user types in at least one character. Use the minSearchLength option to change this behavior. This option specifies the minimum number of characters that must be entered into the search box to begin a search.

You can also specify the time period in milliseconds before a search is executed using the searchTimeout option.

JavaScript
var autocompleteOptions = {
    dataSource: autocompleteData,
    searchMode: 'startswidth',
    minSearchLength: 3,
    searchTimeout: 500
}

Tweak For an Item Structure

If a data source item is a string value, the widget compares the entered text with this value to filter data items. If an item is an object, you should specify which property will be used for comparison. Assign the required property name to the valueExpr option.

JavaScript
var autocompleteData = [
    { "name": "Alabama", "capital": "Montgomery" },
    { "name": "Alaska", "capital": "Juneau" },
    { "name": "Arizona", "capital": "Phoenix" }
    . . .
]
var autocompleteOptions = {
    dataSource: autocompleteData,
    valueExpr: 'name'
}

dxCalendar

The dxCalendar widget displays a calendar and enables a user to select the required date within the specified date range. You can access the selected date using the value option.

The date range is specified by the min and max options, which take on a Date object representing the earliest and latest date respectively.

JavaScript
var calendarOptions = {
    min: new Date(2000,1,1),
    max: new Date(2020,12,31)
}

The widget enables you to specify which day of the week is to be displayed in the first column. Pass the 0 based index of the required day to the firstDayOfWeek option.

  • 0 - Sunday
  • 1 - Monday
  • 2 - Tuesday
  • 3 - Wednesday
  • 4 - Thursday
  • 5 - Friday
  • 6 - Saturday
JavaScript
var calendarOptions = {
    firstDayOfWeek: 1
}

dxCheckBox

The dxCheckBox widget allows a user to check or uncheck an option, and perform a specified action when widget value changes. The widget state can be accessed using the value option, which is set to true if the widget is checked and to false if the widget is unchecked.

In addition to the checked and unchecked states, the widget supports the indeterminate state applied when the value option is set to undefined.

JavaScript
var checkBoxOptions = {
    value: undefined
}

dxColorPicker

The dxColorPicker widget allows a user to specify a color value manually or pick it out from the drop-down editor.

In addition to common Editor functionality, the dxColorPicker widget supports options common for Overlay widgets, which affect popup window behavior.

Access the selected color

You can get or set the selected color using the value option. You can use any CSS compatible color format ("#FF0000", "Red", "rgb(255, 0, 0)") to specify the current color. If a user selects a color using the popup window, the selected color is displayed in the hexadecimal format ("#FF0000").

JavaScript
var colorPickerOptions = {
    value: "#FF9000"
}

Enable alpha channel support

By default, the widget enables an end-user to select non-transparent colors. Set the editAlphaChannel option to true to enable an end-user to specify a color containing the alpha channel component.

JavaScript
var colorPickerOptions = {
    value: "rgba(255, 144, 0, 0.3)",
    editAlphaChannel: true
}

If this option is set to true, the widget displays the selected color in the "rgba(255, 144, 0, 0.3)" format.

Specify button text

The widget enables you to specify a custom text for the OK and Cancel buttons displayed at the bottom of the popup window using the applyButtonText and cancelButtonText options respectively.

JavaScript
var colorPickerOptions = {
    applyButtonText: "Apply color",
    cancelButtonText: "Close window"
}

The string representation of the selected color can be accessed using the value option.

dxDateBox

The dxDateBox widget displays the date and time value in a specified format, and enables a user to pick the required date/time value within the specified range.

The date time range is specified by the min and max options, which take on a Date object representing the earliest and latest date and time respectively.

JavaScript
var dateBoxOptions = {
    min: new Date(2000,1,1),
    max: new Date(2020,12,31)
}

Besides the date information displayed by default, the dxDateBox widget can display time information, and the date and time simultaneously depending on the format option, which can take on one of the following values.

  • date
    The widget displays only the date.

  • time
    The widget displays only the time.

  • datetime
    The widget displays both the date and the time.

JavaScript
var dateBoxOptions = {
    format: "datetime"
}

If the widget format option is set to "date", the widget enables an end-user to pick the required date using the drop-down dxCalendar widget. Set the useCalendar option to true to enable this feature. You can specify inner dxCalendar widget options using the calendarOptions option, which takes on a dxCalendar configuration object.

The formatString option specifies the Globalize date format used to display data picked from the calendar. In addition, you can specify whether or not the widget hides the drop-down calendar if widget value has been changed using the closeOnValueChange option.

JavaScript
var dateBoxOptions = {
    useCalendar: true,
    calendarOptions: {
        //options of the inner dxCalendar widget
    }
    formatString: "D",
    closeOnValueChange: true
}

dxLookup

The dxLookup widget allows an end-user to select predefined values from a lookup window. Refer to the dxLookup guide for more information.

dxNumberBox

The dxNumberBox widget allows a user to enter a number within a range specified using the min and max options.

JavaScript
var numberBoxOptions = {
    min: 0,
    max: 100
}

To enable an end-user to increase or decrease widget value using spin buttons, assign true to the showSpinButtons option. The step option specifies a number added to or subtracted from the widget value on a single spin button click.

JavaScript
var numberBoxOptions = {
    showSpinButtons: true,
    step: 10
}

dxRangeSlider

The dxRangeSlider widget allows a user to specify a range of numeric values.

The selected range is marked by the start and end options, which specify the minimum and maximum range values respectively. The available range boundaries are specified by the min and max options.

JavaScript
var rangeSliderOptions = {
    min: 0,
    max: 100,
    start: 30,
    end: 70
}

The step option specifies the difference between neighboring widget values.

JavaScript
var sliderOptions = {
    step: 10
}

The dxRangeSlider widget can display labels for boundary values. The label options are specified using the label option, which takes on an object containing the following properties.

  • format
    Specifies a format for labels. For more information, refer to the format option description.

  • position
    Takes on the 'top' or 'bottom' values, which specify whether labels are located over or under the scale respectively.

  • visible
    Specifies whether or not range slider labels are visible.

JavaScript
var rangeSliderOptions = {
    label: {
        visible: true,
        position: 'bottom',
        format: function(value) {
            return value + ' units';
        }
    }
}

The widget can also display a tooltip for the slider. Tooltip options are specified using the tooltip option, which takes an object containing the following properties.

  • enabled
    Specifies whether or not the tooltip is enabled.

  • format
    Specifies a format for the tooltip. For more information, refer to the format option description.

  • position
    Takes on the 'top' or 'bottom' values, which specify whether the tooltip is located over or under the slider respectively.

  • showMode
    Takes on the 'onHover' or 'always' values, which specify whether the widget displays the tooltip only when the pointer is over the slider or always, respectively.

    var rangeSliderOptions = { tooltip: { enabled: true, position: 'bottom', showMode: 'always', format: function(value) { return value + ' units'; } } }

dxSelectBox

The dxSelectBox widget is an editor that accepts values from the list specified by the dataSource option.

In addition to the common Editor functionality, the dxSelectBox widget implements the Collection Container widget functionality.

Tweak For an Item Structure

If a data source item is a string value, the widget uses this value to display the item in the drop-down list and in the text field. This string value is also held in the value option if the item is selected. If a data source item is an object, you should specify which property will be used to display the item and which one will be held in the value option. The displayExpr option specifies the property name whose value will be displayed in the drop-down list and in the text field. To specify the property whose value is held in the value option, assign the required property name to the valueExpr option.

JavaScript
var selectBoxData = [
    { "name": "Alabama", "capital": "Montgomery" },
    { "name": "Alaska", "capital": "Juneau" },
    { "name": "Arizona", "capital": "Phoenix" }
    . . .
]
var selectBoxOptions = {
    dataSource: selectBox0Data,
    valueExpr: 'capital',
    displayExpr: 'name'
}

Use the displayValue option to access the text displayed by the text field.

Multi-selection Support

By default, the widget can take only a single value accessed using the value option. To enable an end-user to select multiple values, set the multiSelectEnabled option to true.

JavaScript
var selectBoxOptions = {
    dataSource: selecBoxData,
    multiSelectEnabled: true
}

In this case, you can access the selected values using the values option.

dxSlider

The dxSlider widget allows a user to specify a numeric value within a specified range. The slider range boundaries are specified by the min and max options.

JavaScript
var sliderOptions = {
    min: 0,
    max: 100
}

The step option specifies the difference between neighboring widget values.

JavaScript
var sliderOptions = {
    step: 10
}

The dxSlider widget can display labels for the boundary values. The label options are specified using the label option, which takes on an object containing the following properties.

  • format
    Specifies a format for labels. For more information, refer to the format option description.

  • position
    Takes on the 'top' or 'bottom' values, which specify whether labels are located over or under the scale respectively.

  • visible
    Specifies whether or not slider labels are visible.

JavaScript
var sliderOptions = {
    label: {
        visible: true,
        position: 'bottom',
        format: function(value) {
            return value + ' units';
        }
    }
}

The widget can also display a tooltip for the slider. Tooltip options are specified using the tooltip option, which takes on an object containing the following properties.

  • enabled
    Specifies whether or not the tooltip is enabled.

  • format
    Specifies a format for the tooltip. For more information, refer to the format option description.

  • position
    Takes on the 'top' or 'bottom' values, which specify whether the tooltip is located over or under the slider respectively.

  • showMode
    Takes on the 'onHover' or 'always' values, which specify whether the widget shows the tooltip only when the pointer is over the slider or always, respectively.

    var sliderOptions = { tooltip: { enabled: true, position: 'bottom', showMode: 'always', format: function(value) { return value + ' units'; } } }

dxSwitch

The dxSwitch widget is a switch that can have an on or off state. The widget provides two options in addition to common editor widget functionality. The onText and offText options specify the text displayed by the widget when it is in the enabled and disabled states respectively.

JavaScript
var switchOptions = {
    onText: 'On',
    offText: 'Off'
}

Note that the widget does not use text values to identify the state in the iOS and Windows Phone themes.

dxTextArea

The dxTextArea widget enables a user to enter and edit a multi-line text.

The widget allows you to limit the number of typed characters to the maxLength option value.

JavaScript
var textAreaOptions = {
    maxLength: 100
}

dxTextBox

The dxTextBox widget enables a user to enter and edit a single line of text.

The widget allows you to limit the number of typed characters to the maxLength option value.

JavaScript
var textBoxOptions = {
    maxLength: 10
}

You can also specify the text box mode using the mode option. This option passes the value to the mode attribute of the underlying <input> element. This option can take on values supported by the mode attribute of the <input> element.

JavaScript
var textBoxOptions = {
    mode: 'password'
}