Create your first HTML-based Apollo application

Back to: Apollo Documentation home page

This section describes how to create a simple html-based Apollo application. It walks you through the steps for creating the application files, testing the application, and packaging it using the tools in the Apollo SDK. The application also demonstrates adding data from an XMLHttpRequest to an application page using JavaScript.

Before starting, you should have downloaded and installed the Apollo SDK. See Set up instructions for HTML developers for more information.

Contents
Create the project files Create the Apollo application descriptor file Create the application HTML page Create the sample text file Test the application Package the application

Create the project files

At a minimum, every HTML-based Apollo project must have two files, an application descriptor file, which specifies the application metadata, and a top-level HTML page. This Hello World example also uses a third file containing some HTML-formatted text to be loaded into the application via JavaScript.

To get started, create a directory named, for example, helloapollo, to contain the project files. In a larger-scale application you can have a more complex directory structure – and this might affect how you run the command-line tools – but, for this simple exercise, a single directory is fine.

Create the Apollo application descriptor file

The application descriptor file is an XML file with the following structure:

<application>
	<properties>…</properties>
	<rootContent>…</rootContent>
</application>

Create an XML file named HelloApollo-app.xml with the above structure and then add the content:

Set the following attributes for the <application> element:
```
appID= "samples.HelloApollo"
```
The appID uniquely identifies your application. The recommended form of an appID is a dot-delimited, reverse-DNS-style string, such as: "com.company.AppName". This value is used for both installation and inter-application communication. If two applications use the same appID, installing the second application will overwrite the first application.
```
xmlns="http://ns.adobe.com/apollo/application/1.0.M3"
```
This is the Apollo namespace. Set to reflect the earliest version of Apollo runtime that your application supports.
```
version="0.1"
```
The version designator helps users to determine which version of your application they are installing.
Add the following child elements within the <properties> element:
```
<name>Hello Apollo!</name>
```
The name value identifies your application to users and is used in the default installation path (so it must conform to Windows and Mac OS X folder name conventions).
```
<publisher>My company name</publisher>
```
The publisher value is displayed in the Apollo installer and, on Windows, is used as part of the default installation path.
```
<description>The ubiquitous Hello World example.</description>
```
The description value is displayed in the Apollo installer (optional).
```
<copyright>&#xA9;2007</copyright>
```
The copyright information (optional).
Add the following attributes to the <rootContent> element to specify how your application window will be displayed:
```
systemChrome="standard"
```
This setting will display the application within a standard window. See Defining the rootContent element for other possible settings.
```
visible="true"
```
We want the window to be visible when it opens. In some cases, you might want to initialize the visible property to false so that you can alter the window before showing it to your user.
Set the text content of the <rootContent> element to the path to the application’s top-level HTML page:
```
<rootContent>HelloApollo.html</rootContent>
```

Save the file. Your complete application descriptor file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://ns.adobe.com/apollo/application/1.0.M3" 
  appId="samples.HelloWeb" version="0.1">
  <properties>
    <name>Hello Apollo!</name>
    <publisher>My company name</publisher>
    <description/>
    <copyright/>
  </properties>
  <rootContent systemChrome="standard" visible="true">HelloApollo.html</rootContent>
</application>

Create the application HTML page

The code for this example is a basic HTML page with a few JavaScript functions.

First, create a file named HelloApollo.html (the name must match the name you used in the <rootContent> element of the application descriptor file). Using any HTML or text editor, add the following:

<html>
<head>
  <title>Hello Apollo!</title>
</head>
<body onLoad="appLoad();">
  <h1>Apollo</h1>
  <div id="replace">
  	<p>Placeholder</p>
  </div>
</body>
</html>

One thing worth noting, is that by the time the <body> element’s onLoad event is fired, Apollo has initialized the application so it is safe to access the additional Apollo APIs provided via the window.runtime property.

Now add the JavaScript that handles the onLoad event:

