Getting Started / Working with Widgets

Initializing with MVVM

You can initialize and configure each Kendo UI widget through the data attributes or based on custom HTML attributes.

The Kendo UI Hybrid Application, the Single-Page-Application (SPA) view component, and the Model View View-Model (MVVM) kendo.bind method use the declarative approach to automatically instantiate multiple widgets in an existing DOM element.

Using the data Attributes

Initialization from data attributes is convenient when there are a lot of Kendo UI widgets on the page because the widget configuration is declared within the target element.

The following example demonstrates how to initialize a Kendo UI widget by using the data attributes. The kendo.bind($("#container")) statement finds all elements that have the role data attribute set and initializes the respective Kendo UI widgets.

The value of the role data attribute is the lower-case name of the widget—"autocomplete", "dropdownlist", and so on.

Initializing in Hybrid Applications

You can initialize widgets from data attributes in hybrid applications and within given elements, and then also configure the data-* options. By default, to avoid ambiguity, kendo.bind initializes only widgets from the kendo.ui namespace, excluding the hybrid widgets. This behavior can be changed by passing additional namespaces as parameters. Note that the hybrid Kendo UI Application initializes widgets from the kendo.mobile.ui namespace first. This means that an element with data-role="listview" is automatically initialized as a hybrid ListView widget in the hybrid Application context.

The data-role attribute also accepts a full widget class name (with its namespace) as a value.

The following example demonstrates how to instantiate a Kendo UI ListView in a hybrid Application by using the full class path of the widget.

<div data-role="view">
    <!-- specify the Kendo UI Web ListView widget -->
    <div data-role="kendo.ui.ListView"></div>
</div>
<script>
var app = new kendo.mobile.Application();
</script>

Initializing in Specific Elements

The following example demonstrates how to instantiate Kendo UI widgets in a specific element.

<div id="container">
    <input data-role="numerictextbox" />
    <button data-role="button">Mobile button</button>
</div>
<script>
kendo.bind($("#container"), {}, kendo.ui, kendo.mobile.ui);
</script>

Setting the data Options

Each configuration option can be set with the data attribute of the target element. Add the "data-" prefix to the name of the configuration option and specify the option value—for example, data-delay="100".

The camelCase options are set through dash-separated attributes. For example, the ignoreCase option of the AutoComplete is set through data-ignore-case.

Options which start with data do not require an additional "data" in the attribute name. For example, the dataTextField option is set through the data-text-field attribute and dataSource is set through the data-source attribute. Complex configuration options are set as JavaScript object literals—for example, data-source="{data: [{name: 'John Doe'},{name: 'Jane Doe'}]}".

The following example demonstrates how to configure Kendo UI widgets with data attributes.

<div id="container">
    <input data-role="autocomplete"
           data-ignore-case="true"
           data-text-field="name"
           data-source="{data: [{name: 'John Doe'},{name: 'Jane Doe'}]}" />
</div>

<script>
    kendo.bind($("#container"), {});
</script>

Subscribing to Events

You are able to subscribe to Kendo UI widget events with data attributes. The value of the data attribute is resolved to a JavaScript function, available in the global scope. The following example demonstrates how to subscribe to a Kendo UI widget event through a data attribute.

<div id="container">
    <input data-role="numerictextbox" data-change="numerictextbox_change" />
</div>

<script>
    function numerictextbox_change(e) {
        // Handle the "change" event.
    }
    kendo.bind($("#container"));
</script>

Setting the Event Handlers

You can also set event handlers to member functions. For example, an event data attribute can be set to foo.bar, which is resolved as the bar method of the foo object available in the global scope.

The following example demonstrates how to use a member function as an event handler.

<div id="container">
    <input data-role="numerictextbox" data-change="handler.numerictextbox_change" />
</div>
<script>
var handler = {
    numerictextbox_change: function (e) {
        // Handle the "change" event
    }
};
kendo.bind($("#container"));
</script>

Setting the Data Source

The Data Source of data-bound Kendo UI widgets can also be set through a data attribute. The value can be a JavaScript object, array, or a variable available in the global scope.

The following example demonstrates how to set the data source of a Kendo UI widget to a JavaScript object.

<div id="container">
    <input data-role="autocomplete" data-source="{data:['One', 'Two']}" />
</div>
<script>
kendo.bind($("#container"));
</script>

The following example demonstrates how to set the data source of a Kendo UI widget to a JavaScript array.

<div id="container">
    <input data-role="autocomplete" data-source="['One', 'Two']" />
</div>
<script>
kendo.bind($("#container"));
</script>

The following example demonstrates how to set the data source of a Kendo UI widget to a variable available in the global scope.

<div id="container">
    <input data-role="autocomplete" data-source="dataSource" />
</div>
<script>
var dataSource = new kendo.data.DataSource( {
    data: [ "One", "Two" ]
});
kendo.bind($("#container"));
</script>

Using Templates

By using the data attributes, you can also set the template configuration. The attribute value is resolved as the id attribute of a script element with the template contents.

The following example demonstrates how to set the template of a Kendo UI widget.

<div id="container">
    <input data-role="autocomplete"
           data-source="[{firstName:'John', lastName: 'Doe'}, {firstName:'Jane', lastName: 'Doe'}]"
           data-text-field="firstName"
           data-template="template" />
</div>

<script id="template" type="text/x-kendo-template">
    <span>#: firstName # #: lastName #</span>
</script>

<script>
    kendo.bind($("#container"));
</script>

Using Markup

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

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

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

  • The data attribute initialization is not designed to be combined with the Kendo UI server wrappers. The usage of wrappers is equivalent to jQuery plugin syntax initialization. To create Kendo UI widget instances through the MVVM or AngularJS mechanisms, do not use server wrappers for these instances.
  • 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.

You can declaratively initialize widgets:

Initializing 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.

    <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>

Initializing in MVVM

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

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.

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

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

Initializing 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.

    <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>

See Also

In this article
Related articles
Not finding the help you need? Improve this article