Create a Widget

In this article you will learn how to create and configure DevExtreme UI widgets using jQuery, Knockout and Angular approach. It also details how to link the required libraries, specify themes and add a widget to a page.

Link Libraries and Themes

To use DevExtreme UI widgets in your application, add a link to a widget library on the main page of the application. DevExtreme UI widgets require the application to include links to jQuery and Globalize libraries. If you use the Knockout or Angular approach, you should also add a link to the Knockout (knockout-3.1.0.js) or Angular (angular.js and angular-sanitize.js) libraries respectively. Links to these libraries must be placed over the link to a widget library as shown in the example below.

HTML
<!DOCTYPE html>
<html>
    <head>
        <!-- libraries required by UI widgets-->
        <script src="/js/jquery-2.1.1.min.js"></script>
        <script src="/js/globalize.min.js"></script>

        <!--Knockout library-->
        <!--script src="/js/knockout-3.1.0.js"></script-->

        <!--Angular libraries-->
        <!--script src="/js/angular.js"></script-->
        <!--script src="/js/angular-sanitize.js"></script-->

        <!-- widgets library -->
        <script src="/js/dx.phonejs.js"></script>
    </head>
    <body>

    </body>
</html>

Link Themes

Whatever platform your mobile application is designed for, UI widgets can look and behave natively on it. DevExtreme includes themes for all popular platforms and desktop web applications. Common style settings are stored in the dx.common.css stylesheet, which should always be linked to the application. Theme specific style settings are stored in a .css file with the appropriate name. For example, the dx.ios.default.css.

HTML
<link rel="stylesheet" type="text/css" href="/css/dx.common.css" />
<link rel="stylesheet" type="text/css" href="/css/dx.ios.default.css" />

NOTE: the application should include a link to only one theme stylesheet. Otherwise widgets can be displayed incorrectly.

If you use UI widgets within a DevExtreme application, the application automatically selects the appropriate theme depending on the platform it is working in. Therefore, a DevExtreme application should include links to stylesheets for all desired themes. Note that a stylesheet link looks like the following in this case.

HTML
<link rel="dx-theme" data-theme="ios.default" href="/css/dx.ios.default.css" />

Widget Libraries

The majority of DevExtreme UI widgets support both mobile and desktop themes. There are, however, a handful of widgets designed to support either only mobile (dxActionSheet, dxDateBox, dxDropDownMenu, dxList, dxNavBar, dxTileView) or desktop (dxColorPicker, dxDataGrid) themes.

For this reason, DevExtreme comes with several different libraries.

  • dx.phonejs.js - includes widgets that support mobile themes
  • dx.webappjs.js - includes widgets that support desktop themes
  • dx.all.js - includes all widgets, including data visualization widgets

Note that the widgets supporting both mobile and desktop themes are included in all mentioned libraries.

Library Sources

Manually Installed Libraries

Download a zip-archive of the DevExtreme Web Development or Mobile Development kit with the latest version of the required library. Unpack it and place the Lib folder contents in the folder with your application. In this instance, the links you have to add to your application will be:

HTML
<!--Scripts-->
<script src="/js/jquery-2.1.1.min.js"></script>
<script src="/js/globalize.min.js"></script>
<!--script src="/js/knockout-3.1.0.js"></script-->
<!--script src="/js/angular.js"></script-->
<!--script src="/js/angular-sanitize.js"></script-->
<script src="/js/dx.phonejs.js"></script>

<!--Styles-->
<link rel="stylesheet" type="text/css" href="/css/dx.common.css" />
<link rel="stylesheet" type="text/css" href="/css/dx.ios.default.css" />

Libraries Stored on CDN

You do not always have to deliver DevExtreme libraries with a published site. There are cases when the best option is to load these libraries from a Content Delivery Network (CDN), which can improve the performance of your applications.

The DevExpress CDN hosts Widget JavaScript libraries and style sheets and enables you to add them to your applications. A link to these libraries should be added in the following manner.

