by cody lindley v 1.0


What Is This?

This is an opinionated guide prescribing the ideal usage of Kendo UI mobile widgets and application tools for building web platform sites or applications to be run on phones and tablets.


Why Use Kendo UI Mobile?

Kendo UI provides specific touch first widgets, to be used in the construction of phone and tablet web-platform interfaces. In addition to widgets, Kendo UI also provides application logic for building a Single Page Application in a mobile browser or webview (i.e. Application, View, Layout). In this guide, I will refer to the application logic that is provided by Kendo UI as "mobile application logic" (i.e.

While Kendo UI widgets can run standalone, without an active mobile application instance, this guide assumes the use of the mobile application logic in conjunction with the mobile widgets. Unless you are bringing a replacement for the application logic provided by (e.g. Angular + ng-view + ng-router), the application logic will almost always be needed alongside the mobile widgets.

  • Using the Kendo UI mobile SPA application logic is not strictly required for the widgets to function. Kendo UI mobile widgets can be used anywhere with any SPA framework. They can run standalone for use alongside any Kendo UI web or data visualization widget (i.e. not just mobile widgets) in any web platform environment.
  • The Kendo UI mobile solution does favor integration with Angular (directives are provided), but Angular is not strictly required if the default SPA application logic is not used.

Who Should Read This?

This guide is targeted at front-end developers who have an intermediate understanding of developing applications using HTML, CSS, and JavaScript (e.g. SPA applications using MVVM) and want to use these skills to build a phone or tablet application using Kendo UI mobile solutions.


A reader will gain the most from this guide if they already have a good understanding of Kendo UI solutions and JavaScript application concepts/tools. Be aware and prepared that some knowledge is imparted and some knowledge is assumed about the following:

If you are unfamiliar with any of the above items, I suggest you stop reading this guide and spend sometime educating yourself about the concepts you are least knowledgeable about.

Another possible resource to consume and examine before reading this guide, and after grokking the above prerequisites, is the "Kendo Mobile Sushi Demo" on Github. This mobile app demo provides three different patterns (declarative instantiation only, declaritive+MVVM, and angularJS) for coding a Kendo UI Mobile application. By studying this application and the different patterns for creating a mobile app using Kendo UI, you will be well equipped to make sense of this guide.

Whats-Er-Name Example Application

This guide will express development opinions in the context of an application called, "whats-er-name". The whats-er-name app captures head-shots and names for the purpose of memorizing a group of peoples' names. I conjured up this application to help me memorize the names of each child on my son's football team. The application's functionality provides a UI to create a group, and to then enter a name and head shot (taken with the camera or pulled in from a photo already taken) for each person in the group. The point of the application is to create a slideshow of named photos for memorizing faces and names. Below I show the wireframe I drafted when spec'ing out the application.

The source code can be found on GitHub. You should familiarize yourself with the code (i.e. download, build it, use the app) before reading this guide. Keep in mind that the code is more or less pseudo code, written for the purpose of crafting this document (i.e. storing image data URIs in localStorage is not an ideal solution). In other words, pay attention to the rationale/architecture around the total formation of application rather than to a specific individual part of the application.

Below is a small video walk-thru of the whats-er-name functionality in action.

Kendo UI Mobile Code

Kendo UI Mobile widgets and application tools are free and open source for anyone to use for anything. The code is part of the open sourced Kendo UI Core which is the foundation for Telerik's paid product, Kendo UI Professional.

You can get Kendo UI Core from:

The whats-er-name application uses Bower to install Kendo UI core. However, in this section of the guide, I will briefly detail all of the ways mentioned above that one can obtain the Kendo UI mobile source code.

Getting Kendo UI Core From the CDN

                                    <!DOCTYPE html>
                                        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
                                        <link href="" rel="stylesheet" />

                                        <script src=""></script>
                                        <script src=""></script>

  • The Kendo UI CDN is hosted on Amazon CloudFront.
  • In order to use HTTPS, you need to directly access the CloudFront CDN, or use your own domain and SSL certificate.
  • In production you should provide a fallback to CDN code.
  • Minified files are not always ideal for development. And, only the kendo.ui.code.min.js file is available on the CDN. To get the non-minified files, use bower install or pull the source from GitHub.

Getting Kendo UI Core From Bower

Open a terminal/command line and run $ bower install kendo-ui to get the Kendo UI Core package downloaded using Bower into the current directory.

Getting Kendo UI Core From GitHub

Open a terminal/command line and run $ git clone to clone the Git repository into the current directory or download the zip archive from GitHub.

Sign Up For a Kendo UI Professional Trial

Get a 30-day fully-functional trial of Kendo UI Professional (requires signing up a Telerik account). The trial will contain Kendo UI core and the mobile code.

Buy a Kendo UI Professional License

Purchase a Kendo UI professional license and you will have access to the complete source code for all of Kendo UI (requires signing up a Telerik account). Obviously, this will including Kendo UI core and the mobile code.

1. Kendo UI Mobile Do's

1.1 Identify and Use Newer Web Technologies When Available

A Kendo UI mobile app, even if it's running in a webview, is more than likley being rendered by a modern browser engine (i.e. a webview is like a browser window tab). Newer browser engines support things like ES5, Flexbox, CORS, Canvas, and Web Sockets.

Make sure you are aware of everything you have at your disposal for development and use it.

  • Kendo UI Mobile is supported on Android 2.3+, iOS 6+, Windows Phone 8+, and Chrome for Android. Kendo UI Mobile widgets, used standalone and without the mobile application logic will run on OS X 10.5+ (IE10+, Chrome Recent, Opera 15+, Safari 5+) and Windows XP+ / Server 2003+ (IE10+, Chrome Recent, Opera 15+)

1.2 Use jQuery 2.x

By simply using jQuery 2.X your mobile app will benefit in the following ways:

  • Performance improvements (up to 5%, depending on the app).
  • Faster load times, because jQuery 2.X is smaller in size
  • Future-proofing yourself for the inevitable end of the 1.x branch.

Additionally, Kendo UI Mobile is only supported in IE10+. Using jQuery 1.x, which contains a great deal of old code for IE 6, 7, 8 and 9 and is an unnecessary performance expense.

1.3 Build Common Sense Code

The following are common rules, laws, and practices among seasoned application developers for building long-lasting applications through consistency:

  1. Your entire codebase should follow the same style of coding as if a single developer (i.e. mind) crafted the code. This should be validated automatically at code time (i.e. in code editor on key stroke), build time, and commit time (e.g. GIT Hooks).
  2. When writing code be verbose, prioritize readability (i.e. code is read much more often than it is written), comment everything, and dispense with DRY principles if it obscures developer clarity.
  3. The DNA of an application is small miniature applications/components, properly decoupled into single responsibility modules.
  4. Modules are separated by nature (i.e. behavior/controller, model/data, style, template/html, test etc..) but organized together (i.e. application structure) by UI feature.
  5. Avoid complexity that does not clearly and rationally pay for itself.
  6. Don't optimize development code, optimize production code (i.e. don't pre-optimize)
  7. Document everything!
  8. Automate what you can using a task runner to build code. Don't rely on manual tasks entrusted to humans.
  9. Establish at least one layer (unit, integration, functional) of automated testing that runs during build or before accepting code commits (i.e. Use a githook to run tests, reject if tests fail).
  10. Automate the logging and notification of runtime errors for production code.
  11. Fear monolithic abstractions in the form of closed frameworks which promote one stop developer solutions.
  12. Plan for change. It's the only constant! This means that you had better not build a large complex system or build on top of one you adopt. Build a very small set of simple modules that work together in a decoupled way.

