Icenium: Blank Project and Hello World

In my last post we explored how easy it is to dive into Icenium to create cross-platform HTML5 hybrid mobile applications. This time we'll take a closer look at the project files and how they work together by creating a blank project and using it to display a “Hello, World” message.

Creating a Blank Project

As mentioned before, Icenium has several project types to get you started. In later posts, we'll be making use of the Kendo Mobile project, since this is my platform of choice for mobile and web development. However, to keep things as simple as possible for this example, we'll start with just the Blank project.  This generates an Icenium project with the absolute bare minimum of files needed to create a simple cross-platform application.  Running the app reveals a simple static application, which shows a status message updating from “Connecting to the device” to “Device is ready”.  We'll see how this is done with JavaScript shortly, but first let’s explore the different components that make up the solution.

HTML 5

Remember that Icenium is simply a platform for developing hybrid, native-looking mobile apps using standard HTML 5, CSS, and JavaScript. As a result, the application is structured, and behaves just like a standard web site, including the default “index.html” page. Notice that this html file references both the index.css and index.js files, which respectively define the style and behavior for the application. Creating additional views and sections of your app is as simple as adding a new set of these files and linking to them via a standard navigation menu. However, as we'll see in future posts, with Kendo Mobile you define multiple views in a single page, reducing the need to duplicate the HTML across different files and making it easier to organize and manage your project.

Cordova and JavaScript

The heart of the application lies in the cordova.js file, which defines all of the behaviors exposed by the Cordova library. This library grants you access to several device features such as the camera, accelerometer, and more, wrapping them into simple JavaScript calls. In addition, several events are exposed, such as “deviceready”, which allow you to ensure that your application only begins when the application is fully loaded. If you look at the index.js file for the sample app, you can see it is here that controls the changing of the application message to ready status using simple JavaScript.

onDeviceReady: function() {

    app.receivedEvent('deviceready');

    navigator.splashscreen.hide();

},

// Update DOM on a Received Event

receivedEvent: function(id) {

    var parentElement = document.getElementById(id);

    var listeningElement = parentElement.querySelector('.listening');

    var receivedElement = parentElement.querySelector('.received');

    listeningElement.setAttribute('style', 'display:none;');

    receivedElement.setAttribute('style', 'display:block;');

    console.log('Received Event: ' + id);

}

Icenium can make use of any of the base plugins of the Apache Cordova API, and even supports custom Cordova plugins, granting even more powerful functionality. Just be sure to review the requirements for custom Cordova plugins in the Icenium documentation.

Cordova Limitations in the Icenium Simulator

There’s one important thing to note when working with the Cordova library; for the most part, none of these behaviors are supported in the Icenium Simulator. For testing and verifying behavior it is entirely suggested that you rely on an actual device to deploy and test your compiled application. This took me a bit by surprise, and during my testing I assumed I had a bug in my code when behaviors either didn't appear as expected, or didn't function at all. So keep in mind that while the simulator is great for testing and reviewing layouts, navigation, and style, for testing the actual app behavior, you're definitely going to want to use a device. The good news is that the Icenium team is continuing to improve the simulator with every release, so expect this experience to improve over time. In addition, the Icenium LiveSync feature makes testing on devices a breeze, since any changes in your project are immediately reflected on the app.

Hello World

Now that we have a better understanding of the building blocks of this simple Icenium app, let’s add some Hello World functionality by creating an HTML button, and taking advantage of support for the base Notification Cordova plugin. All we really need to do to begin is add some markup for the button. In this case I'm going to add it inside the “Device Ready” paragraph element, so it only shows when the device is fully loaded and ready. Next, referring to the Cordova documentation for notifications, I simply call the notification api with some appropriate arguments:

buttonClick: function() {

    navigator.notification.alert(

    'Hello, World!',  // message

    null,         // callback

    'Message',            // title

    'Ok'                  // buttonName

);

As mentioned before, if we run the app in the simulator, we're not going to get the native notification, but rather the standard browser alert.  However, deploying the device to the app reveals a much more native look as we expected, and in addition of course, automatically adjusts the notification visually for each platform

Next Steps

The blank project is nice for poking around the system and getting familiar with the environment. However, for more complex projects you're going to want to take advantage of the starter projects provided such as Kendo Mobile, which we will look at in our next post.