Kendo UI Mobile – Exploring Mobile Widgets

Nishanth Nair

September 2013

(For more resources related to this topic, see here.)

Kendo Mobile widgets basics

All Kendo Mobile widgets inherit from the base class, which is inherited from the base class of all Kendo widgets (both Web and Mobile), kendo.ui.Widget. The complete inheritance chain of the mobile widget class is shown in the following figure:

kendo.Class acts as the base class for most of the Kendo UI objects while the kendo.Observable object contains methods for events. which is the building block of Kendo MVVM, is inherited from kendo.Observable.

Mobile widget base methods

From the inheritance chain, all Kendo Mobile widgets inherit a set of common methods. A thorough understanding of these methods is required while building highly performing, complex mobile apps.


The bind() method defined in the kendo.Observable class, attaches a handler to an event. Using this method we can attach custom methods to any mobile widget. The bind() method takes the following two input parameters:

  • eventName: The name of the event
  • handler: The function to be fired when the event is raised

The following example shows how to create a new mobile widget and attach a custom event to the widget:

//create a new mobile widget var mobileWidget = new; //attach a custom event mobileWidget.bind("customEvent", function(e) { // mobileWidget object can be accessed
inside this function as //'e.sender' and 'this'. console.log('customEvent fired'); });

The event data is available in the object e. The object which raised the event is accessible inside the function as e.sender or using the this keyword.


The trigger() method executes all event handlers attached to the fired event. This method has two input parameters:

  • eventName: The name of the event to be triggered
  • eventData (optional): The event-specific data to be passed into the event handler

Let's see how trigger works by modifying the code sample provided for bind:

//create a mobile widget var mobileWidget = new; //attach a custom event mobileWidget.bind("customEvent", function(e) { // mobileWidget object can be accessed //inside this function as //'e.sender' and 'this' . console.log('customEvent fired'); //read event specific data if it exists if(e.eventData !== undefined){ console.log('customEvent fired with data: ' + e.eventData); } }); //trigger the event with some data mobileWidget.trigger("customEvent", { eventData:'Kendo UI is cool!' });

Here we are triggering the custom event which is attached using the bind() method and sending some data along. This data is read inside the event and written to the console.

When this code is run, we can see the following output in the console:

customEvent fired customEvent fired with data: Kendo UI is cool!


The unbind() method detaches a previously attached event handler from the widget. It takes the following input parameters:

  • eventName: The name of the event to be detached. If an event name is not specified, all handlers of all events will be detached.
  • handler: The handler function to be detached. If a function is not specified, all functions attached to the event will be detached.

The following code attaches an event to a widget and detaches it when the event is triggered:

//create a mobile widget var mobileWidget = new; //attach a custom event mobileWidget.bind("customEvent", function(e) { console.log('customEvent fired'); this.unbind("customEvent"); }); //trigger the event first time mobileWidget.trigger("customEvent"); //trigger the event second time mobileWidget.trigger("customEvent");


customEvent fired

As seen from the output, even though we trigger the event twice, only on the first time is the event handler invoked.


The one() method is identical to the bind() method only with one exception; the handler is unbound after its first invocation. So the handler will be fired only once.

To see this method in action, let's add a count variable to the existing sample code and track the number of times the handler is invoked. For this we will bind the event handler with one() and then trigger the event twice as shown in the following code:

//create a mobile widget var mobileWidget = new; var count = 0; //attach a custom event"customEvent", function(e) { count++; console.log('customEvent fired. count: ' + count); }); //trigger the event first time mobileWidget.trigger("customEvent"); //trigger the event second time mobileWidget.trigger("customEvent");


customEvent fired. count: 1

If you replace the one() method with the bind() method, you can see that the handler will be invoked twice.


The destroy() method is inherited from the kendo.ui.Widget base object. The destroy() method kills all the event handler attachments and removes the widget object in the attribute so that the widget can be safely removed from the DOM without memory leaks. If there is a child widget available, the destroy() method of the child widget will also be invoked.

Let's see how the destroy() method works using the Kendo Mobile Button widget and using your browser's developer tools' console. Create an HTML file, add the following code along with Kendo UI Mobile file references in the file, and open it in your browser:

<div data-role="view" > <a class="button" data-role="button" id="btnHome"
data-click="buttonClick">Home</a> </div> <script> var app = new; function buttonClick(e){ console.log('Inside button click event handler...'); $("#btnHome").data().kendoMobileButton.destroy(); } </script>

In this code block, we created a Kendo Button widget and on the click event, we are invoking the destroy() method of the button.

Now open up your browser's developer tools' Console window, type $("#btnHome").data() and press Enter .

Now if you click on the Object link shown in the earlier screenshot, a detailed view of all properties can be seen:

Now click on kendoMobilebutton once and then again in the Console , type $("#btnHome").data() and hit Enter . Now we can see that the kendoMobileButton object is removed from the object list:

Even though the data object is gone, the button stays in the DOM without any data or events associated with it.


The view() method is specific to mobile widgets and it returns the view object in which the widget is loaded.