You need keep these practices in mind when creating a Kendo UI mobile application.

1.4 Develop Using Real Devices

Simulators and browsers running on a desktop or laptop provide a quick and easy way to run Kendo UI Mobile applications. However, this should not be how you test your code alone. It's critical that during development, development code is tested on the devices it's intended to run on. You need real phones. I recommend at the very least testing on the following device types:

  • Windows Phone / Windows Mobile 8.0+
  • Android / Android 4.0+
  • iPhone / iOS 6.0+

1.5 Make Use of Remote Debugging Tools

By plugging an Android (4.2+) or iOS (iOS6) device into you computer/laptop, you can use the developer tools found in Safari or Chrome locally to debug a Kendo UI Mobile application running on the phone in a browser. This is an invaluable tool when using real devices to test code.


1.6 Favor the Flat Theme

By default, Kendo UI Mobile will use a unique platform specific theme to style the UI. This is considered platform [adaptive CSS rendering]( because the UI will attempt to mimic the native UI of the devices OS. The first three devices (iOS, Android, Windows) in the image below demonstrate this feature in action.

However, it's better to force Kendo UI Mobile to use the styles for all platforms (e.g. the far right device in the above image).

The reason to favor the flat theme is as follows:

  1. Mimicking the look and feel of a specific platform turns out to be a complicated proposition, resulting in a UI that will likely fall short of native look and feel, function, and performance in most cases. It's better to have a custom UI than to have a UI that is always in second place to the real thing.
  2. Using the platform neutral theme results in a fast user experience because the CSS used to create the neutral theme is void of the complex CSS (i.e. Gradients etc...) required by the platform themes to replicate native UIs.
  3. Overwriting and evolving one theme (i.e. the flat theme) is simpler than overwriting and evolving several platform specific themes. This is exactly what is done at

To override Kendo UI Mobile's default nature of detecting the platform and forcing a platform-specific CSS theme simply set the skin option to flat in the Application() method when initializing the mobile application.

                                    var app = new$(document.body), { skin: 'flat' });

1.7 Tweak the Flat Theme

Telerik offers a mobile theme builder tool that can be used to generate CSS code that overrides the CSS found in the default Kendo UI Mobile themes. Below I show a video of this being done for the flat theme.

