Individual Widgets

This article describes the specifics of working with widgets unrelated to any category.

See Also

dxButton

The dxButton widget is a button, which executes a specified action when clicked.

View Demo

The action executed by a click should be passed to the onClick option.

JavaScript
var buttonOptions = {
    onClick: 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 icon 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 icon option also accepts the URL pointing to the image to be displayed on the button.

JavaScript
var buttonOptions = {
    text: 'Click me',
    icon: '/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'
}

If the button is focused, an end-user can use the Enter or Space key to perform a click.

dxDeferRendering

The dxDeferRendering widget is a container element whose content is rendered at a specified moment. This widget is helpful on pages where a portion of the content is loaded later than the remaining part, e.g., while waiting for data from a server, or where the content is so "heavy" that its rendering takes a long time. To control the page content loading process, place some of the page content within the dxDeferRendering widget and specify when this content is allowed to be rendered. While waiting for the rendering moment, a load indicator or certain custom content can be displayed on the page.

Specify a Moment for Rendering

To specify the moment when the content located within the dxDeferRendering widget must be rendered, use the widget's renderWhen option. In the code below, the dxList widget is rendered when its data comes from a remote location.

HTML
<div id="deferRendering">
    <div id="myList" style="margin: 10px;"></div>
</div>
JavaScript
$(function(){
    var readyToRender = $.Deferred();
    var listDataSource = new DevExpress.data.DataSource({ store: [] });
    $.get("/remoteFolder/states.txt", function (data) {
        for (var i = 0; i < data.length; i++) {
            listDataSource.store().insert(data[i]);
        }
        listDataSource.load().done(function () {
            $("#myList").dxList({
                dataSOurce: listDataSource
            });
            readyToRender.resolve();
        });
    }, "json");

    $("#deferRendering").dxDeferRendering({
        renderWhen: readyToRender.promise(),
        animation: 'fade',
        showLoadIndicator: true
    });
});
Angular Approach
HTML
<div dx-defer-rendering="{
        renderWhen: modelIsReady,
        animation: 'fade',
        showLoadIndicator: true
    }">
    <div id="myList" style="margin: 10px;" dx-list="{
        dataSource: listDataSource
    }"></div>
</div>
JavaScript
var modelIsReady = $.Deferred();
var myApp = angular.module('myApp', ['dx']);
myApp.controller("demoController", function ($scope) {
    $.get("/remoteFolder/states.txt", function (data) {
        for (var i = 0; i < data.length; i++) {
            $scope.listDataSource.store().insert(data[i]);
        }
        $scope.listDataSource.load().done(function () {
            modelIsReady.resolve();
        });

    }, "json");
    $scope.modelIsReady = modelIsReady.promise();
    $scope.listDataSource = new DevExpress.data.DataSource({ store: [] });
});
angular.element(document).ready(function () {
    angular.bootstrap(document, ['myApp']);
});
Knockout Approach
HTML
<div data-bind="dxDeferRendering: {
        renderWhen: modelIsReady,
        animation: 'fade',
        showLoadIndicator: true
    }">
    <div id="myList" style="margin: 10px;" data-bind="dxList: {
        dataSource: listDataSource
    }"></div>   
</div>
JavaScript
var modelIsReady = $.Deferred();
$.get("/remoteFolder/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        myViewModel.listDataSource.store().insert(data[i]);
    }
    myViewModel.listDataSource.load().done(function () {
        modelIsReady.resolve();
    });

}, "json");
var myViewModel = {
    listDataSource: new DevExpress.data.DataSource({ store: [] }),
    modelIsReady: modelIsReady.promise()
};
ko.applyBindings(myViewModel);

Indicate Loading State

While waiting for the moment when the widget's content is allowed to be rendered, you can display some indication so that end users are aware that the content is being loaded. For this purpose, use one of the following techniques.

  • Show loading indicator.
    Set the dxDeferRendering widget's showLoadIndicator option to true.

  • Add custom content that will indicate the loading state of the required content.
    Apply the dx-visible-while-pending-rendering class to the custom content and the dx-invisible-while-pending-rendering class to the content to be rendered when allowed. The elements with the dx-visible-while-pending-rendering class will be visible until the elements with the dx-invisible-while-pending-rendering class are rendered.

Animate Content Showing

To specify the animation to be used for showing widget content, use the animation option. You can pass a configuration object defining the required animation or the name of one of the registered animations.

The dxDeferRendering widget uses the TransitionExecutor object to animate the content. The Transition Executor enables you to perform staggered animation when elements with a similar selector are animated using the specified animation one after another with a specified delay (see how list items are animated in the simulator to the right). Use the following options so that a staggered animation is performed under the elements within your dxDeferRendering widget.

  • Set the dxDeferRendering widget's staggerItemSelector option.
    The elements with the specified selector that are found within the the dxDeferRendering widget content will be animated using the staggered animation.

  • Set the staggerDelay option within the animation configuration that is passed as the animation option to the dxDeferRendering widget.
    The elements will be animated with the specified delay.

