Edit this page

Markup Widget Initialization

In addition to the jQuery plugin syntax, the Kendo UI widgets might be instantiated based on custom HTML attributes.

Overview

You can initialize widgets based on custom HTML attributes in the following ways:

  • Option 1 The View and the mobile Application instantiate widgets based on the role HTML5 data attributes. Both use the MVVM internally.
  • Option 2 The kendo.bind method scans the passed DOM element contents for the data-role attributes and instantiates the respective widgets.
  • Option 3 The Kendo UI AngularJS directives support declarative initialization based on custom element attributes or custom tag names.

Important

The data attribute initialization is not designed to be combined with the Kendo UI server wrappers. The usage of wrappers is equivalent to jQuery plug-in syntax initialization. To create Kendo UI widget instances through the MVVM or AngularJS mechanisms, do not use server wrappers for these instances.

While it is theoretically possible to initialize several different Kendo UI widgets from the same DOM element through the jQuery plug-in syntax, it is not supported with the declarative initialization from markup.

Important

It is strongly recommended to initialize the Kendo UI widgets from HTML elements, which are part of the DOM tree. The creation of widgets from document fragments might cause undesired side effects or lead to JavaScript errors.

Declarative Initialization

You can declaratively initialize widgets:

In SPA Views

The following example refers to a (SPA) View with an AutoComplete widget in the template. For more information on the SPA View, refer to the article on building Single Page Applications.

Example
    <div id="container"></div>
    <script id="index" type="text/x-kendo-template">
        <div>Hello <input data-role="autocomplete" data-source="['foo', 'bar', 'baz']" />!</div>
    </script>

    <script>
        var index = new kendo.View('index');
        index.render("#container");
    </script>

In MVVM

The following example refers to an MVVM-bound DOM element with an AutoComplete widget.

Example
    <div id="container">
        <div>Hello <input data-role="autocomplete" data-bind="source: source" />!</div>
    </div>

    <script>
        kendo.bind($("#container"), {
            source: ['foo', 'bar', 'baz']
        });
    </script>

Important

The data-bind attribute syntax establishes a two-way binding between the widget options—in this case, the Data Source—and the view model field (the source). For more information, refer to the introductory article on MVVM.

In Hybrid UI Applications

The following example refers to a Kendo UI hybrid Application with a View and an AutoComplete widget. For more information about the Hybrid UI applications, refer to the article on building hybrid mobile applications.

Example
    <div data-role="view" data-model="foo">
        <div>
        An autocomplete widget
        <input data-role="autocomplete" data-source="['foo', 'bar', 'baz']" />
        </div>

        <div>
        A widget bound to the mobile view ViewModel dataSource field
        <input data-role="autocomplete" data-bind="source: dataSource" />
        </div>
    </div>

    <script>
        var foo = kendo.observable({
            dataSource: ['foo', 'bar', 'baz']
        });

        new kendo.mobile.Application();
    </script>

Configuration

To configure widgets that are declaratively initialized, you need to be aware of some specifics such as the parsing of the data attributes and the AngularJS directives.

The data Attributes

In addition to the data-role attribute, the declarative initialization parses other data attributes and passes them as configuration options to the widget constructor. For more information on the supported data attributes and on how to bind them to widget events, refer to the section on data attributes.

AngularJS Directives

The following example refers to the AngularJS directive in the Kendo UI AutoComplete. For more information on the features of the Kendo UI AngularJS directives, refer to the introductory article on AngularJS.

Example

    <div ng-app="myApp">
        <div ng-controller="MyController">
            <input kendo-autocomplete k-data-source="dataSource" />
        </div>
    </div>

    <script>
        var myApp = angular
                        .module("myApp", [ "kendo.directives" ])
                        .controller("MyController", function($scope) {
                          $scope.dataSource = [
                                     'foo', 'bar', 'baz'
                                      ]
                            });
    </script>

See Also

Other articles on getting started with Kendo UI: