User Name
Password

Not a member?
Register
Forgot your password?
Recover
Forgot your username?
Remind






Hello, World!

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

Before you start working on your first Palm webOS application, install the Palm® Mojo™ SDK. Familiarize yourself with the emulator, and ensure you know how to start applications. This tutorial helps you build a simple webOS application and verify that your development tools are working correctly.

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. To create the directory structure by using Eclipse with the Palm plug-in, select File > New > Project (wizard), expand Palm webOS, and then select Mojo Application. Name the project HelloWorld. Otherwise, use these instructions and palm-generate at the command prompt to set up the application directory structure.

Set up the application directory structure

  1. Open a Command Prompt window, and make a workspace directory (for example, app_dir) for developing applications.
  2. 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:

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:

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 > External Tools > Run As > Palm Application. Eclipse automatically packages, installs, and launches the application. Otherwise, run the application at the command prompt by using the palm tools included with the SDK.

This section includes the following procedures:

Notes:

Package and install the application on the emulator

  1. Start the emulator.
  2. Open a Command Prompt window, and then navigate to the workspace directory.
  3. Use the palm-package command as follows to package the directory containing the application:
    palm-package HelloWorld
  4. 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

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

Close the application at the command prompt

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

Delete the application from the emulator

  1. Start the emulator.
  2. Open a Command Prompt window, and then navigate to the workspace directory.
  3. 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.

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 creates the view and the assistant for the first scene. It also adds a few lines to sources.json to correlate the assistants and scenes. Take a look at the following files:

Create and edit the first scene

  1. Open a Command Prompt window, and then navigate to the workspace directory.
  2. 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. The file name is auto-generated to start with a lowercase letter.
  3. 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:

Push the application scene

  1. Open stage-assistant.js.
  2. 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

  1. Open first-assistant.js.
  2. 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:

Bind and register the handler

  1. Open first-assistant.js.
  2. 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