HTML
<!--Scripts-->
<script src="http://cdn3.devexpress.com/jslib/14.1.13/js/dx.phonejs.js"></script> <!--Mobile UI widgets-->
<script src="http://cdn3.devexpress.com/jslib/14.1.13/js/dx.webappjs.js"></script> <!--Desktop UI widgets-->
<script src="http://cdn3.devexpress.com/jslib/14.1.13/js/dx.all.js"></script> <!--All UI widgets-->

<!--Styles-->
<link rel="stylesheet" type="text/css" href="http://cdn3.devexpress.com/jslib/14.1.13/css/dx.common.css" />
<link rel="stylesheet" type="text/css" href="http://cdn3.devexpress.com/jslib/14.1.13/css/dx.ios.default.css" />

You can also use the jQuery, Globalise, Knockout and Angular libraries in the same manner via the Microsoft Ajax CDN and Google CDN.

<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-2.1.1.min.js"></script>
<!--script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/knockout/knockout-3.1.0.js"></script-->
<!--script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/angularjs/1.1.1/angular.min.js"></script-->
<!--script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/angularjs/1.1.1/angular-sanitize.js"></script-->
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/globalize/0.1.1/globalize.min.js"></script>

Use a NuGet Package

When using Visual Studio, you can easily add the dx.webappjs.js or dx.phonejs.js library to your application using the DevExtreme Web or DevExtreme Mobile NuGet package respectively. To do this, follow the steps below.

  1. Right-click your project in the Solution Explorer window and choose Manage NuGet Packages... in the context menu.

    NuGetVS

  2. Choose Online in the right column of the appeared window.

    NuGetVS

    Make sure that you have nuget.org as your online source. Then, type DevExtreme Web (DevExtreme Mobile) within the Search Online text box.

  3. When the search is complete, click the Install button of the found item.

    NuGetVS

After the successful install of the DevExtreme Web (DevExtreme Mobile) NuGet package, you will find it in the list of installed packages along with the Globalize and jQuery packages upon which the dx.webappjs.js (dx.phonejs.js) library depends.

NuGetVS

Once you have installed the DevExtreme Web (DevExtreme Mobile) NuGet package, you will be able to update the dx.webappjs.js (dx.phonejs.js) library to the newest version from the Updates section of the Manage NuGet Packages window.

To use the dx.webappjs.js (dx.phonejs.js) library, provide links to the library and its dependencies. Add the following code to your application.

HTML
<script src="/Scripts/jquery-2.1.1.min.js"></script>
<script src="/Scripts/globalize/globalize.js"></script>
<script src="/Scripts/dx.webappjs.js"></script>
<!--<script src="/Scripts/dx.phonjejs.js"></script>-->

NOTE: The Knockout and AngularJS libraries are not included in the DevExtreme Web and DevExtreme Mobile NuGet packages.

You can find more information about the DevExtreme Web and DevExtreme Mobile NuGet packages in the NuGet Gallery: DevExtreme Web and DevExtreme Mobile.

To learn how to install NuGet, refer to the Installing NuGet article.

Add a Widget

There are the following possible approaches to creating a DevExtreme widget. Review all of these approaches to pick the one that suits your project best.

jQuery Approach

Add a div element within the body of the required view.

HTML
<div id="buttonContainer"></div>

DevExtreme supplies jQuery plugins for each widget. The following code demonstrates how to create a button within the "buttonContainer" container using the dxButton jQuery plugin.

JavaScript
$(function () {
    $("#buttonContainer").dxButton();
});

To configure a widget, pass a configuration object as the constructor's parameter. The properties of this object represent the widget's configuration options. To specify them, set the required values to the configuration object's properties.

JavaScript
$(function () {
    var showHelloWorld = function () {
        alert("Hello world!");
    };

    $("#buttonContainer").dxButton({
        clickAction: showHelloWorld,
        text: "Click me!"
    });
});
See Also

You can see an example in the Configure Widget - jQuery Approach tutorial.

