Introduction

This is the first in a series of articles covering how to develop HTML5 applications for Intel AppUp. This first article will cover the basics of getting a minimal application packaged using the Encapsulator tool. Later articles will describe some larger example applications that illustrate different features of HTML5. The assumption is that you are somewhat familiar with HTML5 or at least HTML4 and JavaScript.

We’ll focus on the Windows platform although Encapsulator will also produce packages that will run on the Netbook version of MeeGo. The intention is that these applications will also run on other platforms in the future, such as Tizen, with little or no changes.

All of the source files described in this article can be downloaded from here.

Note that at the time of writing, the Encapsulator tool is still in beta test. There may be some differences between what is described and shown here and the final release.

Minimal Application

For this first example we just want to display a web page, use a simple style sheet, and write some JavaScript. I’ll show how to use some of the APIs provided by AppUp. Then I will walk you through the steps of packaging the code as an application using Encapsulator and then installing and running it on a Windows desktop.While we could put all the code in a single HTML file, for all but the simplest application it’s good practice to put JavaScript in one or more separate files. We’ll also include a CSS file to illustrate typical usage of style sheets.

To start, we need a main HTML file, index.html, that will reference our style sheet (app.css) and an external JavaScript file (functions.js). The main html file needs to be named index.html; the other files can be any name you wish. The first few lines of our index.html file are shown in Listing 1 below. We reference the style sheet and the JavaScript file.

  <!DOCTYPE HTML>
  <html>
    <head>
      <title>HTML5 Application: Simple Example</title>
      <link href="app.css" rel="stylesheet" type="text/css" />
      <script src="functions.js" type="text/javascript"></script>
    </head>

Listing 1: Main HTML File Part 1Now let’s implement the body of the web page with a heading and some text. This is shown in Listing 2:

  <body>
    <h1>HTML5 Application: <em>Simple Example</em></h1>

      This is a simple first example of an HTML5 application. It illustrates
      what is needed to use Encapsulator to package an HTML5 application for
      AppUp. As well as a single HTML file, it includes a JavaScript file
      and style sheet. It shows how to call some of the Encapsulator AppUp
      APIs and use some HTML5 features.

  </hr>

Listing 2: Main HTML File Part 2Let’s provide three buttons, associating them with the JavaScript functions we want to execute when they are pressed. The code for these buttons is shown in Listing 3:

<a href="#" id="FullScreen" onclick="fullScreen()">Set Full Screen Mode</a>
<a href="#" id="ExitFullScreen" onclick="exitFullScreen()">Exit Full Screen Mode</a>
<a href="#" id="CloseApp" onclick="closeApplication()">Close Application</a>

Listing 3: Main HTML File Part 3And finally, we’ll close off the page with some copyright information and the ending body and html tags:

  <br><br><hr>
  <address><br>Copyright © 2011, Intel Corporation.</address>
</body>
</html>

Listing 4: Main HTML File Part 4Here is our JavaScript file, functions.js. It simply implements three functions by calling functions that are provided in the Intel AppUp API. The functions should be self explanatory, and are described in more detail here. The file is shown in it’s entirety in Listing 5:

 

function closeApplication()
{
    intel.adp.encapsulator.closeapplication();
}

function fullScreen()
{
    intel.adp.encapsulator.setfullscreen();
}

function exitFullScreen()
{
    intel.adp.encapsulator.exitfullscreen();
}

Listing 5: JavaScript Functions FileFinally, we provide a style sheet, app.css, that provides some styling for our buttons. I won’t list the entire file here as it is somewhat large and not particularly interesting. You can download and examine it if you wish. Listing 6 shows a portion of the file.

BODY {
 background-color: grey
}

.button {
	display: inline-block;
	margin: 0 2px;
	outline: none;
	cursor: pointer;
	text-align: center;
	text-decoration: none;
	font: 14px/100% Arial, Helvetica, sans-serif;
	text-shadow: 0 1px 1px rgba(0,0,0,.3);
}

Listing 6: Portion of CSS FileThe final thing we need to satisfy AppUp is an icon file. This will be used when the application is packaged. It needs to needs to be in PNG format, named icon.png, and needs to be square with a resolution of at least 128 by 128 pixels. Figure 1 shows the icon I created:
 
Developing HTML5 Applications AppUp Simple Example 1 Developing HTML5 Applications for AppUp Part 1: A Simple Example
 
Figure 1: Application Icon

Given these files you could now test the application locally using a web browser. The only limitation is that your browser won’t recognize the AppUp JavaScript API functions. In the case of this simple application, testing it locally in a web browser is an efficient way to initially check that the user interface looks correct.

Now that our applications looks ready, we can proceed to use Encapsulator to package it as an application.

Using Encapsulator

Encapsulator is a web-based tool that takes our HTML5 application and packages it as a native application for AppUp for each platform.

The first step is to package up our application’s files into a ZIP archive. Figure 2 shows a screen shot I made when I did this on a Windows 7 desktop using Windows Explorer. We need to include the four files we created earlier: the main HTML file, the JavaScript file, the CSS file, and the icon.
 
