Individual Widgets

This article describes the specifics of working with widgets unrelated to any category. Refer to the Create a Widget and Manipulate a Widget guides for the information on the common tasks you will encounter when working with any widget.

dxButton

The dxButton widget is a button, which executes a specified action when clicked. The action executed by a click should be passed to the clickAction option.

JavaScript
var buttonOptions = {
    clickAction: function() {
        alert("The button is clicked");
    }
}

The widget can display a text and an icon on the button. The text is specified using the text option. You can specify the button icon using either the icon option or iconSrc option.

You can pass the name of an existing icon from the built-in icon library or a custom icon name to the icon option.

JavaScript
var buttonOptions = {
    text: 'Click me',
    icon: 'home'
}

The iconSrc option specifies the URL pointing to the image to be displayed on the button.

JavaScript
var buttonOptions = {
    text: 'Click me',
    iconSrc: '/images/icons/buttonIcon.png'
}

In addition, you can specify the type of the displayed button using the type option, which accepts any of the following values: 'normal', 'default', 'back', 'danger', 'success'.

JavaScript
var buttonOptions = {
    text: 'Return',
    type: 'back'
}

dxLoadIndicator

The dxLoadIndicator widget is a UI element displayed when the loading process is being executed. You can control widget visibility using the visible option. You can use the jQuery, Knockout or Angular approach to modify the visible option at runtime.

  • jQUery
    Get the widget instance and call the option(optionName, optionValue) method to update the visible option value.

    JavaScript
    var showLoadIndicator = function(){
        var loadIndicator = $("#loadIndicatorContainer").dxLoadIndicator("instance");
        loadIndicator.option("visible", true);
    }
    var hideLoadIndicator = function(){
        var loadIndicator = $("#loadIndicatorContainer").dxLoadIndicator("instance");
        loadIndicator.option("visible", false);
    }
  • Knockout
    Declare an observable variable and pass it to the visible option.

    JavaScript
    var viewModel = {
        indicatorVisible: ko.observable(false);
        showLoadIndicator: function(){
            this.indicatorVisible(true);
        },
        hideLoadIndicator: function(){
            this.indicatorVisible(false);
        }
    }
    ko.applyBindings(viewModel);
    HTML
    <div data-bind="dxLoadIndicator: { visible: indicatorVisible }"></div>
  • Angular
    Declare a $scope object field and provide two-way binding between the visible option and the declared field.

    JavaScript
    function Controller($scope) {
        $scope.visible = false;
        $scope.showLoadIndicator = function() {
            $scope.visible = true;
        };
        $scope.hideLoadIndicator = function() {
            $scope.visible = false;
        }
    }
    HTML
    <div ng-controller="Controller">
        <div dx-load-indicator="{ bindingOptions: { 'visible': 'indicatorVisible' } }"></div>
    </div>

You can use a custom image as an indicator instead of the standard indicator icons. Assign the image path to the indicatorSrc option to specify the indicator image.

JavaScript
var loadIndicatorOptions = {
    indicatorSrc: '/Content/Images/loadindicator-demo.gif'
}

dxMap

The dxMap widget displays a map at the specified location using a specified zoom level. It can also display markers and routes. Refer to the dxMap widget guide for more information.

dxScrollView

The dxScrollView widget is a wrapper for scrollable content. The scrollable content is placed inside the dxScrollView container.

End-user Gestures

The widget supports the "Pull Down to Refresh" gesture. Assign the required function to the pullDownAction option to perform a custom action after the widget is scrolled to the top and pulled down. When the action is executed, the widget gets into the "refreshing" state. You should call the release() method at the end of the action to release the widget. You can access the widget instance using the component property of the action parameter object.

JavaScript
var scrollViewOptions = {
    pullDownAction: pulledDown
}
var pulledDown = function(actionOptions){
    alert("The widget is pulled down.");
    actionOptions.component.refresh();
}

You can also specify the text displayed when the widget is about to be pulled down and when it is pulled down using the pullingDownText and pulledDownText options respectively. The refreshingText option specifies the text displayed while the widget is being refreshed.

JavaScript
var scrollViewOptions = {
    pullDownAction: pulledDown,
    pullingDownText: 'Pull down to refresh',
    pulledDownText: 'Release to refresh',
    refreshingText: 'Refreshing...'
}

If an end-user scrolls the widget to the bottom, the widget executes the function passed to the reachBottomAction option and displays the text assigned to the reachBottomText option.

JavaScript
var reachedBottom = function(){
    alert("The widget is scrolled to the bottom.");
    actionOptions.component.refresh();
}
var scrollViewOptions = {
    reachBottomAction: reachedBottom,
    reachBottomText: 'Loading...'
}

You can also pass a function to the scrollAction option to process each scroll gesture.

JavaScript
var scrolled = function(){
    alert("The widget is scrolled.");
}
var scrollViewOptions = {
    scrolledAction: scrolled
}

Scrolling Options

By default the widget can be scrolled only vertically. Use the direction option to enable scrolling in vertical, horizontal or in both directions. The showScrollBar option specifies whether the scrollbars are visible or not.

JavaScript
var scrollViewOptions = {
    direction: 'both'
}

Programmatic Scrolling

The dxScrollView widget includes multiple methods used to scroll the widget to the required position. Refer to the widget API reference for the information on these methods.

JavaScript
var scrollToTargetPosition(target){
    var scrollView = $("#scrollViewContainer").dxScrollView("instance");
    scrollView.scrollTo(target);
}