Handle Rendering

You can perform custom actions after the dxDeferRendering widget's content is rendered. For this purpose, use the following configuration options of the widget:

dxLoadIndicator

The dxLoadIndicator widget is a UI element displayed when the loading process is being executed.

View Demo

You can control widget visibility using the visible option.

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

In MVVM Approach, provide two-way binding between the visible option and the corresponding variable.

Angular Approach
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>
Knockout Approach
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>

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.

View Demo

dxResizable

The dxResizable widget is a container element whose size can be changed by an end user.

The boundary sizes are specified using the minHeight, minWidth, maxHeight and maxWidth options.

JavaScript
var resizableOptions = {
    minWidth: 200,
    maxWidth: 500,
    minHeight: 100,
    maxHeight: 500
}

The current width and height can be accessed using the height and width options.

The handles option enables you to specify which borders of the widget element are used as handles. This option accepts the "all", "top", "bottom", "left", "right" values. You can use several values separated by space.

JavaScript
var resizableOptions = {
    handles: "left right bottom"
}

If right and bottom borders are used as handles, a triangular handle is displayed at their junction.

dxScrollView

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

View Demo

End-user Gestures

The widget supports the "Pull Down to Refresh" gesture. Assign the required function to the onPullDown option to perform a custom action after the widget is scrolled to the top and pulled down. When the function is called, 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 = {
    onPullDown: 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 = {
    onPullDown: 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 onReachBottom 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 = {
    onReachBottom: reachedBottom,
    reachBottomText: 'Loading...'
}

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

JavaScript
var scrolled = function(){
    alert("The widget is scrolled.");
}
var scrollViewOptions = {
    onScroll: 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);
}

Keyboard Support

An end-user can use the following keys to interact with the widget.

  • Up/down arrow
    Scrolls content up/down.

  • Page up/down
    Scrolls content up/down by a page.

  • Home/End
    Scrolls content to the top/bottom.

dxSlideOutView

The dxSlideOutView widget allows you to slide-out the current view to reveal a custom menu.

This widget is similar to the dxSlideOut widget. In its simplest form, it consists of a panel that slides out to reveal a menu. However, unlike the dxSlideOut widget, dxSlideOutView does not hold items. It contains only content and menu panels, which enable you to use any collection widget as a menu.

Specify the widget content

Implement a function that renders the widget content and pass it to the contentTemplate option.

HTML
<div id="mySlideOutView"></div>
JavaScript
$("#mySlideOutView").dxSlideOutView({
    contentTemplate: function(contentElement){
        contentElement.append("<h1>My Slide Out View</p>");
        contentElement.append("<p>Selected item: <b id='selecteItem'>none</b></p>");
        var showMenuButton = $("<div>");
        contentElement.append(showMenuButton);
        showMenuButton.dxButton({
            text: 'Show menu',
            onClick: function(){
                $("#mySlideOutView").dxSlideOutView("instance").showMenu();
            }
        })
    },
    menuTemplate: function(menuElement){
        . . .
    }
});

In MVVM approach, create a content template and pass its name or element to the contentTemplate option.

Angular Approach
HTML
<div dx-slide-out-view="{ contentTemplate: 'slideOutViewContent', menuTemplate: 'slideOutViewMenu' }">
    <div data-options="dxTemplate: { name: 'slideOutViewContent' }">
        <h1>My Slide Out View</h1>
        <p>Selected item: <b>{{selectedItem}}</b></p>
        <div dx-button="{ text: 'Show menu', onClick: showMenu }"></div>
    </div>
    <div data-options="dxTemplate: { name: 'slideOutViewMenu' }">
        . . .
    </div>
</div>
JavaScript
myApp.controller("demoController", function ($scope) {
    $scope.selectedItem = 'none';
    $scope.showMenu = function(){
        . . .
    }
});
Knockout Approach
HTML
<div data-bind="dxSlideOutView: { contentTemplate: 'slideOutViewContent', menuTemplate: 'slideOutViewMenu' }">
    <div data-options="dxTemplate: { name: 'slideOutViewContent' }">
        <h1>My Slide Out View</h1>
        <p>Selected item: <b data-bind="text: selectedItem"></b></p>
        <div data-bin="dxButton: { text: 'Show menu', onClick: showMenu }"></div>
    </div>
    <div data-options="dxTemplate: { name: 'slideOutViewMenu' }">
        . . .
    </div>
</div>
JavaScript
var myViewModel = {
    selectedItem: ko.observable('none'),
    showMenu: function(){
        . . .
    }
}
ko.applyBindings(myViewModel);
See Also

Adjust the widget menu

The dxSlideOutView widget can use any collection widget as a menu. Implement a function that renders the menu panel and pass it to the menuTemplate option.

NOTE: The widget requires you to append a collection widget to the menu panel element within the rendering function.

HTML
<div id="mySlideOutView"></div>
JavaScript
$("#mySlideOutView").dxSlideOutView({
    contentTemplate: function(contentElement){
        . . .
    },
    menuTemplate: function(menuElement){
        menuElement.css("height", "100%");
        var menuWidget = $('<div>');
        menuElement.append(menuWidget);
        menuWidget.dxList({
            items: ['Item 1', 'Item 2', 'Item 3' ],
            onItemClick: function(itemData, itemIndex, itemElement){
                //Process item click
            }
        });
    }
});

In MVVM Approach, create a content template and pass its name or element to the menuTemplate option.

Angular Approach
HTML
<div dx-slide-out-view="{ contentTemplate: 'slideOutViewContent', menuTemplate: 'slideOutViewMenu' }">
    <div data-options="dxTemplate: { name: 'slideOutViewContent' }">
        . . .
    </div>
    <div data-options="dxTemplate: { name: 'slideOutViewMenu' }" style="height: 100%;">
        <div dx-list="{ items: menuItems, onItemClick: itemClicked }"></div>
    </div>
</div>
JavaScript
myApp.controller("demoController", function ($scope) {
    $scope.menuItems = ['Item 1', 'Item 2', 'Item 3' ];
    $scope.itemClicked = function(itemData, itemIndex, itemElement){
        //Process item click
    };
});
Knockout Approach
HTML
<div data-bind="dxSlideOutView: { contentTemplate: 'slideOutViewContent', menuTemplate: 'slideOutViewMenu' }">
    <div data-options="dxTemplate: { name: 'slideOutViewContent' }">
        . . .
    </div>
    <div data-options="dxTemplate: { name: 'slideOutViewMenu' }" style="height: 100%;">
        <div data-bind="dxList: { items: menuItems, onItemClick: itemClicked }"></div>
    </div>
</div>
JavaScript
var myViewModel = {
    menuItems: ['Item 1', 'Item 2', 'Item 3' ],
    itemClicked: function(itemData, itemIndex, itemElement){
        //Process item click
    }
}
ko.applyBindings(myViewModel);
See Also

Control menu visibility

To show or hide the menu, call the showMenu() or hideMenu() methods respectively. To access a widget method, obtain the widget instance first.

JavaScript
var showSlideOutViewMenu = function(){
    var slideOutView = $("#mySlideOutView").dxSlideOutView('instance');
    slideOutView.showMenu();
}
var showSlideOutViewMenu = function(){
    var slideOutView = $("#mySlideOutView").dxSlideOutView('instance');
    slideOutView.hideMenu();
}

Also you can use the menuVisible option to show or hide the menu depending on the variable value. In jQuery approach, set the option value using the option(optionName, optionValue) method. In MVVM approach, provide two-way binding between the configuration option and the corresponding field of a view or application model.

Angular Approach
HTML
<div dx-slide-out-view="{
    bindingOptions: {
        menuVisible: 'slideOutViewMenuVisible'
    }
}">
    . . .
