Apollo Alpha 1 Documentation - collected by Jimbob | Back to MY RESOURCES


About HTML-based applications

Back to: Apollo Documentation home page

Contents
  1. Overview: HTML-based applications
  2. HTML-based application structure
  3. Calling Apollo runtime classes
  4. Initializing your application
  5. Making an XMLHttpRequest
  6. Creating a new window
    1. NativeWindows versus HTML windows

Overview: HTML-based applications

Apollo applications can be created entirely in HTML and JavaScript. Apollo uses WebKit to interpret, layout, and render HTML and JavaScript. Most existing HTML applications should run unchanged (assuming they use HTML, CSS, DOM, and JavaScript features compatible with WebKit).

The built-in host classes and objects of Apollo provide an API for features traditionally associated with desktop applications, such as reading and writing files, and managing windows. An HTML-based Apollo application can also use the entire Flash API, which provides features like sound and binary sockets.

Using the Apollo and Flash APIs is entirely optional. You can choose how much of your application to program in HTML and JavaScript, and how much to program using the Apollo host objects and API. If you want your application to work in both a web browser and as an Apollo desktop application, you can encapsulate the Flash and desktop-specific features of Apollo such that those features degrade gracefully when your application is run in a web browser. In other words, you can employ the same techniques you would typically use to achieve cross-browser compatibility.

For a short introduction to the basics of building an HTML-based Apollo application, see Create your first HTML-based Apollo application.

Common application tasks:

HTML-based application structure

An HTML-based application contains a complete browser-like JavaScript environment with an HTML renderer, document object model, and JavaScript interpreter. Apollo adds a new property, runtime to the JavaScript Window object. The runtime property allows you to instantiate and use the built-in Apollo runtime classes and objects. Built-in classes include the Apollo and Flash player APIs (but not, for example, the Flex framework).

Every Apollo application has a Shell object that represents the operating system shell of the computer on which the application is run (for example, the Windows Explorer or the Mac OS X Finder). The Shell is a singleton object (only one instance can exist in an application) and can be accessed in JavaScript code through the static Shell class property as follows: 

  var shellReference = runtime.flash.system.Shell.shell;

Note, that if your page unloads, the JavaScript environment is refreshed. References to instances of objects created by the unloaded page code may be lost, and the objects garbage collected, when a new page is loaded.

Calling Apollo runtime classes

A number of host classes are available in the Apollo runtime that are not available in a web browser. This lets you access the advanced features that Apollo provides, including:

Also, Apollo runtime classes provides the API for Apollo features, such as access to the file system.

For example, The Apollo file API includes a File class, contained in the flash.filesystem package. You can create a new File object in JavaScript as follows: 

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

The runtime object is a special JavaScript object, available to HTML content running in Apollo. It lets you access runtime classes from JavaScript. The flash property of the runtime object provides access to the flash package, and the flash.filesystem property of the runtime object provides access to the flash.filesystem package (and this is the package that includes the File class). Packages are a way of organizing classes used in ActionScript. (For details on packages, see ActionScript 3.0 Classes, packages, and namespaces).

Classes added for the Apollo runtime are discussed throughout the Common development tasks section of this documentation. Other classes of interest to HTML developers are described in the Apollo Language Reference. In the current alpha release of Apollo, the language reference for these classes is written using ActionScript syntax. ActionScript is the language used in SWF (Flash) content. However, JavaScript and ActionScript syntax are quite similar. (They are both based on versions of the ECMAScript language.) For an overview of the ActionScript language, see ActionScript basics for JavaScript developers. All built-in classes are available in both JavaScript (in HTML content) and ActionScript (in SWF content).

Note: ActionScript code (in a SWF file) can access JavaScript code and the HTML DOM in an HTMLControl object contained in the SWF. (This is only possible in SWF-based applications that contain HTMLControl object.) For details, see Adding HTML content to SWF-based applications.

Initializing your application

You can initialize the HTML and JavaScript components of your application in the same way you would in a browser environment. Apollo loads the HTML page identified in the rootContent element of the application descriptor file. Script elements in the page are executed and events dispatched in the usual order.

Making an XMLHttpRequest

Apollo uses the XMLHttpRequest object for asynchronous data requests. The object works in Apollo in the same way that it works in a typical web browser. The following example illustrates a simple XMLHttpRequest: 

xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", "app-resource:/localfile.data",true);
xmlhttp.onreadystatechange=function() {
    if (xmlhttp.readyState==4) {
        //do something with data...
    }
}
xmlhttp.send(null)

Creating a new window

To create a new HTML window use the standard JavaScript Window.open() method. A window with system chrome will be created to display the content at the specified URL.

JavaScript example: 

  newWindow = window.open("InvokeEvent.html", "logWindow", "height=600,width=400,top=10,left=10");

Note: the window created does not automatically have the Apollo window.runtime property exposed. To create this property in the new window, create a new runtime property on the window object and assign it the value of the opening window's runtime property: 

  window.runtime = window.opener.runtime;

In this Alpha release of Apollo, full control of windows created through the JavaScript window.open() method is not supported. For example, you cannot set the display state of an HTML window. Only methods supported by client-side JavaScript can be used.

If full control of the window is required, you can use the Apollo NativeWindow API to create a non-JavaScript window. Adding HTML content to this type of window is more complicated, however. You must first add an HTMLControl object to the window display list and then load the HTML content into the HTMLControl. (See Loading HTML content for an example.)

NativeWindows versus HTML windows

Windows created through JavaScript, and this includes the window automatically created for your application on start-up if the rootContent is an HTML file, follow the document object model for displaying and manipulating window content. NativeWindows, on the other hand, use the Flash display list model. For information on Flash display list programming, see the ActionScript Language Reference and the Flex Developer’s Guide.

HTML-based application have full access to the NativeWindow API for creating new ActionScript windows, but when doing so, must use the Flash display list techniques to draw into the window. Likewise, SWF-based applications can create JavaScript windows (through JavaScript in an HTMLControl, but must load HTML data or write elements to the document object to put content into such windows.


Back to: Apollo Documentation home page

collected by Jimbob 2007.05