Building Your First App

This brief tutorial takes you through the process of creating your first Palm® webOS™ application. Instead of displaying "Hello, World!" on the screen, this tutorial shows you how to create a simple counter that counts button taps. After completing the tutorial, you should be familiar with stages, scenes, assistants, and a few other important concepts.

Before You Begin

This tutorial helps you build a simple webOS application and verify that your development tools are working correctly.

Before you start working on your first Palm webOS application, install the Palm webOS SDK. Familiarize yourself with the emulator, and ensure you know how to start applications from the emulated device's Launcher. The emulated device works very much like the real Palm device, but your computer's keyboard is used to type, and your mouse is used for gestures. The "back" gesture is emulated using the "Esc" key.

You can write a webOS application using only the Palm tools and your favorite text editor or Web development tool. Using Eclipse™ with the Palm plug-in simplifies debugging, packaging, installing, and running webOS applications. For more info, see Eclipse.

The Application Directory

A webOS application directory has a specific structure. These instructions will show you how to use the Palm SDK's command line tools to set up the application directory structure and create an initial set of files required for the application.

(If you are using Eclipse with the Palm SDK plug-in, select File > New > Mojo Application. Enter "HelloWorld" for the project name and title, and accept the defaults for the other fields. Click "Finish" to create the application framework.)

Set up the application directory structure

Open a Command Prompt window, and make a workspace directory (for example, app_dir) for developing applications.
From the workspace directory, type the following (note the single quotes inside the double-quotes):

palm-generate -p "{title:'Hello World', id:com.mystuff.hello, version:'1.0.0'}" HelloWorld

Take a look at the contents of the new HelloWorld folder:

app folder—Contains the assistants, models, and views that make up the application. Later in the tutorial, you add files to this directory.
images folder—Any other images the application uses.
stylesheets folder—Contains the cascading style sheet file for the application.
appinfo.json—The Application Information file.
icon.png—The image that the application presents in the Launcher on the emulator or device.
index.html—The main stage on which the application's scenes appear.
sources.json—A list of the source files for each scene.

For more info about the application directory structure, see Application Structure.

Application Information

The file appinfo.json provides information that the SDK framework uses to package and run the application. Take a look at the contents of appinfo.json:

{
  "id": "com.mystuff.hello",
  "version": "1.0.0",
  "vendor": "My Company",
  "type": "web",
  "main": "index.html",
  "title": "Hello World",
  "icon": "icon.png"
 }

Notice the id and vendor parameters, which become useful when you build signed applications to run on the device itself.

Setting the Stage

A stage is the platform on which you build the user interface for your application. A stage generally corresponds to a single card, or application window. Most simple applications have a single stage, contained in the file index.html. An application that lets the user perform more than one action concurrently might require more than one stage. For example, an email application might show the inbox on one stage, but launch a second stage to compose a new email message. Notification and background applications have no stages at all.

Take a look at the contents of index.html:

<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
   <title>Hello There</title>
   <script src="/usr/palm/frameworks/mojo/mojo.js" type="text/javascript" x-mojo-version="1" />
    <!-- application stylesheet should come in after the one loaded by the framework -->
   <link href="/stylesheets/hellothere.css" media="screen" rel="stylesheet" type="text/css" />
 </head>
 <body>
   <h2>This text verifies your application is running.</h2>
   <p>
   To create a fully functional Palm application create a scene and remove this text from
   index.html. See the documentation on Palm Applications for more information on creating
   applications and scenes.
   </p>
 </body>
 </html>

Notice that index.html is a standard XHTML page, with a <script> tag that brings in the SDK framework required for webOS applications. Although it does not do much yet, it is time to try your application on the emulator.

Starting the Emulator

Follow the instructions for your system:

Linux: At the command prompt, type palm-emulator.
Mac: In the Applications folder, double-click the Palm Emulator icon.
Windows: Select Start > All Programs > Palm > SDK > Palm Emulator.

Running Applications on the Emulator

If you are using Eclipse with the Palm plug-in, you can run an application on the emulator by selecting Run > Run Configurations..., then selecting "Palm Emulator" for the target of your application name. On subsequent activations, select Run > Run As... > Mojo Application. Eclipse automatically packages, installs, and launches the application. With Eclipse, there is no need to uninstall the application before re-running it.

If you are using the command line tools, run the application at the command prompt by using the palm tools included with the SDK.

This section includes the following procedures:

Package and install the application on the emulator
Launch the application at the command prompt
Close the application at the command prompt
Delete the application from the emulator

Notes:

These instructions use the "Hello, World!" example. Remember to make changes as needed for actual applications.
The "workspace directory" contains all of the application directories.
Changes made during development and debugging may not appear unless you first delete the previous version, and then repackage and reinstall the updated application.
Installing a new version of an application does not remove any source files that are not present in the new version. Therefore, during testing, it is useful to delete the old version of an application before installing a new version.

Package and install the application on the emulator

Start the emulator.
Open a Command Prompt window, and then navigate to the workspace directory.
Use the palm-package command as follows to package the directory containing the application:
```
palm-package HelloWorld
```
Use the palm-install command as follows to install the resulting .ipk file on the emulator:
```
palm-install com.mystuff.hello_1.0.0_all.ipk
```

