Apollo file structures
Back to: Apollo Documentation home page
Aside from all the files and other assets that make up your Apollo applications, the following two files are required for Apollo applications:
- AIR files — An AIR file is used to package an Apollo application, and it serves as the installer file.
- application.xml — An XML file, included in each Apollo application (embedded in the AIR file), serves as a manifest, defining various properties of the application.
When using Flex Builder and the Apollo Extensions, the application.xml file is automatically generated for you when you create a new Apollo project. If you're developing Apollo applications using the Flex and Apollo SDKs, you need to create this file manually. Additionally, when using the Apollo Extensions for Flex Builder, you export your application as an AIR file and it is generated for you. When developing with the Flex and Apollo SDKs, you use the ADT command-line tool to generate the AIR file.
This section describes the formats of these files.
| Contents |
|---|
|
The AIR file format
An AIR file is a ZIP-based application distribution format used to transfer and install Apollo applications. An AIR file contains all of the files necessary for Apollo to install and run the application. When Apollo is installed, it automatically registers for the .air extension, and users can simply double-click an AIR file to initiate application installs.
Typically, an AIR file contains the following:
- application.xml — The application descriptor file (required). See The application descriptor file schema.
- The main application file — This is a SWF file or an HTML file (required).
- The application icons — One or more PNG, GIF, or JPEG graphics.
- Any additional assets (such as SWF, JavaScript, HTML, image, or data files) that are used by the application at run time.
The application.xml file goes into a special metadata directory within the AIR package. Other assets, including the main application file and icons, can be placed in sub-directories within the AIR file. The directory structure will be maintained when the application is installed.
Use the ADT application to create an AIR file. For details, see Packaging an Apollo application.
The application descriptor file schema
The application descriptor file, application.xml, contains the properties of the entire application, such as its name, the version, copyright, and so on. Any file name can be used for the application descriptor file. Flex Builder will automatically create a descriptor file when you create a new project. When you package the application, either with Flex Builder or ADT, the application descriptor file is renamed to application.xml and placed within a special directory inside the package.
Here's the content of an example application descriptor file:
<?xml version="1.0" encoding="utf-8" ?>
<application appId="com.adobe.apollo.examples.HelloWorld" version="1.0"
xmlns="http://ns.adobe.com/apollo/application/1.0.M3">
<properties>
<name>Apollo Hello World</name>
<description>
This is the Hello World sample file from the Apollo documentation.
</description>
<publisher>Apollo Examples</publisher>
<copyright>Copyright © 2006, ApolloCorps, LLC.</copyright>
</properties>
<rootContent
systemChrome="none" transparent="true">
ApolloHelloWorld-debug.swf
</rootContent>
<icon>
<image16x16>smallIcon.png</image16x16>
<image32x32>mediumIcon.jpg</image32x32>
<image48x48>bigIcon.gif</image48x48>
<image128x128>biggestIcon.png</image128x128>
</icon>
</application>
Attributes of the root application element
At its root, the sample application.xml file contains an application property:
<application appId="com.adobe.apollo.HelloWorld" version="1.0"
xmlns="http://ns.adobe.com/apollo/application/1.0.M3">
The application identifier (appID) attribute
The application identifier is a unique identifier for the application. It is represented in the application.xml file as the appID attribute of the root application element:
appId="com.adobe.apollo.SampleApp"
The string portion is restricted to the following characters:
- 0–9
- a–z
- A–Z
- . (dot)
- - (hyphen)
The string portion must contain between 17 and 255 characters (inclusive).
The string portion is typically structured using a dot-separated hierarchy, in alignment with a reversed DNS domain address, a Java package or class name, or an OS X Universal Type Identifier. For example:
com.adobe.apollo.HelloWorld
The DNS-like form is not enforced, and Apollo does not create any association between the name and actual DNS domains.
The version attribute
This is used to specify the version information for the application (not for the Apollo run time). The version string is an application-defined designator of the standard form: "MajorVersion.MinorVersion", where MajorVersion and MinorVersion are numbers. Additional point designators are allowed after the minor version, and may include letters. Examples: "1.0", ".4", "0.5", "4.9", "1.3.4a"
version="1.0"
The Apollo XML namespace
Be sure to declare the Apollo namespace as the default XML namespace:
xmlns="http://ns.adobe.com/apollo/application/1.0.M3"
Note: The namespace will change with each release of Apollo.
The application name, publisher, description, and copyright properties
The properties element contains information that defines the basic properties of the file:
<properties>
<name>ApolloTunes</name>
<publisher>Adobe Systems Inc.</publisher>
<description>An Apollo-based MP3 player</description>
<copyright>Copyright © 2006 ApolloWorks, Inc.</copyright>
</properties>
The name property defines the name of the application. In Windows, this is displayed in the application's title bar and in the Windows Start menu. On Mac OS, it is displayed in the menu bar when the application is running.
The description will be displayed in the Apollo application installer.
The copyright notice will be displayed in the Apollo application installer.
The publisher information will be displayed in the Apollo application installer. In Windows, this name is used to identify a section of the Start menu that contains the application, and it also identifies the subdirectory of the "Program Files" directory in the user directory in which applications are installed by default. On Mac OS, the publisher value is not used in the installation path.
Defining the rootContent element
The application.xml file also indicates the rootContent file. This is the file that is first loaded by the application. This may be either a SWF file or an HTML file.
The value specified for the rootContent property is a URL that is relative to the root of the application.xml file. For example, in the following rootContent property, the ApolloTunes.swf file (in the same directory as the application.xml file) is defined as the root file for the application:
<rootContent
systemChrome="none"
transparent="true"
visible="true"
height="400"
width="600">
ApolloTunes.swf
</rootContent>
The systemChrome attribute
There are two possible values for this attribute:
- standard — System chrome is displayed, and the application has no transparency.
- none — No System chrome is displayed.
The transparent attribute
Set this to "true", if you want the application window to support alpha blending. This property cannot be changed after the window has been created. A window with transparency may draw more slowly and require more memory than a window without it.
For the Apollo Alpha release, setting transparent="true" has no effect if systemChrome="standard". In addition, transparency is not supported for HTML-based applications.
The visible attribute
Set this to "false" if you initially want to have the main window be hidden. The default value is "true".
You may want to have the main window hidden initially, and then set its position and size in ActionScript. You can then display the window by setting the stage.window.visible property (for the main window) to true. For details, see Working with windows.
For the Apollo Alpha release, there is no way to change the visible property of a window in an HTML-based application. Accordingly, HTML-based applications should not set this property to false in most circumstances.
The height and width attributes
The height and width attribute set the height and width of the main window of the application. If you do not set these attributes, the window size is determined by the settings in the root SWF file or, in the case of HTML, by the operating system. If you set the visible attribute to "false" you can add ActionScript code to adjust the width and height property of the window (before setting its visible property to true).
The icon property
The icon property specifies one or more icon files to be used for the application. Including an icon is optional. If you do not specify an icon property, the operating system will display a default icon.
The path specified is relative to the application root directory. For the Apollo Alpha release, PNG, GIF, and JPEG formats are supported. If you do not specify an icon, the default Apollo icon is used. To avoid scaling, you can specify all of the following icon sizes:
<icon>
<image16x16>smallIcon.png</image16x16>
<image32x32>mediumIcon.jpg</image32x32>
<image48x48>bigIcon.gif</image48x48>
<image128x128>biggestIcon.png</image128x128>
</icon>If an image is specified, it must be the size specified or application installation will fail. If all sizes are not provided, the closest size will be scaled to fit for a given use of the icon by the operating system.
Back to: Apollo Documentation home page