Developing HTML5 Applications AppUp Simple Example 2 1 Developing HTML5 Applications for AppUp Part 1: A Simple Example
 
Figure 2: Making the ZIP file

Now we are ready to go to Encapsulator by opening the URL with a web browser. After reading the information in the Introduction tab, go to Make your app. We need to fill in the required fields in the form. If you need help understanding any of the fields, click on the “?” button. After filling in all the information, click on Choose File to select and upload the ZIP file containing the application files. Figure 3 shows an example for our simple example application:
 
Developing HTML5 Applications AppUp Simple Example 3 1 Developing HTML5 Applications for AppUp Part 1: A Simple Example
 
Figure 3: Filling Out Encapsulator Fields

Now you can click on Make it and Encapsulator will examine your application files and let you know if there are any problems. Encapsulator is pretty good at detecting errors and telling you what is wrong, e.g. missing or too small icon file, incorrect version string format, etc.

If all goes well, the Check status and download tab will become active and you can monitor the status as Encapsulator packages your application for each platform. The screen shot in Figure 4 below illustrates this.
 
Developing HTML5 Applications AppUp Simple Example 4 1 Developing HTML5 Applications for AppUp Part 1: A Simple Example
 
Figure 4: Check Status and Downloads

When your application is successfully packaged, the web interface will indicate this and provide a link for you to download the packages. For Windows it will be an MSI file and for MeeGo an RPM package. If packaging fails, the reason should be indicated and you can go back and fix the problem and submit it again.

Let me say a few words about what is happening behind the scenes to build the packages: Encapsulator builds a native application which has an HTML rendering engine. Currently it uses the Qt toolkit and QtWebKit. The web view in the application opens your application’s index.html file. This wrapper application is compiled for each platform and packaged in the appropriate format, including the icon and any other files you included in the zip archive.

On MeeGo the package is an rpm file. It uses the version of Qt that is installed on MeeGo for Netbooks. The package can be installed with the “rpm” command.

On Windows the package is an MSI file which includes a graphical install/uninstall wizard. The package includes Qt and any other DLLs that are needed by the native wrapper application.

Installing, Running, and Uninstalling

Now that our package is built, let’s install and test it. On Windows, download the generated MSI file and run it. You should see an installer like the one below in Figure 5:
 
Developing HTML5 Applications AppUp Simple Example 5 1 Developing HTML5 Applications for AppUp Part 1: A Simple Example
 
Figure 5: Application Installer

After the installer completes you can launch the application, either from the icon on the desktop or start menu. For our simple application, it should appear as in Figure 6 below:
 
Developing HTML5 Applications AppUp Simple Example 6 1 Developing HTML5 Applications for AppUp Part 1: A Simple Example
 
Figure 6: Simple Example Running

Now you can finish testing. With our simple application you can try the three buttons and confirm that they perform the expected functions.

If you want to uninstall the application you can do that from the Windows Control panel. On Windows 7 it should look like the screen shot in Figure 7 below:
 
Developing HTML5 Applications AppUp Simple Example 7 1 Developing HTML5 Applications for AppUp Part 1: A Simple Example
 
Figure 7: Uninstalling the Application

Deploying to the AppUp Store

For a real application that you want to offer as a download, you’ll want to deploy it to the AppUp store. We’ll cover the additional steps to do this in a future article.

Other Tips

Here are a few miscellaneous tips that you may find useful.

To debug your application, I mentioned earlier the strategy of first running it locally in a browser. This avoids the upload / generate / download cycle of using Encapsulator but typically won’t let you fully test your application because it’s running in a different environment from the AppUp wrapper application. For testing and debugging the application there is a useful tool called Web Inspector that is built into the WebKit rendering engine. If you right click on the web view, you will see an “Inspect” menu entry. This opens the Web Inspector. As well as being able to see errors and debug JavaScript, you can do a number of things including seeing the HTML elements and getting performance information. When your application is submitted to AppUp as a released version, the Inspect menu will not appear. Figure 8 shows Web Inspector running.
 
Developing HTML5 Applications AppUp Simple Example 8 1 Developing HTML5 Applications for AppUp Part 1: A Simple Example
 
Figure 8: Web Inspector

As the HTML5 standard is still being evolving, web rendering engines don’t support all features. There are some limitations in the QtWebKit-based rendering engine used by the the Encapsulator wrapper program. The HTML5 features that Encapsulator supports are documented here. Over time, you can expect the level of HTML5 support to continue to improve.

You can’t do too much testing! Here are some things to consider when you test your application:

  • exercise all the features of your application
  • test on all platforms you want to support (e.g. Windows and MeeGo)
  • test on multiple versions of the platform, e.g different versions of Windows
  • verify that the installer program installs all required files, and no more and no less
  • verify that the uninstaller removes all files
  • use the Web Inspector to check for JavaScript errors or warnings and run the Audits feature

 

Source Intel AppUp(SM) Developer Program