Palm webOS applications have a standard directory structure with naming conventions and some required files. To help you get started quickly, the SDK includes palm-generate, a command-line tool that takes an application or scene name as arguments and creates the required directories and files. You can run this from the command line (the $ is the command-line prompt and should not be entered as part of the command):

$ palm-generate AppName

The tool creates a functional application within a conventional webOS directory structure. Every webOS application should have a directory structure similar to the following, and some parts of the structure are required:

AppName
   -> app
       -> assistants
           -> first-assistant.js
           -> second-assistant.js
           -> ...
       -> views
           -> first
               -> first-scene.html
           -> second
               -> second-scene.html
           -> ...
   -> appinfo.json
   -> icon.png
   -> images
       -> image_1.png
       -> image_2.jpg
       -> ...
   -> index.html
   -> sources.json
   -> stylesheets
       -> AppName.css
       -> ...

You are free to choose any project directory name, but AppName should correspond to the value of the id property in appinfo.json, discussed later in this section. An application’s logic and presentation files reside in the app directory, which provides a directory structure loosely based on the MVC pattern.

There are scene assistants in the assistants directory of your application. As discussed earlier, a scene is a particular interactive screen in an application. Scene assistants are delegates implemented in your application, and are used by the framework’s controllers to customize an application’s behavior.

All layout files are located in the views directory of your application. A scene assistant has one main HTML view file, which provides the structure and content of its presentation page. It also includes optional HTML template view files that may be used to display dynamic data, such as JavaScript object properties for UI controls. These files are fragments of the UI that are combined together by the framework to produce the final presentation of the scene.

An application’s images are located in the images directory and the CSS files are placed in the stylesheets directory. As with web applications, webOS applications use HTML to structure the layout of a page and CSS to style the presentation. CSS files are used to style your custom HTML, and you can also use CSS to override Mojo’s default styles.

The appinfo.json object gives the system the information it needs to load and launch your application. Within appinfo.json there are both required and optional properties, which are described in Table 2-2.

The palm-generate tool creates an appinfo.json file with a common set of properties set to default values. The most important property is the id, which must be unique for each application; it’s used in service calls to identify the caller and serves as a unique application identifier.

The Application Manager is responsible for putting the application in the Launcher using the icon.png as the icon for your application. Application icons should be 64 × 64 pixels, encoded as a PNG with 24 bit/pixel RGB and 8 bits alpha. The icon’s image should be about 56 × 56 pixels within the PNG bounds.

Following web standards, index.html is the first page loaded when a webOS application is launched. There are no restrictions on what you put into the index.html, but you do need to load the Mojo framework here. Include the following in the header section:

<script src="/usr/palm/frameworks/mojo/mojo.js"
    type="text/javascript" x-mojo-version="1"></script>

This code loads the framework indicated by the x-mojo-version attribute; in this case version 1. You should always specify the latest version of the framework that you know is compatible with your application. If needed, Palm will include old versions of the framework in webOS releases, so you don’t need to worry about your application breaking when Palm updates the framework.

You can load your JavaScript using the sources tag in index.html, but this will load all the JavaScript at application launch. To improve launch performance, it is recommended that you use sources.json to provide lazy loading of the JavaScript. The palm-generate tool will create a template, and you can add the application specific files as they are created.

The generated file includes only your stage assistant, but a typical sources.json includes some scene assistants and perhaps an app assistant:

[
  {
    "source": "app/assistants/app-assistant.js"
  },
  {
    "source": "app/assistants/stage-assistant.js"
  },
  {
    "source": "app/assistants/first-assistant.js",
    "scenes": "first"
  },
  {
    "source": "app/models/data.js",
    "scenes": ["first", "second"]
  },
  {
    "source": "app/assistants/second-assistant.js",
    "scenes": "second"
  }
]

The app-assistant file path comes first, followed by the stage-assistant and the scenes file paths after that. The scene file paths can be in any order, but must include both the source and scenes properties. Note the example where both the first and second scenes with a dependency on the same file. HTML files are not included.

Applications can add other directories to the structure above. For example, you might put common JavaScript libraries under a javascripts or library directory, or put test libraries under tests. The required elements are:

The rest of the structure and naming is recommended but not required.

Most web applications can simply be loaded into a browser to run and debug them, and webOS apps can also be tested and debugged that way. However, you’ll run into difficulty if your application is using Mojo widgets or webOS services. And it’s difficult to fully test your application without seeing it working within the webOS System UI and other applications.

For this reason, you’ll want to use the webOS Emulator with integrated JavaScript debugger and DOM inspector. Unlike the other development tools, the emulator is a full native application on every platform and will be found in the Applications directory on MacOS X and Linux or in the Programs directory on Windows XP/Vista. First, you can launch the emulator directly; it will bring up a window that looks like a Palm Prē. Or, you can use command-line tools; use palm-package to package your application and use palm-install to run it on the emulator.

You’ll also use the debugger for testing your applications after connecting any Palm webOS device to your system using a USB cable. From the command line you can run palm-package and palm-install to run your application on the device as well.