In the previous example, we can assign an ID, mainView, to the view and then retrieve it in the button's click event using this.view().id as shown in the following code snippet:

<div data-role="view" id="mainView" > <a class="button" data-role="button" id="btnHome"
data-click="buttonClick">Home</a> </div> <script> var app = new; function buttonClick(e){ console.log("View id: " + this.view().id ); } </script>


View id: #mainView

The ButtonGroup widget

Sometimes for navigation between sections inside a view, we may need buttons grouped together. The ButtonGroup widget is helpful in this scenario by transforming an HTML list into a set of buttons. Icons can also be set for each individual buttons just like the Button widget.


ButtonGroup can be initialized by setting data-role="buttongroup" to <ul> </ul> as shown in the following code snippet:

<ul data-role= "buttongroup" > <li> Button 1 </li> <li> Button 2 </li> <li> Button 3 </li> </ul>

ButtonGroup can be initialized using the jQuery plugin syntax too as shown as follows:

<div data-role="view" data-init="initialize"> <ul id="listButtons" > <li> button 1 </li> <li> button 2 </li> <li> button 3 </li> </ul> </div> <script> var app = new; function initialize(){ var buttongroup = $("#listButtons").kendoMobileButtonGroup(); } </script>


ButtonGroup can be styled in the following two ways:

  • Adding your style definitions in the <li> element for each button:

    <ul id="listButtons" data-role="buttongroup" > <li style="background-color:green; color:white; font-style:italic"> button 1 </li> <li> button 2 </li> <li style= "background-color:orange; color:white;"> button 3 </li> </ul>

  • Overriding Kendo-generated CSS styles for iOS:

    .km-root .km-ios .km-buttongroup .km-button { background-color: red; } .km-root .km-ios .km-buttongroup .km-button .km-text { color: white; }

ButtonGroup in action

Now let's write some code and see the ButtonGroup widget in action by exploring its properties, methods, and events. Our code is going to create a ButtonGroup with four buttons and once a button is selected, we will write to the console the text and index of the button and change the text of the button to I am clicked. The buttons will be configured so that a button will be selected only when we release a press on it, which will make sure that, while scrolling, touching the button group will not select a button accidentally. We will also configure the widget so that the buttons are green in color by default and once a button is selected, it will change its color to maroon:

<body> <div data-role="view" data-init="initialize"> <div> <ul id="btnGroup"> <li>button 1 </li> <li>button 2 </li> <li>button 3 </li> </ul> </div> </div> <script> var app = new; function initialize() { $( "#btnGroup").kendoMobileButtonGroup({ index: 1, selectOn: "up", select: onButtonSelect }); } function onButtonSelect(e) { console.log('selected button text was : '+ this.current().text()); console.log(" index:" + this.current().index()); //Change the text on the selected button this.current().text( 'I am clicked' ); } </script> </body> <style> #btnGroup .km-button { background-color: green; color: white; } #btnGroup .km-state-active { background-color: maroon; } </style>

During the initialization we are using a couple of properties of the ButtonGroup widget:

  • index: This property selects a button with the specified index from the group.
  • selectOn: Using this property, we can specify whether the button will be selected as soon as the button is pressed or when the user releases the pressed button. Allowed values are up and down (default). Setting the value of this property to up selects the button selection on the touchend, mouseup, and MSPointerUp platform-specific events, while down does the selection on the touchstart, mousedown, or MSPointerDown events.

Then we hooked up the select event to the onButtonSelect function. Inside this function we read the text on the button using this.current().text(). The current() method will return the currently selected button's jQuery object. Similarly we found the index of the currently selected button using this.current().index(). Once the current button's data is read using jQuery's text() method, the text of the button is changed.

To set the initial color of the buttons, we updated the style provided by the .km-button CSS class. The .km-state-active class styles the currently selected button. By setting the background color to maroon in this class, we changed the selected button's background color.

We can also use ButtonGroup's select(index) method to select a button with the index provided as input.

The Switch widget

Switch is a common UI element on mobile devices which is used for binary on/off or true/false data input. The Switch widget can either be tapped or dragged to toggle its value.

The Kendo Mobile Switch widget is created by transforming an HTML checkbox. The checked property will get or set the checked/unchecked state of the widget. The label for a checked state is set using the onLabel property and the offLabel property sets the unchecked state's label.

The check() method gets and sets the checked state of the widget and the toggle() method toggles the checked state. When the checked state of the widget is changed, the change event is fired.


Now let's see different ways of initializing the Switch widget:

Data attribute initialization by setting data-role="switch":

<input type="checkbox" id="chkSwitch1" data-role="switch" checked="checked"data-on-label="Pass"
data-off-label="Fail" />

jQuery plugin syntax:

<div data-role="view" data-init="init"> <input type="checkbox" id="chkSwitch2" /> </div> <script> var app = new; function init(){ $('#chkSwitch2').kendoMobileSwitch({ checked:false, onLabel:'Yes', offLabel:'No' }); } </script>

The PopOver widget

The PopOver widget is used on tablet devices to display content on a visual layer that floats above the app's window. This widget is typically used in the following scenarios:

  • To display some information about an element
  • To display a menu for navigating to other views
  • To display a context menu with actions to be performed
  • To display a filter list

The PopOver widget can contain multiple views inside it and they can be navigated between each other. The views are automatically added inside a Pane widget. The Pane widget's properties can be set using the pane configuration option.


The widget can be initialized declaratively by setting data-role="popover". Additional pop-up options can be set through the data-popup attribute.

The PopOver widget can be opened by tapping a navigational widget by adding the data-rel="popover" attribute and a href attribute targeting the PopOver's ID or programmatically by calling its open() method:

<a data-role="button" href="#popOverWidget"data-rel="popover">Filter</a> <div id="popOverWidget" data-role="popover"data-popup="{'height':150}"> <div data-role="view"> <ul data-role="listview"> <li> <a href="#">Comedy (9)</a> </li> <li> <a href="#">Action (10)</a> </li> <li> <a href="#">Romantic (5)</a> </li> <li> <a href="#">War (7)</a> </li> </ul> </div> </div>

The PopOver widget can be initialized using the jQuery plugin syntax as shown in the following code snippet:

<div data-role="view" data-init="init"> <a data-role="button" href="#popOverWidget"data-rel="popover">Select Genre</a> <div id="popOverWidget" > <div data-role="view"> <ul data-role="listview" > <li> <a href="#">Comedy (9)</a> </li> <li> <a href="#">Action (10)</a> </li> <li> <a href="#">Romantic (5)</a> </li> </ul> </div> </div> </div> <script> var app = new; function init(){ $('#popOverWidget').kendoMobilePopOver({ popup: { height: '130px' } }); } </script>

Try it in jsFiddle:

PopOver with multiple views

There are many scenarios we encounter where, in a PopOver widget, we need to display multiple views and navigate to each other depending on some condition. A common example is a multiview menu where the entire view is replaced by another level of menu.

Let's see how easily this can be implemented for selecting a movie from a genre list and then from a movie list using the PopOver widget as shown in the following code snippet:

<head> <style> .no-backbutton .km-back { visibility: hidden; } </style> </head> <body> <div data-role="view" > <a data-role="button" href="#popOverWidget" data-rel="popover"> Select Movie </a> <div id="popOverWidget" data-role="popover"
<!-- Layout --> <div data-role="layout" data-id="popoverLayout"> <div data-role="header"> <a data-role="backbutton" > Back </a> </div> <div data-role="footer"></div> </div> <!-- main menu view--> <div data-role="view" id="view-main"class="no-backbutton" > <ul data-role="listview" > <li><a href="#view-comedy">Comedy (3)</a></li> <li><a href="#view-action">Action (2)</a></li> </ul> </div> <!-- Comedy Menu View--> <div data-role="view" id="view-comedy"> <ul data-role="listview" > <li> <a href="#view-final?movie=Hangover III"> Hangover III </a> </li> <li> <a href="#view-final?movie=Scary Movie"> Scary Movie </a> </li> <li> <a href="#view-final?movie=Ted">Ted </a> </li> </ul> </div> <!-- Action Menu View--> <div data-role="view" id="view-action"> <ul data-role="listview" > <li> <a href="#view-final?movie=Iron Man 3"> Iron Man 3 </a> </li> <li> <a href="#view-final?movie=After Earth"> After Earth </a> </li> </ul> </div> <!-- Final View--> <div data-role="view" id="view-final" data-show="finalViewShow" > <div> <h3>You selected: </h3> <h2> <!-- Selected movie name will be displayed in this span --> <span id="spanMovieName"> </span> </h2> </div> </div> </div> </div> <script> var app = new; //Function to be called when the view is shown every time function finalViewShow(e) { //show the movie name in the view $('#spanMovieName').text(; } </script> </body>

We added three views in the PopOver widget, two menus, and one final view, where the selected movie is displayed. The menus are assigned a common layout (popoverLayout) which contains a header element with a Kendo BackButton widget. The back button is hidden in the first view using the following CSS class :

.no-backbutton .km-back { visibility: hidden; }

For all other views, the back button is visible and by using it we can navigate to the previous view.

In the view with ID view-main, we are showing the genre of the movies, and clicking on the links will take you to the appropriate movie menu views, that is, view-comedy or view-action. In this menu, we are displaying movies as links with the movie name passed to the view with ID view-final as a query string. Once we click a movie name and navigate to the final view, the function finalViewShow is invoked. This function reads the movie name from the query string and displays it on the view.

The second and third view of the PopOver widget we created is shown as follows:


In this article, we explored the basics of Kendo UI Mobile widgets and learned about commonly available methods. We then took a deep dive into widgets such as ListView, Button, ButtonGroup, Switch, Pane, and PopOver and saw how to instantiate them and use them in multiple scenarios using examples.

Resources for Article :

Further resources on this subject:

You've been reading an excerpt of:

Building Mobile Applications Using Kendo UI Mobile and ASP.NET Web API

Explore Title