Introduction
This is the first in a series of articles covering how to develop HTML5 applications for Intel AppUp center. This first article will cover the basics of getting a minimal application packaged using the Intel AppUp™ 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 AppUp 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 AppUp 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 the Intel AppUp(SM) developer program. Then I will walk you through the steps of packaging the code as an application using AppUp 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 is 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 1
Now 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 2
Let'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" class="button black" onclick="fullScreen()">Set Full Screen Mode</a>
<a href="#" id="ExitFullScreen" class="button white" onclick="exitFullScreen()">Exit Full Screen Mode</a>
<a href="#" id="CloseApp" class="button blue" onclick="closeApplication()">Close Application</a>
Listing 4: Main HTML File Part 4
Here is our JavaScript file, functions.js. It simply implements three functions by calling functions that are provided in the API. The functions should be self-explanatory, and are described in more detail here. The file is shown in its 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 File
Finally, 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 File
The 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:
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 application looks ready, we can proceed to use Intel AppUp encapsulator to package it as an application.
Using Intel AppUp™ encapsulator
Intel AppUp 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.
Figure 2: Making the ZIP file
Now we are ready to go to AppUp 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:
Figure 3: Filling Out AppUp encapsulator Fields
Now you can click on Make it and AppUp encapsulator will examine your application files and let you know if there are any problems; itis 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 the AppUp encapsulator packages your application for each platform. The screen shot in Figure 4 below illustrates this.
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: Intel AppUp 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:
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:
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:
Figure 7: Uninstalling the Application
Deploying to the Intel AppUp(SM) center
For a real application that you want to offer as a download, you'll want to deploy it to the Intel AppUp center. 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 AppUp encapsulator but typically won't let you fully test your application because it's running in a different environment from the 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 the AppUp center as a released version, the Inspect menu will not appear. Figure 8 shows Web Inspector running.
Figure 8: Web Inspector
As the HTML5 standard is still evolving, web rendering engines don't support all features. There are some limitations in the Qt WebKit-based rendering engine used by the AppUp encapsulator wrapper program. The HTML5 features that this tool 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
Summary
In this tutorial we've covered the basics of using Intel AppUp encapsulator to package a simple HTML5 application. I hope this simple example provides a good starting point for your applications. In future installments we will look at some more complex HTML5 applications that illustrate additional HTML5 features supported by the AppUp encapsulator.
Copyright © 2011, Intel Corporation.
Tizen™ is a trademark of the Linux Foundation
