Application Structure

Every HP webOS application should follow a conventional directory structure. The Command Line Tools include palm-generate, which creates a new application project and this complete structure automatically with as little as an application name as an argument:

palm-generate MyApp

The MyApp/views directory and everything within it is required along with valid appinfo.json and sources.json files at the root level of the app directory. The rest of the structure and naming is recommended but not required.

MyApp
  -> app
  -> assistants
  -> first-assistant.js
  -> second-assistant.js
  -> ...
  -> models
  -> views
  -> first
  -> first-scene.html
  -> second
  -> second-scene.html
  -> ...
  -> appinfo.json
  -> icon.png
  -> images
  -> image1.png
  -> image2.jpg
  -> index.html
  -> sources.json
  -> stylesheets
  -> css1.css
  -> ...

The sections that follow explain each of the directories, as well as the individual files appinfo.json, sources.json, icon.png, and index.html.

App Folder

An application's logic and presentation files reside in the MyApp folder, which provides a directory structure based on the model-view-controller (MVC) pattern. You can choose any name for your application, but MyApp should correspond to the value of the id property in appinfo.json.

Assistants

Assistants are application-specific JavaScript functions that leverage the framework's controllers to customize the application's behavior. There are several kinds of assistants, the most common of which are scene assistants which implement a particular view of the application. For example, in the Contacts application there is a scene that handles the details of an individual contact. The scene not only displays that contact's information, but also provides the ability to interact with the various fields that present that information. The Contacts application uses a scene assistant to handle the logic of that interactivity. See Introduction to HP webOS Applications for more information on assistants and controllers.

Models

Applications that include data models would locate them in the models directory. The number and types of files is entirely application dependent and it isn't unusual for an application to have nothing in this directory or for the directory to be missing.

Views

HTML files describe the application's layout and display elements, and all the files are located in the views directory of your application. A scene assistant has one main HTML view file, which provides the static structure and content of its presentation page. It can also include HTML template view files that may be used to display dynamic data, such as JavaScript object properties from a scene assistant. These files are fragments of the UI that are combined together by the framework to produce the final presentation.

Each scene has a specific view directory that uses the scene's name, and a single HTML file within it for the scene's view file. For example, the first scene has a view directory of first within which is the view file, named first-scene.html. If there are any templates used in the first scene, then they would also likely be in the first directory.

Images

An application's images are located in the images folder. When referring to images from inside an assistant, use the following to specify the path: images/. When referring to images from a CSS file, use the following to specify the path: url(../images/). The images folder may also contain sub-directories.

Stylesheets

An application's cascading style sheets (CSS) are placed in the stylesheets directory. In general, a web application designer typically uses HTML to structure the layout of a page and CSS to style the presentation. The same principle applies to webOS applications, and CSS files work in the conventional way.

Make sure to load any CSS files in your index.html file as follows:

<link href="/stylesheets/<stylesheet-name>" media="screen" rel="stylesheet" type="text/css" />

appinfo.json

The appinfo.json file provides configuration information to the framework to load the application and run it. The Application Manager is responsible for putting the application in the Launcher.

Here's an example of an appinfo.json file:

{
  "title": "MyApp",
  "type": "web",
  "main": "index.html",
  "id": "com.mydomain.app.myapp",
  "version": "1.0",
  "vendor": "mydomain"
}

There's a lot more on appinfo.json in appinfo.json, which covers each of the properties and their possible values in detail.

sources.json

For info about creating and formatting sources.json, see sources.json.

icon.png

This file is the icon to be used for your application. Application icons should be 1 in. square, 64 x 64 pixels, encoded as a PNG with 24 bit/pixel RGB and 8 bits alpha. The icon's image should be about 56 x 56 pixels within the PNG bounds. Designers, or those interested in icon design guidelines, should refer to the User Interface Guidelines.

index.html

Following web standards, index.html is the first page that the framework loads for an application unless changed with an assignment in appinfo.json. All your code belongs in your assistants, and your HTML belongs in your view files, so there is very little to go into index.html, but you do need to load the Mojo framework here and any application-specific CSS.

You should always specify the latest version of the framework that you know is compatible with your application. HP will include old versions of the framework in webOS releases so you don't need to worry about your application breaking when HP updates the framework. For example, your application's index.html will look something like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>My App</title>
<script src="/usr/palm/frameworks/mojo/mojo.js" x-mojo-version="1"
  type="text/javascript"></script>
<link href="/stylesheets/MyApp.css" media="screen" rel="stylesheet"
  type="text/css" />
</head>
<body>
 .
 .
</body>
</html>

This code loads the framework version indicated by the x-mojo-version property. You do need to specify your application stylesheets explicitly.

The framework includes the Prototype library and the standard webOS style sheet automatically within the main application window, but not within child windows. There is more discussion of that in Advanced Topics.