Edit this page

jQuery Plug-Ins Widget Initialization

All Kendo UI widgets are registered as jQuery plug-ins which allows them to be instantiated on a jQuery object instance.

Overview

The jQuery plug-in method is formed by the widget name in Pascal Case, prefixed with kendo as in kendoGrid and kendoListView. To avoid collisions with their desktop counterparts, the methods for the Hybrid UI widgets are prefixed with Mobile as in kendoMobileTabStrip, kendoMobileButton, and kendoMobileListView.

Some Kendo UI widgets have specific requirements about the element types they must be instantiated on. For more details and working examples, check the source code in the respective widget demo and API reference.

While it is theoretically possible to initialize several different Kendo UI widgets from the same DOM element, it might lead to undesired side effects.

Important

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

Initialization

This section demonstrates the basic scenarios for initializing the Kendo UI widgets.

Regular Approaches

The following example demonstrates how to instantiate a Kendo UI AutoComplete.

Example

    <p>Animal: <input id="animal" /></p>

    <script>
        $(function() {
          $("#animal").kendoAutoComplete({ dataSource: [ "Ant", "Antilope", "Badger", "Beaver", "Bird" ] });
        });
    </script>

Important

  • A similar approach is used for all other widgets, with the widget name being spelled in Pascal Case. The widget initialization method follows the jQuery plug-in paradigm and returns the jQuery object of the same DOM element used for the widget creation. It does not return the widget instance, and the instance should be obtained through the jQuery data() method.
  • If the jQuery object includes more than one DOM element, a separate widget is instantiated for each one.

Multiple Widgets with Single Selectors

The following example demonstrates how to instantiate multiple Buttons with a single jQuery selector.

Example
    <button>Foo</button> | <button>Bar</button>
    <script>
      $(function() {
        $("button").kendoButton();
      });
    </script>

Important

The jQuery convention for returning the selected DOM element from most methods applies to the widget initialization methods. This allows for chaining jQuery methods.

Chaining jQuery Method Calls

The following example demonstrates the chain jQuery method calls after the widget instantiation plug-in method.

Example
    <button>Foo</button> | <button>Bar</button>

    <script>
      $(function() {
        $("button").kendoButton().css("color", "red");
      });
    </script>

Widgets within Iframes

It is theoretically possible to initialize a Kendo UI widget which is inside an iframe from the context of the parent page or vice-versa. Such cross-frame widget creation might work in specific scenarios, but is not officially supported or recommended. For example, widgets that render popups might not be able to display them. To work around this issue, initialize widgets in another document context by calling a JavaScript function, which belongs to the same context where the widgets will be located.

Duplicate Initialization

When initializing a widget, the goal is to get the instance object. However, recreating a widget instance turns out to be a common issue.

Overview

When using a Kendo UI server-side wrapper (as the server-side wrappers are automatically initialized) or when a widget is being created in an event handler executed multiple times, it is possible to initialize a widget on the same DOM element more than once.

The following example demonstrates an incorrect duplicate initialization.

Example
    <input id="autocomplete" />
    <script>
        // initialization code here...
        $("#autocomplete").kendoAutoComplete(["Apples", "Oranges", "Grapes"]);

        // ...
        // correct - instance reference is obtained:
        var autocomplete = $("#autocomplete").data("kendoAutoComplete");

        // INCORRECT - instance reference is obtained while creating a duplicate instance:
        var duplicate = $("#autocomplete").kendoAutoComplete().data("kendoAutoComplete");
    </script>

Tracking Existing Instances

To check whether a widget instance already exists for a certain DOM element, use the standard way to obtain the widget instance. If the returned value is undefined, then the widget instance does not exist.

Example
    <input id="autocomplete" />
    <script>
        // try to obtain the widget instance
        var autocomplete = $("#autocomplete").data("kendoAutoComplete");

        // check the returned value
        if (typeof autocomplete === "undefined") {
            // widget instance does not exist
        }
        // simpler alternative syntax for the above
        if (!autocomplete) {
            // widget instance does not exist
        }
    </script>

Configuration

To configure a Kendo UI widget, pass a configuration object—key/value pairs—as an argument to the jQuery plug-in method. The supported configuration options and events for each widget are listed in the API reference of the respective widget. The configuration object might also contain event handlers that will be bound to the corresponding widget events.

The following example demonstrates how to set the height, columns and dataSource configuration options of the Grid widget.

Example
    <div id="grid"></div>

    <script>
    $("#grid").kendoGrid({
      height: 200,
      columns:[
          {
              field: "FirstName",
              title: "First Name"
          },
          {
              field: "LastName",
              title: "Last Name"
          }
      ],
      dataSource: {
          data: [
              {
                  FirstName: "John",
                  LastName: "Doe"
              },
              {
                  FirstName: "Jane",
                  LastName: "Doe"
              }
          ]
      }
    });
    </script>

See Also

Other articles on getting started with Kendo UI:

Is this article helpful? Yes / No
Thank you for your feedback!

Give article feedback

Tell us how we can improve the information

close
Dummy