However, using the theme builder tool might be overkill. If all you want to do is replace the default turquoise color in the flat theme, you can use the CSS below to do so. Simply change the color values in the CSS and make sure that the CSS is included in an HTML document after the flat theme CSS.

                                    .km-flat .km-switch-handle,
                                    .km-flat .k-slider-selection,
                                    .km-flat .km-switch-background {
                                      color: #444;
                                    .km-flat .km-rowinsert,
                                    .km-flat .km-state-active,
                                    .km-flat .km-scroller-pull,
                                    .km-flat .km-loader:before,
                                    .km-flat .k-slider-selection,
                                    .km-flat .km-touch-scrollbar,
                                    .km-flat .km-pages .km-current-page,
                                    .km-flat .k-slider .k-draghandle,
                                    .km-flat .k-slider .k-draghandle:hover,
                                    .km-flat .km-tabstrip .km-state-active,
                                    .km-flat .km-popup .k-state-hover,
                                    .km-flat .km-popup .k-state-focused,
                                    .km-flat .km-popup .k-state-selected,
                                    .km-flat .km-actionsheet > li > a:active,
                                    .km-flat .km-actionsheet > li > a:hover,
                                    .km-flat .km-actionsheet > li > .km-state-active,
                                    .km-flat .km-listview-link,
                                    .km-flat .km-listview-label,
                                    .km-flat .km-listview-label input[type=radio]:checked,
                                    .km-flat .km-listview-label input[type=checkbox]:checked {
                                      background: #444;
                                    .km-flat .km-filter-wrap > input:focus {
                                      border-color: #444;

Before customizing the flat theme, either by hand or by using the theme builder tool, you should be aware of the flat theme customization found at These themes extend the flat theme and can be used as is or as a starting point for further customization.

1.8 Use the Additional Icons Kendo UI Mobile Provides

Kendo UI Mobile includes 38 integrated font icons that can be used in HTML by specifying a data-icon attribute with one of the following icon names:

Below I show of one of these icons defined in HTML:

                                    <li><span data-role="button" data-icon="about"></span>about</li>

Don't limit yourself to this short list of icons. There are hundreds of additional icons shipped for use but are simply not set up in CSS to be used. This is presumably done so the CSS does not become bloated with unused CSS declarations. Be aware of what is available and make use of what you need.

To use these additional icons you need to create CSS that references the additional icons. For example, the code below defines a right arrow icon by explicitly referencing the correct unicode/icon in the CSS declaration:

                                        content: "\e000";

With the above code in place, you can use the newly defined icon in your application like so:

                                    <a href="/" data-icon="arrow-e">Home</a>

All Unicodes with associated icons are shown below:

1.9 You'll Need a Mobile-First CSS Framework

Kendo UI Mobile does not lock you into or prohibit the use of mobile-first CSS framework to aid with UI development. I've found that even the simplest of custom interfaces (i.e. anything you want to do that is not a widget alone) can benefit from the solutions found in a mobile CSS framework (mobile first grids, form styles, form layouts etc...).

Some battle-tested mobile-first CSS frameworks are:

If introducing another third-party dependency into the code is not something you prefer doing, then just realize you will probably have to create a miniature custom CSS framework for aiding the development of custom interfaces. In other words, anything that is not a widget will have to be built using custom HTML & CSS. This can come as a rather big surprise if you are expecting something similar to Ionic CSS components.

  • I'm using Bootstrap in the whats-er-name. If you use Bootstrap, don't use the optional Kendo UI Mobile Bootstrap theme. It contains some CSS that might cause performance issues.
  • You might consider using the icons provided by third-party CSS frameworks. For example, if you use Bootstrap you could sidestep the Kendo UI Mobile icons and use

1.10 Only Use Kendo UI Patterns to Register Events

This might be the single most important opinion found in this guide. If you add events in any other manner except the ones described below, you'll have to write your own custom logic to deal with event delays and missed touches.

All touch related events should be declared in a mobile view using data attributes which refer to a view-model. Below, I show the 3 possible ways this can be coded:






Additionally, specific touch events that are not MVVM or widget specific (i.e. click) can be setup generically using the Touch widget.

                                   <div data-role="view">
                                        <div data-role="touch" data-tap="onTap">
                                            Tap me

                                        function onTap(e) {
                                            console.log( + " was tapped");

1.11 Improving Tap Predictability

Touch events can be unpredictable on mobile devices and mobile browser. This is an issue which plagues not just Kendo UI Mobile, but all HTML5/JavaScript solutions for mobile devices. To fix this today you can add the following code to your project to improve iOS and Windows touch reliability:

                                    var app = new, {
                                        init: function() {
                                            //don't do this for android, causes issues with scrollView and swiping
                                           kendo.UserEvents.defaultThreshold( === 'android' ? 0:20);

1.12 Favor Kendo UI Mobile Widgets

Although you can use third-party UI widgets with Kendo UI Mobile, it is best to stick with the Kendo UI Mobile widgets when they are available. Kendo UI Mobile widgets automatically adhere to the page's theme, use a consistent API, and are tested on each of Kendo UI Mobile's supported browsers.

The whats-er-name application uses the Button, Drawer, Layout(s), NavBar(s), and ScrollView widgets. You can view a full list of Kendo UI Mobile widgets at (see the “Mobile” heading), or you can scan the QR code below to run the demos on a mobile device (note: QR links you to all the Kendo demos not just mobile demos).

1.13 Favor HTML Form Elements Over Kendo UI Mobile Counterparts

When building forms in mobile apps, you should use HTML5 form elements whenever possible (e.g. input types like email, date, numeric, select, etc) instead of using the more complex Kendo UI counterparts (e.g. NumericBoxTextBox, DropDownList, etc). There is, of course, nothing wrong with the Kendo UI widgets, but if you don't need any specific functionality from them, you might as well save the overhead.

2. Kendo UI Mobile Cautions & Don'ts

2.1 Don't Add Mobile Rendering Meta Elements

Kendo UI Mobile automatically adds the meta elements below when your application is instantiated:

                                <meta name="apple-mobile-web-app-capable" content="yes">
                                <meta name="apple-mobile-web-app-status-bar-style" content="black">
                                <meta name="msapplication-tap-highlight" content="no">
                                <meta content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no" name="viewport">

Rely on this fact and don't add your own.

2.4 Don't Use IE Compatibility Modes

Internet Explorer compatibility modes can exhibit different behavior and rendering bugs, compared to the browser versions they emulate. Don't use compatibility modes, just the Edge mode. Place the following meta tag on all .html pages to enable IE's Edge mode.

                                <meta http-equiv="X-UA-Compatible" content="IE=edge" />

2.5 Don't Use AJAX to Navigate to Views (i.e. Remote Views)

Use a build step (like in the whats-er-name application) to get all the views in the application into a single .html page so that the application does not have to use AJAX to retrieve views when the application is running. View rendering is simplified when you take asynchronous view loading patterns out of the architecture.

2.6 Don't Fight Against Declarative Widget Initialization or MVVM

Kendo UI Mobile widgets and the Application instance are integrated with the declarative widget initialization (i.e. create widgets from markup) and the MVVM pattern. Learn it, accept it, and don't fight it. Otherwise, you'd be better off not using the and SPA logic found in the Application instance. You'd be better off either going all in on AngularJS or using the mobile widgets in stand alone mode.

2.7 Don't Mix AngularJS With Kendo UI MVVM or Mobile SPA Logic

If you are using AngularJS then you probably want to use Angular's own routing mechanism and data binding. In other words, don't mix SPA logic from Kendo UI Mobile with SPA logic from Angular. You won't be happy.

2.8 Don't Use a Dependency Manager With Mobile Views

Assuming, and I do in this guide, you are using the mobile application logic, don't attempt to load mobile views with a dependency manager. Doing so creates unnecessary complexity and overhead. Because of the way that the application logic works, all views have to be loaded and depended upon once (due to declarative instantiation) before the Application instance can be instantiated. This fact makes something like RequireJS almost pointless due to the complexity it adds to an application. Using RequireJS just so you can have modules is not ideal considering simpler solutions are possible using a tasking tool (e.g. gulp, grunt etc...).

Favor a build strategy using a tasking tool that allows you to keep things in organized modules but pull everything into a single .html file during the build process. Doing this works with Kendo UI Mobile assumptions (i.e everything in a single .html file) not against them.

3. whats-er-name Folder Structure

3.1 Application Structure Overview

The directory structure belows details the folder structured used to create the whats-er-name application.

├── bower.json
├── gulpfile.js
├── node_modules
├── package.json
├── src
│   ├── index.html
│   ├── shared
│   │   ├── css
│   │   ├── layouts
│   │   ├── models
│   │   └── utilities
│   └── ui
│       ├── appInfo
│       ├── groups
│       └── nameViewer
├── wwwDev
│   ├── bower_components
│   │   ├── bootstrap
│   │   ├── canvasResize
│   │   ├── jquery
│   │   ├── kendo-ui
│   │   └── lodash
│   ├── index.html
│   ├── shared
│   │   ├── css
│   │   ├── layouts
│   │   ├── models
│   │   └── utilities
│   └── ui
│       ├── appInfo
│       ├── groups
│       └── nameViewer
└── wwwProd
    ├── fonts
    │   ├── glyphicons-halflings-regular.eot
    │   ├── glyphicons-halflings-regular.svg
    │   ├── glyphicons-halflings-regular.ttf
    │   └── glyphicons-halflings-regular.woff
    ├── index.html
    ├── thirdparty
    │   ├── Flat
    │   ├──
    │   ├── images
    │   ├── thirdparty-15c25db7.css
    │   └── thirdparty-3f70b54f.js
    ├── whatsername-5bdcc67f.css
    └── whatsername-8b890cb0.js

I'm detailing the whats-er-name directory tree in this guide to server in order to prescriptive a structure, by example, that can be used for any Kendo UI mobile application. You can investigate and navigate this directory structure yourself by getting the code from GitHub and running a development build and production build using gulp. The remaining content in this chapter will discuss the directory structure in detail. Make sure you are referencing the above directory tree structure as you read.

3.2 Bower & NPM Directory Setup

The Bower and NPM package managers are used to download third-party code (i.e. public packages). Below, I describe where these packages are being stored and how each manager is configured for the whats-er-name application.

Node packages (used by Gulp) are stored in a directory called node_modules at the root of directory containing the application. This is the default directory name and location, used by NPM, for storing node modules. The package.json file, which defines/configures which modules are need, can also be found at the root of the directory containing the application.

Bower, unlike npm, is not being used in the default manner. The bower.json file is in the root of the application directory, which is common, but I am using the .bowerrc file to configure bower to store packages in the wwwDev directory in a folder called bower_components. This might seem odd, until you become aware of the fact that what you actually see in the browser during development is being served from the wwwDev directory and not the src directory.

3.3 Src, wwwDev, wwwProd Directories

The whats-er-name application source code can be found in the src directory. This will be where you edit code during development. The wwwDev directory and the wwwProd directory will contain development and production versions of the code which get served to a web browser using gulp-webserver (more on that in the build and task section).

  • If you are looking at the code in GitHub the wwwDev and wwwProd folders are missing. This is because they are created from running the dev and production build tasks.

3.4 Shared Directory

The src/shared directory will contain logically named and grouped modules which are either used globally to run the application or are used by more than one view module. Common files to find in the shared directory are global CSS modules, layout modules, models, and utility modules. Modules placed in the shared directory help to keeping things DRY. If more than one module in the ui directory uses another module, it's likely a candidate for placement in the shared directory.

3.5 ui Directory

The ui directory contains logically grouped and named UI portions of the application. It's not a hard and fast rule, but think of the ui directory as the place you start dividing the application into a folder structure of features or logical sections of the application. Often the structure of this directory will mimic the architecture of the application from a navigation or tree map perspective. This can often be a source of great confusion for developers because the structure of the folders depends greatly upon what is being built.

For a Kendo UI Mobile application it might be best to simply consider that each view has its own directory potentially containing one or more of the following modules:

  • view-model JS file (aka a controller)
  • view HTML file
  • layout HTML file
  • view CSS file containing view-specific styles
  • model JS file
  • template HTML file containing a template used in the view by a widget
  • test JS test file (test file could be a unit test, testing view-model or functional test, testing the view)

These directories of views form a tree/hierarchical structure based on the logical break up of the application from the user's perspective (i.e user interface).

How exactly the ui directory is organized is not an exact science. What's important is that the directory is human friendly, development friendly, and its architecture facilitates an application made up of small parts, grouped logically together, that have a clear separation of concerns (i.e. small modules). Every folder in the ui directory should represent a logical part (i.e. a region of logically relevant UI) of the application. Inside of the folder will be all of the source code for that part only (excluding parts found in the shared directory that are globally used by more than one view).

If this is difficult for you to envision, study the whats-er-name wireframe and the whats-er-name directory structure (specifically the ui directory) to get a feel for this style of organization.

3.6 Git Ignoring Directories

The .gitignore file (shown below) is used to keep the node_modules, wwwProd, and wwwDev out of Git source control.


If it's not obvious, this is done so that NPM and Bower packages are included in the repository and local development code (i.e. wwwProd and wwwDev) stays local.

4. whats-er-name Gulp Builds

4.1 What Is Gulp Doing?

The whats-er-name app uses gulp (a task runner) to create development and production builds that are opened in a browser and served from a local node server (e.g. localhost:3027). Basically, as you develop, a build is occurring (i.e. a bunch of tasks you don't want to run manually) every time you make a change to the source code. When a change is detected (i.e. files re-built) the browser tab serving the application is reloaded.

When you are done developing the application, a production build can be run (i.e. $ gulp prod) to convert your development code into production-ready code. Note that production code is served on a different server (localhost:3028) than development code and is not listening to changes from the development directory, therefore it will not reload the browser as you make changes.

Gulp tasks are configured in the gulpfile.js file found in the root directory of the application. You'll find the file is broken up into wwwDev and wwwProd tasks.

4.1 The wwwDev Build Process & Server

The wwwDev process are the gulp tasks, and reoccurring tasks, which get run during development.

The following list summarizes the development process and tasks:

  1. empties the wwwDev directory except for bower components
  2. parses the index.html file in src directory doing file includes, and places all .html files (including the updated index.html) from the src into the wwwDev directory
  3. starts a webserver at localhost:3027 that serves the wwwDev directory, and opens localhost:3027 in default browser on your machine
  4. listens for any change in src directory. If a change occurs it runs step 2

To start this process run $ gulp dev.

  • I'm not using any sort of CSS or JS pre-processors. But if you wanted to, you could easily adjust the wwwDev process to add them.

4.2 The wwwProd Build Process & Server

The wwwDev process are the gulp tasks which get run after development is done. The process will create a production-ready set of files. For more details on the wwwProd process examine the gulp.js file.

The following summarizes the production process and tasks:

  1. empty the wwwProd directory
  2. take wwwDev code, concatenate css and js based on build comments in index.html, version each file (e.g. whatsername-8b890cb0.js), place new code in wwwProd
  3. move all the image and font assets in wwwDev required by CSS to correct location in wwwProd
  4. lint CSS
  5. hint HTML
  6. hint JavaScript
  7. minify CSS, HTML, and JS
  8. start a web server at localhost:3028 serving the wwwProd directory, open localhost:3028 in default browser on local machine

To start the wwwProd process run $ gulp prod. For more details on the wwwProd process examine the gulp.js file.

5. whats-er-name Application Architecture

5.1 index.html Overview

There will be only one valid HTML file (i.e. doctype, header, etc..) in the entire application. It will be called index.html and it will reside in the src folder. All other assets will be considered a module that is included via index.html using a <script> element, <link> element, or the build process (i.e. client-side includes).

Consider index.html the master configuration file for including all the necessary modules (models, views, view-models, layouts, templates, CSS, JS etc..) to make the application run. If you open index.html and read the comments, it should be obvious that by running index.html in a browser it will load all modules and then instantiate the entire application.

Note that when the application is instantiated (i.e. is invoked) the mobile application logic is instantiating everything (e.g. view, layouts, widgets etc..) that is defined using declarative markup. In other words, anything declaratively defined is instantiated when the application first boots up.

5.2 Application Name Space

The Kendo UI Mobile application logic, by default, looks for supporting JavaScript in the global scope. This factor forces the use of a global name space instead of privately scoped modules with inject scopes. Thus the whats-er-name application uses a global name space to store JavaScript code relating to the application so that any module can gain a reference to another module's interface.

The name space whatsername and shortcut name space wrn are defined in the index.html file and shown below.

                                    this.whatsername = this.wrn = {}; //long and shortcut namespace

JavaScript modules need to be properly placed inside of the name space in an organized fashion. Meaning, for each JavaScript file (e.g. utilities, models, view-models) we have to create, or add, a name space for the code to live within. More detail around defining a JavaScript module for models, view-models, and utility modules will be given in the appropriate section of this chapter.

  • The Kendo UI Mobile application (i.e. the construction done via declarative instantiation), assumes that all dependencies can be found in the global scope. This is pretty much the opposite of dependency management/injection, and it's why you'll see references to deeply nested objects in the source code. The modules are not injected into scope, they are referenced where they are attached to the name space and sub name spaces. Obviously, more sophisticated solutions for dealing with scope and modules (i.e. dependency management/injection) are available today but layering these abstractions over the top of the current application logic adds unnecessary complexity. Using nested objects and having to type out longer object references is recommended because it works with the default behavior of the logic, not against it. If you are using Angular, then you'd obviously be going down the Angular road (i.e. dependency injection) leaving behind all the Kendo mobile application logic.

5.3 Run/Instantiate Application

As previously stated, the mobile application is instantiated by the last script parsed in the index.html file. This is where you would provide any settings for the instance. Below I am showing the JavaScript which instantiates the whats-er-name application.

                           = new$(document.body), { 
                                        skin: 'flat',
                                        initial: 'groupListView', //this is the initial view to load
                                        init: function() {
                                            //fix mouse events in iOS don't do it for android, causes more issues than it fixes
                                            kendo.UserEvents.defaultThreshold( === 'android' ? 0:20);

Don't forget, creating an instance of bootstraps the entire application.

5.4 Module Naming

The application is organized into logical directories and files based on the user interface. The directories and files are semantically named based on the semantical purpose of the view or feature in the UI (read more about this in section 3).

You can get a feel for what I am describing by simply examining the whats-er-name directories containing all of the modules in the app and comparing this to the actual whats-er-name UI.

├── index.html
├── shared
│   ├── css
│   │   ├── bootstrapOverides.css
│   │   ├── kendoOverides.css
│   │   └── whatsername.css
│   ├── layouts
│   │   ├── globalLayout.css
│   │   └── globalLayout.html
│   ├── models
│   │   ├── groupModel.js
│   │   └── viewerModel.js
│   └── utilities
│       └── extend.js
└── ui
    ├── appInfo
    │   ├── appInfo.css
    │   └── appInfoView.html
    ├── groups
    │   ├── addGroup
    │   │   ├── addGroupView.html
    │   │   └── addGroupViewModel.js
    │   └── groupList
    │       ├── groupList.css
    │       ├── groupListItemTemplate.html
    │       ├── groupListView.html
    │       └── groupListViewModel.js
    └── nameViewer
        ├── addName
        │   ├── addNameView.html
        │   └── addNameViewModel.js
        └── viewer
            ├── scrollerTemplate.html
            ├── viewerView.css
            ├── viewerView.html
            └── viewerViewModel.js

From the above directory tree you should note two things:

1) The view, model, view-model, template, and layout files end with a descriptive word describing what type of file they are, i.e. "View", "Model", "ViewModel", "Template", or "Layout". This is extremely handy when you have a lot of files open in a code editor or are grepping for a file.

2) The ui directories should contain modules named with the same root words contained in the directory name (e.g. the addName directory contains addNameView.html and addNameViewModel.js files).

5.5 Defining View Modules

View modules are html files containing mobile views with declarative attributes and likely declaratively define mobile widgets. This shouldn't be a surprise to you if you fully grok the MVVM pattern. The view declaratively connects to the view-model. For example, in the viewerView.html file shown below the data-model attribute binds viewerViewModel.js to the view declaratively when the application is started.

                                <div id="viewerView" 

When defining a view module, keep in mind each view is a mobile view widget and associated with a declaratively instantiated layout widget. The view also contains other mobile widgets that are likely connected to a view-model associated with a model.

  • Make sure you use the name of the view file, minus the extension, as the id for the view (e.g. id="viewerView" ). This pattern is used through out the whats-er-name app.
  • Any view specific CSS should be placed into a separate CSS file in the same directory as the HTML view. The name of the HTML view file should match the name given to the view CSS file (e.g. a viewerView.html css file would be called viewerView.css).

5.6 Defining Layout Modules

The whats-er-name application uses a single layout for all of its mobile views (i.e. /src/shared/layouts/global/globalLayout.html), but if you mimic the architecture prescribed in this guide, you will probably have more than one view layout and associating styles. When this occurs, the HTML and CSS should be placed in the same directory which contains the view HTML. Make sure you end both files with the word "Layout".

For example, if the viewerView.html module used a unique layout, there would be a viewerLayout.html module and possibly a viewerLayout.css file in the same directory (or, shared directory if the view shared the layout with another view).

5.7 Defining view-model Modules

There is a strong relationship between the view and the view-model. In the MVVM pattern the view-model typically contains controller-like logic. One can declaratively create a lot of abstracted functionality in the HTML view, but it's the view-model where all of the observed JavaScript code resides that drives the view.

Below is an example of the the pattern used to create a view-model JavaScript module. It should look somewhat familiar, as it's a simple and common module pattern/definition used in JavaScript applications.


                                    'use strict';

                                    //below you place anything private you don't want exposed in the viewModel

                                    //below we create the viewModel

                                    wrn.viewer = {  //create viewModel namespace in global

                                            //the actual model
                                            modelData: wrn.viewerModel,

                                            //other properties or functions you want to observe and expose to html
                                            init:function(){ ... },
                                            show:function(){ ... },
                                            anyFunction:function(){ ... },

                                })(wrn); //pass in global namespace

Three things are occurring and should be repeated when creating view-models:

  1. The name space should be exactly the same name of the directory that contains the view-model module (e.g. wrn.viewer).
  2. The view-model name space is an object that contains a viewModel property that stores an instance of kendo.observable.
  3. If the view-model uses a model, then it's stored as an observable property called modelData, which references a model module in the name space.
  • The whats-er-name application does not contain any models that are unique to a view. The two models used are shared among multiple views, and thus found in the shared directory. If a view has a unique model, it would, of course, be found in the same directory as the view-model and the rest of the supporting modules.

5.8 Defining Model Modules

The pattern for creating model JavaScript files differs from creating model-view files. Models should be stored one level deep from the top global name space in a logical and semantically minded name space (e.g. viewerModel). This is because models are typically used by several views. In the whats-er-name application this is why the two models used in the application are found in the shared directory and not a view-specific directory. It would not be logical to place models on the name space of a specific view because of the potential of being used by more than one view. Therefore, models are never properties of view name spaces (i.e. wrn.viewer.model = ...).

Below I am showing the pattern for defining models:

                                    'use strict';

                                    wrn.viewerModel = new{
                                        offlineStorage: 'viewerModel',
                                        schema: {
                                            model: {
                                                id: "id"


                                })(wrn); //pass in global namespace
  • Model name spaces should end with "Model".
  • If a model does not get used by more than one logical ui grouping, it would be perfectly logical to store it in the directory containing the rest of the ui's specific files.
  • A model can often be a simple, static JSON object but it's more likely that you'll be using the Kendo UI DataSource abstraction to wrap local or remote data. In the whats-er-name app I am using it to force a DataSource into offline mode to manage JSON in localStorage.

5.9 Defining Utility Modules

Any utility objects/functionality needed by all JavaScript modules can be place directly on the name space object as property which specifically describes the utility. Below I show the makeId.js utility code as an example pattern for adding utility JavaScript modules into the whats-er-name architecture.


                                    'use strict';

                                    wrn.makeId = function(){
                                        'use strict';
                                        var n = 0;
                                        var possible = "0123456789";
                                        for (var i = 0; i < 15; i++){
                                            n += possible.charAt(Math.floor(Math.random() * possible.length));
                                        return Number(n);

                                })(wrn); //pass in global namespace

Utility modules are always stored in the shared/utilities directory.

5.10 Defining Template Modules

Kendo UI mobile widgets can make use of Kendo UI templates. The whats-er-name application uses <script> elements to house Kendo UI Mobile HTML templates in .html files (included into the index.html using client-side includes).

Shown below is an example of a template (e.g. /src/ui/nameViewer/viewer/scrollerTemplate.html) used by the mobile scroller widget in the viewerView.html view.

                                <script id="scrollerTemplate" type="text/x-kendo-template">
                                    <a class="removePhotoNameBtn deleteBtn" data-role="button" data-bind="click:removePhotoName,invisible:notEditMode" data-id="#= id #">
                                        <span class="glyphicon glyphicon-trash"></span>
                                        <div class="photo" style="background-image:url(#= image #)"></div>
                                        <div class="photoName"><span>#= name #</span></div>

Make sure you give the <script> an id (e.g. id="scrollerTemplate") so that the widgets in your views can point to the template.

  • Template module files should end with the string "Template" (e.g. scrollerTemplate.html)
  • To clarify, template modules house an html <script> element that contains HTML. Notice that Kendo UI templates construed using a <script> (as opposed to JS strings, in JS) have a custom type of text/x-kendo-template.

5.11 Use Imperative Widget Instantiation When Needed

Don't be too dogmatic about only using declarative instantiation patterns for widgets contained in mobile views. Sometimes it's necessary to imperatively instantiate a mobile widget using code, not markup. You simply have no choice in the matter. I chose to imperatively create the kendoMobileScrollView widget in the viewerViewModel.js file because it was logically necessary. Sometimes it's simply the path of least resistance in terms of code and code complexity. Other times, its the only solution.

6. whats-er-name Coding Style

6.1 Editor Configuration

A .editorconfig (found in root directory) is used to maintain consistent coding styles between different code editors. Below I am showing the .editorconfig used in the whats-er-name application.

                                root = true

                                indent_style = tab
                                end_of_line = lf
                                charset = utf-8
                                trim_trailing_whitespace = true
                                insert_final_newline = true

                                indent_style = space
                                indent_size = 2

6.2 HTML Hinting

The HTMLHint static code analysis tool is used to avoid simple and pesky errors that can occur in HTML.

In the whats-er-name app I am using a .htmlhintrc file (found in root directory) to setup the rules for this analysis. The analysis is currently running during the production build, but I recommend you also run it locally via your code editor while coding. Below are the contents of the .htmlhintrc used in the whats-er-name app.

                                    "attr-value-double-quotes": true,
                                    "tagname-lowercase": true,
                                    "attr-value-not-empty": true,
                                    "attr-no-duplication": true,
                                    "tag-pair": true,
                                    "id-unique": true,
                                    "head-script-disabled": false,
                                    "doctype-first": false


6.3 CSS Linting

The CSSLint code quality tool is used to analyze CSS for errors or potential other issues that might cause problems.

In the whats-er-name app I am using a .csslintrc file (found in root directory) to setup the rules for this analysis. The analysis is currently running during the production build, but I recommend you also run it locally via your code editor while coding. Below are the contents of the .csslintrc used in the whats-er-name app.

                                    "adjoining-classes": false,
                                    "box-model": false,
                                    "box-sizing": false,
                                    "bulletproof-font-face": false,
                                    "compatible-vendor-prefixes": false,
                                    "display-property-grouping": false,
                                    "duplicate-background-images": true,
                                    "duplicate-properties": true,
                                    "empty-rules": true,
                                    "errors": true,
                                    "fallback-colors": false,
                                    "floats": false,
                                    "font-faces": false,
                                    "font-sizes": false,
                                    "gradients": false,
                                    "ids": false,
                                    "import": false,
                                    "important": false,
                                    "known-properties": false,
                                    "outline-none": false,
                                    "overqualified-elements": false,
                                    "qualified-headings": false,
                                    "regex-selectors": false,
                                    "rules-count": false,
                                    "selector-max": false,
                                    "selector-max-approaching": false,
                                    "shorthand": false,
                                    "star-property-hack": false,
                                    "text-indent": false,
                                    "underscore-property-hack": false,
                                    "unique-headings": false,
                                    "universal-selector": false,
                                    "unqualified-attributes": false,
                                    "vendor-prefix": false,
                                    "zero-units": false

6.4 JS Hinting

The JSLint tool is used to detect errors and potential problems in JavaScript code as well as enforce coding conventions.

In the whats-er-name app I am using a .jshintrc file (found in root directory) to setup the rules for this detection. JSHhint is currently running during the production build, but I recommend you also run it locally via your code editor while coding. Below are the contents of the .jshintrc used in the whats-er-name app.

                                    maxerr: 50,
                                    bitwise: true,
                                    camelcase: false,
                                    curly: true,
                                    eqeqeq: true,
                                    freeze: true,
                                    forin: true,
                                    immed: false,
                                    indent: 4,
                                    latedef: false,
                                    newcap: false,
                                    noarg: true,
                                    noempty: true,
                                    nonbsp: true,
                                    nonew: false,
                                    plusplus: false,
                                    quotmark: false,
                                    undef: false,
                                    unused: true,
                                    strict: true,
                                    maxparams: false,
                                    maxdepth: false,
                                    maxstatements: false,
                                    maxcomplexity: false,
                                    maxlen: false,
                                    asi: false,
                                    boss: false,
                                    debug: false,
                                    eqnull: false,
                                    es5: false,
                                    esnext: true,
                                    moz: false,
                                    evil: false,
                                    expr: false,
                                    funcscope: false,
                                    globalstrict: false,
                                    iterator: false,
                                    lastsemic: false,
                                    laxbreak: false,
                                    laxcomma: false,
                                    loopfunc: false,
                                    multistr: false,
                                    noyield: false,
                                    notypeof: false,
                                    proto: false,
                                    scripturl: false,
                                    shadow: false,
                                    sub: false,
                                    supernew: false,
                                    validthis: false,
                                    browser: true,
                                    couch: false,
                                    devel: true,
                                    dojo: false,
                                    jasmine: false,
                                    jquery: true,
                                    mocha: true,
                                    mootools: false,
                                    node: false,
                                    nonstandard: true,
                                    prototypejs: false,
                                    qunit: false,
                                    rhino: false,
                                    shelljs: false,
                                    worker: false,
                                    wsh: false,
                                    yui: false,
                                    globals: ["whatsername","wrn","kendo","_","canvasResize"]
  • Gulp is actually creating the .jshintrc from a file called .jshintrcCommented.txt before it uses the .jshintrc for configuration. I did this because I wanted a commented/documented file containing the configurations and JSON is invalid when it contains comments. So, I set the configurations in the commented file, but Gulp converts it to the .jshintrc file first then uses it to hint JavaScript files.
  • JavaScript code style can be enforced using something like JSCS. I have not implemented JS style enforcement to this degree in the whats-er-name app, but if I was going to work on this application with another developer I would likely add JSCS.

7. Conclusion

The entire point of this guide was to offer opinionated insights into developing sites and applications using Kendo UI mobile widgets and its application logic. I have yet to offer any insights into actual hybrid mobile development. Once the Kendo UI mobile solution, as a whole, has been properly grokked, the next logical question is how does one take this knowledge and use it to develop a hybrid mobile application.

The next part of this guide will offer insights into hybrid mobile development using Kendo UI mobile and AppBuilder together. This will be accomplished by taking the whats-er-name application and re-developing it, assuming a hybrid approach is the focus of the insights offered.