Initializing as jQuery Plugins
All Kendo UI components (widgets) are registered as jQuery plugins which allows them to be instantiated on a jQuery object instance.
The jQuery plugin method is formed by the component name in Pascal Case that is prefixed with kendo as in kendoGrid and kendoListView. To avoid collisions with their desktop counterparts, the methods for the hybrid UI components are prefixed with Mobile as in kendoMobileTabStrip, kendoMobileButton, and kendoMobileListView.
Some Kendo UI components have specific requirements about the element types on which they are instantiated. For more details and working examples, refer to the source code in the respective component demo and API reference.
- Avoid initializing several different Kendo UI components from the same DOM element because duplicate initialization might lead to undesired side effects.
- It is strongly recommended to initialize the Kendo UI components from HTML elements which are part of the DOM tree. Creating components from document fragments might cause undesired side effects or lead to JavaScript errors.
Getting Started
The following example demonstrates how to use a regular approach to instantiate a Kendo UI AutoComplete. A similar approach to the demonstrated one is used for all other components with the component name spelled in Pascal Case. The widget initialization method follows the jQuery plugin paradigm and returns the jQuery object of the same DOM element which is used for the component creation. It does not return the widget instance, and the instance has to be obtained through the jQuery data() method.
If the
jQueryobject includes more than one DOM element, a separate component is instantiated for each one.
<p>Animal: <input id="animal" /></p>
<script>
$(function() {
$("#animal").kendoAutoComplete({ dataSource: [ "Ant", "Antilope", "Badger", "Beaver", "Bird" ] });
});
</script>
Multiple Components with Single Selectors
The following example demonstrates how to instantiate multiple Buttons with a single jQuery selector. The jQuery convention for returning the selected DOM element from most methods applies to the component initialization methods. This allows for chaining jQuery methods.
<button>Foo</button> | <button>Bar</button>
<script>
$(function() {
$("button").kendoButton();
});
</script>
Chaining jQuery Method Calls
The following example demonstrates the chain jQuery method calls after the component instantiation plugin method.
<button>Foo</button> | <button>Bar</button>
<script>
$(function() {
$("button").kendoButton().css("color", "red");
});
</script>
Components within Iframes
It is theoretically possible to initialize a Kendo UI component which is inside an iframe from the context of the parent page or vice-versa. Such cross-frame component creation might work in specific scenarios, but is not officially supported or recommended. For example, components that render popups might not be able to display them. To work around this issue, initialize components in another document context by calling a JavaScript function, which belongs to the same context where the components will be located.
Duplicate Initialization
When you initialize a component, the goal is to get the instance object. However, recreating a component instance turns out to be a common issue. When using a Kendo UI server-side wrapper (as the server-side wrappers are automatically initialized) or when a component is being created in an event handler that is executed multiple times, it is possible to initialize a component on the same DOM element more than once.
The following example demonstrates an incorrect duplicate initialization.
<input id="autocomplete" />
<script>
// initialization code here...
$("#autocomplete").kendoAutoComplete(["Apples", "Oranges", "Grapes"]);
// ...
// Correct: the instance reference is obtained:
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
// INCORRECT: The instance reference is obtained while creating a duplicate instance:
var duplicate = $("#autocomplete").kendoAutoComplete().data("kendoAutoComplete");
</script>
To check whether a component instance already exists for a certain DOM element, use the standard way to obtain the component instance. If the returned value is undefined, then the component instance does not exist.
<input id="autocomplete" />
<script>
// Try to obtain the component instance.
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
// Check the returned value.
if (typeof autocomplete === "undefined") {
// The component instance does not exist.
}
// A simpler alternative syntax for the above:
if (!autocomplete) {
// The component instance does not exist.
}
</script>
Component Configuration
To configure a Kendo UI component, pass a configuration object (key/value pairs) as an argument to the jQuery plugin method. The supported configuration options and events for each component are listed in the API reference of the respective component. The configuration object might also contain event handlers that will be bound to the corresponding component events.
The following example demonstrates how to set the height, columns, and dataSource configuration options of the Grid component.
<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>