To create a widget within a view of your DevExtreme application, handle the viewRendered event of the HtmlApplication object. To specify a separate handler for a particular view only, add the viewShown field to the view's ViewModel and assign the handling function to it.

HTML
<div data-options="dxView:{name:'home', title:'Home'}">
    <div data-options="dxContent: { targetPlaceholder: 'content'}">
        <div data-bind="dxButton: { text: 'Click me!', clickAction: showHelloWorld }"></div>
    </div>
</div>
JavaScript
MyApp.home = function(params) {
    return {
        viewShown: function () {
            $("#buttonContainer").dxButton({
                clickAction: showHelloWorld,
                text: "Click me!"
            });
        }
    };
};

Knockout Approach

If you use the DevExtreme widgets with the Knockout approach, the application should include a link to the knockout-3.1.0.js library.

HTML
<!--script src="/js/knockout-3.1.0.js"></script-->

DevExtreme supplies custom Knockout bindings for each widget.

HTML
<body>
    <div id="buttonContainer" data-bind="dxButton: {}"></div>
</body>

To configure a widget, specify a configuration object. The properties of this object represent the widget's configuration options. To specify them, set required values for the configuration object's properties.

HTML
<body>
    <div id="buttonContainer" data-bind="dxButton: { clickAction: showHelloWorld, text: 'Click me!' }"></div>
</body>

In the code above, the dxButton's clickAction option is set to a value that is specified by the accompanying JavaScript code below.

JavaScript
var myViewModel = {
    showHelloWorld: function() {
        alert("Hello world!");
    }
};
ko.applyBindings(myViewModel);

To activate Knockout, call ko.applyBindings() as it was done in the code above.

See Also

You can see an example in the Configure Widget - Knockout Approach tutorial.

To create a widget within a view of your DevExtreme application, add the widget element to the required layout placeholder of the view markup.

HTML
<div data-options="dxView:{name:'myView', title:'Home'}">
    <div data-options="dxContent: { targetPlaceholder: 'content'}">
        <div data-bind="dxButton: { text: 'Click me!', clickAction: showHelloWorld }"></div>
    </div>
</div>

Widget options can be bound to the fields of the view's ViewModel, as the clickAction option specified above is bound to the showHelloWorld function defined within the ViewModel below.

JavaScript
MyApp.myView = function(params) {
    return {
        showHelloWorld: function() {
            alert("Hello world!");
        }
    }
});

NOTE: If you use widgets within a DevExtreme application, you don't have to call the ko.applyBindings() function to perform binding, because this function is called internally when displaying a view.

Angular Approach

DevExtreme UI widgets can be used in applications built using the AngularJS version 1.2 framework. Therefore, the widgets library includes an AngularJS module registered under the name "dx". This module contains registered directives for all DevExtreme widgets. Include this module in the list of dependencies for your application module.

JavaScript
angular.module('myApp', [ 'dx' ]);

If you use the Angular approach, the application should include links to angular.js and angular-sanitize.js libraries in addition to commonly required libraries.

HTML
<script src="/js/angular.js"></script>
<script src="/js/angular-sanitize.js"></script>

DevExtreme supplies custom AngularJS directives for each widget. To create a DevExtreme widget on a page, add a div element and apply an attribute representing the corresponding directive. The attribute name should correspond to the AngularJS normalization rules: dx-widget-name. For instance, use the dx-button directive to create the dxButton widget and the dx-multi-view directive to created the dxMultiView widget.

HTML
<div dx-button=""></div>

To configure a widget, specify a configuration object within the directive's expression. The fields of this object represent the widget's configuration options.

HTML
<div dx-button="{ text: 'Click me!' }"></div>

You can set configuration options to the values that are specified in scope. In the code below, the dxButton's clickAction option is set to the showHelloWorld function that is defined within the scope of the controller.

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

You can also set an object from the scope as a configuration object of a widget.

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

You can see an example in the Configure Widget - Angular Approach tutorial.