Launch the application at the command prompt

Start the emulator.
Open a Command Prompt window, and then navigate to the workspace directory.
Use the palm-launch command as follows:
```
palm-launch com.mystuff.hello
```

Close the application at the command prompt

Start the emulator.
Open a Command Prompt window, and then navigate to the workspace directory.
Use the palm-launch command as follows:
```
palm-launch -c com.mystuff.hello
```

Delete the application from the emulator

Start the emulator.
Open a Command Prompt window, and then navigate to the workspace directory.
Use the palm-install command as follows:
```
palm-install -r com.mystuff.hello
```

After you package and install the Hello World application on the emulator, launch it at the command prompt or through the emulator by selecting Launcher > Hello World (default icon is a crescent moon). The following screen shot shows the application thus far.

Before moving on, we need to remove the placeholder text from index.html to make room for the new scene. Open index.html and remove all of the text in the body section.

The file should now look like this:

<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
   <title>Hello There</title>
   <script src="/usr/palm/frameworks/mojo/mojo.js" type="text/javascript"
 x-mojo-version="1" />
    <!-- application stylesheet should come in after the one loaded by the
 framework -->
   <link href="/stylesheets/hellothere.css" media="screen" rel="stylesheet"
 type="text/css" />
 </head>
 <body></body>
 </html>

For more info about the emulator, see Emulator.

Creating a Scene

A scene is a formatted screen for presenting information or a task to the user. Each scene has a view and an assistant. The view determines the layout and appearance of the scene. The assistant determines the behavior. Some scenes also have models, which supply data.

The palm-generate command can be used to create scenes and assistants. It also adds a few lines to sources.json to correlate the scenes and assistants. In this next step, we're going to use it to create the scene called "first", which will include the following files:

/app/assistants/first-assistant.js —This is the assistant.
/app/views/first/first-scene.html —This is the view.
sources.json —This file now includes JSON information that binds first-assistant.js to the first scene.

Create and edit the first scene

Open a Command Prompt window, and then navigate to the workspace directory.
Use the palm-generate command as follows:
```
palm-generate -t new_scene -p "name:first" HelloWorld
```
This command creates first-assistant.js and first-scene.html.
Open first-scene.html and replace the content with the following

<div id="main" class="palm-hasheader">
     <div class="palm-header">Header</div>
     <div id="count" class="palm-body-text">0</div>
     <div id="MyButton" name="MyButton1" x-mojo-element="Button"></div>
 </div>

To actually show the scene, you must tell the stage to "push" the scene. In the next section, you add that code to the stage assistant.

Stage Assistant

Like a view, the stage also has an assistant. In this simple application, the stage assistant's only task is to push the scene, making it visible. The stage assistant is a file called stage-assistant.js in the assistants directory, and it contains two functions:

StageAssistant() is the constructor.
setup(), which is called when the stage is launched, pushes the first scene.

Push the application scene

Open stage-assistant.js.
Edit the StageAssistant function to contain the following:

function StageAssistant () {
 }
  StageAssistant.prototype.setup = function() {
     this.controller.pushScene("first");
 }

The application now has a stage and a scene. To make the application functional, you need to write some code in the scene assistant.

Script Writing

At last, it is time to breathe life into the application by adding code to the scene assistant for the first scene. To make the first scene's button functional, the application needs a button handler. This new function updates the text each time the user taps the button.

Add a button handler function

Open first-assistant.js.
Add the following function:

FirstAssistant.prototype.handleButtonPress = function(event){
  // increment the total and update the display
     this.total++;
     this.controller.get("count").update(this.total);
 }

After you register the handler as a listener for Tap events on the button, the framework calls the handler with every button tap. The handler must be bound to the scene assistant, so that when the framework calls the handler it has access to the scene and its DOM. Otherwise, the handler is bound by default to the calling object instead, which is not useful. This example demonstrates two steps:

binding the handler to the scene assistant's scope, using bind(this)
registering the handler as a listener, using Mojo.Event.listen()

Bind and register the handler

Open first-assistant.js.
Edit the setup function to contain the following:

FirstAssistant.prototype.setup = function() {
  // set the initial total and display it
     this.total = 0;
     this.controller.get("count").update(this.total);
  // a local object for button attributes
     this.buttonAttributes = {};
  // a local object for button model
     this.buttonModel = {
     "label" : "TAP HERE",
     "buttonClass" : "",
     "disabled" : false
     };
  // set up the button
     this.controller.setupWidget("MyButton", this.buttonAttributes, this.buttonModel); 
  // bind the button to its handler
     Mojo.Event.listen(this.controller.get("MyButton"), Mojo.Event.tap, 
    this.handleButtonPress.bind(this));
 }

Conclusion

Now that you have changed the source files to create and push the first (and only) scene, you must repackage and reinstall the application to view the completed application.

When you run the application, it shows how many times you have tapped the button. If you do not see the below screen, you need to debug your code. Common errors include spelling and proper capitalization where noted. After debugging, you might have to delete the previous application version and then repackage/reinstall the updated version before it starts properly.

Where to Go from Here

For more info about the structure of a webOS application, see Application Basics.
For more code samples, see Samples.
For info about webOS widgets, see Widgets.

Palm Developer Center