<script type="text/javascript"><!--   
  function appLoad(){
  	if(window.runtime){
  		runtime.trace("Hello Apollo.");
	}
	xmlhttp = new XMLHttpRequest();
	xmlhttp.open("GET", "request.txt",true);
 	xmlhttp.onreadystatechange=function() {
  		if (xmlhttp.readyState==4) {
			document.getElementById('replace').innerHTML = xmlhttp.responseText;
  		}
 	}
 	xmlhttp.send(null)
  }  
  --></script>

The function first checks that runtime is defined, and if it is, calls the runtime.trace function. The trace message will be printed to the command console when the application is run using ADL. Apollo adds the runtime object to the HTML window object when an HTML page is loaded. All calls to ActionScript APIs are made through this object, using the fully qualified package name of the class. trace is a top-level function, so no additional qualifiers are needed, but to create a new Apollo File object, for example, you would use:

var myFile = new runtime.flash.filesystem.File();

See ActionScript basics for JavaScript developers for more information.

The rest of the appLoad() function is standard JavaScript. The function creates an XMLHttpRequest to load some simple data from a local file and changes the text displayed on the page.

The complete HelloApollo.html file should look like:

<html>
<head>
  <title>Hello Apollo!</title>
  <script type="text/javascript"><!-- 
  
  function appLoad(){
  	if(window.runtime){
  		runtime.trace("Hello Apollo.");
	}
	xmlhttp = new XMLHttpRequest();
	xmlhttp.open("GET", "request.txt",true);
 	xmlhttp.onreadystatechange=function() {
  		if (xmlhttp.readyState==4) {
			document.getElementById('replace').innerHTML = xmlhttp.responseText;
  		}
 	}
 	xmlhttp.send(null)
  }  
  --></script>
</head>

<body onLoad="appLoad();">
  <hi>Apollo</h1>
  <div id="replace">
  	<p>Placeholder</p>
  </div>
</body>
</html>

Create the sample text file

The sample text file contains a simple HTML-formatted string. Create a text file named, request.txt (matching the relative URL used in the XMLHttpRequest in the HTML file). Add the following text to the file:

Hello <b>Apollo</b>!

Save the file and you are ready to run.

Test the application

Use the Apollo Debug Launcher (ADL) to run the example as an Apollo application. (See Adding the Apollo tools to your class path for information on setting up your path to run the ADL and ADT tools.)

First, open a command console or shell. Change to the directory you created for this project. Then, run the following command:

adl HelloApollo-app.xml

An Apollo window opens, displaying your small application.

Also, note that the console window displays the message resulting from the ActionScript trace call.

Trace statements can be used to help debug HTML-based applications. Another useful technique for debugging is to compartmentalize your code such that you can exercise the JavaScript logic in a browser that supports full JavaScript debugging. This example uses that technique by testing to see whether the runtime property is defined before calling any ActionScript code. That means you can run the example in a browser as well as Apollo. Apollo’s HTML rendering is based on Webkit, so JavaScript that runs in Apollo will also run in the Safari and (usually) FireFox browsers. This example will not run in Internet Explorer 6.0, for example, because that browser uses a different method for making XMLHttpRequests.

See Debugging using the Apollo Debug Launcher for more information on running applications with ADL.

Package the application

Once your application works as desired, you can use the ADT tool to package the files for installation:

adt –package HelloApollo.air HelloApollo-app.xml HelloApollo.html request.txt

The first argument after the –package command is the name of the AIR file that ADT will produce. The second argument is the name of the application descriptor file. The subsequent arguments are the files used by your application. This example only uses two files, but you can include any number of files and directories.

After the AIR package is created, you can double-click, Ctrl-Click or type the AIR file name as a command in the shell to install and run the application.

See Packaging an Apollo application using the Apollo Developer Tool for more information on packaging applications with ADT.

Back to: Apollo Documentation home page