</div>
JavaScript
myApp.controller("demoController", function ($scope) {
    $scope.slideOutViewMenuVisible = false;
    $scope.showMenu: function(){
        $scope.slideOutViewMenuVisible = true;
    };
    $scope.hideMenu: function(){
        $scope.slideOutViewMenuVisible = false;
    };
});
Knockout Approach
HTML
<div data-bind="dxSlideOutView: {
        menuVisible: slideOutViewMenuVisible
    }">
    . . .
</div>
JavaScript
var myViewModel = {
    slideOutViewMenuVisible: ko.observable(false),
    showMenu: function(){
        this.slideOutViewMenuVisible(true);
    },
    hideMenu: function(){
        this.slideOutViewMenuVisible(false);
    }
}
ko.applyBindings(myViewModel);

Menu position

To specify the current menu position use the menuPosition option. This option accepts two values: normal and inverted. By default, menuPosition is set to normal. Normally, the menu is located at the left side of the screen. To display the menu at the opposite side assign 'inverted' to this option.

If you need to switch the display of the widget to right-to-left, enable the rtlEnabled option. When the option value is true, the text flows from right to left, and the layout the component's elements is reversed. Note, in a right-to-left representation, normal position of the menu is the right side of the screen. Assign 'inverted' to the menuPosition option to show the menu on the left side.

JavaScript
var slideoutOptions = {
    ...
    rtlEnabled: true,
    menuPosition: 'inverted'
}