Introduction to webOS SDK Development

This tutorial series will guide you through the process of getting started with webOS app development. In this tutorial, you will learn how to install the webOS development environment and create a simple application. In subsequent parts of this series, we will create a usable application that allows you to browse and display the latest articles on the tuts+ network.

About webOS

Today, web applications are common thanks to advances in modern web browsers. On mobile devices, however, most applications run locally and are built with a compiled programming language such as Objective-C or Java. Because they are built for a specific mobile device, they are very difficult to port to a web site or another mobile platform.

Palm’s operating system for mobile devices (e.g. Palm Pre and Pixi) is appropriately called webOS. One of the distinguishing features of webOS is that it makes all device applications web applications created with HTML, CSS and Javascript by using the Mojo Javascript Framework. Even the native Palm apps on the device are web applications. With the help of HTML5, webOS apps can store data locally, draw 2D graphics, and do CSS transitions/animations. They can also call web services through AJAX to access remote or local data.

The Mojo Javascript Framework loosely follows the Model-View-Controller (MVC) pattern. Views are written in HTML and CSS, while Controllers that control the application logic are written in Javascript. Mojo also includes a set of common UI elements, such as Lists, Buttons, Containers, Dialogs, Indicators, and Pickers. To access lower layers of the operating system, Mojo comes with a set of Javascript APIs to interface with device services (e.g. Alarms, Contacts, Calendars, Photos) or hardware components (e.g. GPS, Display, Camera, Power Supply).

In short, if you know HTML, CSS, and Javascript, you can easily create applications for webOS!

Getting Started

To begin building apps for webOS, you will need to download and install the Palm webOS Software Development Kit. The webOS SDK is available for OS X, Linux, and Windows. You will need to follow the latest instructions from Palm to setup your webOS development environment.

After you have the SDK installed, you can use any text-editor or IDE to create your source code files. There is a webOS development plugin available for Eclipse, but I personally prefer to use ActiveState’s excellent Komodo Edit with a 3rd party plugin for webOS development. In this tutorial, we are going to use the command-line method.

Creating Your First webOS Application

To get started with a hello world app, type the following from your command line / terminal:

palm-generate helloWorld

This command will create a directory named “helloWorld” that will include the necessary directory structure for our app.

Let’s have a look at that structure for a moment:

• app: Contains the assistants and views of your application. More on these later.
• images: Contains images used in your application.
• stylesheets: Contains the css-stylesheet for your application.
• appinfo.json: Contains application information.
• framework_config.json: Contains framework configuration information.
• index.html: Main/start file.
• sources.json: Contains a list of source files for each scene
• icon.png: The icon that represents your application in the launcher and app catalog

Now let’s take a closer look at appinfo.json. Open the file in your favorite text editor:

{
  "id": "com.yourdomain.helloworld",
  "version": "1.0.0",
  "vendor": "My Company",
  "type": "web",
  "main": "index.html",
  "title": "helloWorld",
  "icon": "icon.png"
}

The most important parameters in this file are:

• “id”: This is your application’s id and has to be unique across all available applications. It’s advised to use your own domain name (if you own one).
• “vendor”: Use your company name (if you have one) or your own name.

Next take a look at index.html. It’s a standard HTML file and sets the stage for your application, doing things like loading the mojo framework and the main stylesheet.

<!DOCTYPE html>
<html>
<head>
    <title>Hello World!</title>
    <!-- Initialize the Mojo Framework -->
    <script src="/usr/palm/frameworks/mojo/mojo.js" type="text/javascript" x-mojo-version="1"></script>
    <!-- Apply our main stylesheet -->
    <link href="/stylesheets/helloworld.css" media="screen" rel="stylesheet" type="text/css">
</head>
</html>

To test our application we are going to use the webOS Emulator on an x86 build of webOS running with VirtualBox. Not all hardware features are supported on the emulator. The unavailability of both the device camera and screen multitouch capability are examples of simulator limitations, but special commands can help us overcome these limitations. For example, it is possible to issue a command to simulate an incoming call or text message.

The following operating system commands will start the webOS emulator:

• Linux: Type “palm-emulator” in the command prompt
• Mac OS X: In the Applications folder, double-click the Palm Emulator icon
• Windows: Start > All Programs > Palm > SDK > Palm Emulator

Go ahead and run an instance of the emulator. Play around with the functionality a bit.

In order to package our application so it can be run on webOS, type the following in the command line from the directory that holds the “helloWorld” folder:

palm-package helloWorld

The result is our installable package file: com.yourdomain.helloworld_1.0.0_all.ipk. Note that the filename contains the id and version from the appinfo.json file.

Now, install the application with the following command:

palm-install com.yourdomain.helloworld_1.0.0_all.ipk

Launch the application in the emulator:

Extend the Application

We now have our first application up an runnning, but it’s not very exciting. Let’s add some more content.

To fill our stage with life we go ahead and create the first scene. Scenes are the same as different pages on a website. Scenes can be pushed onto the stage, popped off the stage, or swapped with another scene.

palm-generate -t new_scene -p "name=first" helloWorld

This creates two files: the view in app/views/first/first-scene.html and the assistant for the scene at app/assistants/first-assistant.js.

Open first-scene.html and edit it to contain the following:

<div id="main" class="palm-hasheader">
    <div class="palm-header">First Scene</div>
    <div class="palm-text">Welcome to my World</div>
</div>

Notice the classnames that start with “palm-”; these styles are included in the Mojo Framework, but can be expanded or changed in your own stylesheet.

Now we edit stage-assistant.js to display our new scene when the application starts:

function StageAssistant() {
    /* this is the creator function for your stage assistant object */
}
StageAssistant.prototype.setup = function() {
    /* this function is for setup tasks that have to happen when the stage is first created */
    Mojo.Controller.stageController.pushScene("first");
};

package the application and reinstall it. Here is the result:

Let’s add one more scene and call that when the user presses a button on the first scene:

palm-generate -t new_scene -p "name=second" helloWorld

Now we need to add a button to the first scene. Change first-scene.html to the following:

<div id="main" class="palm-hasheader">
    <div class="palm-header">First Scene</div>
    <div class="palm-text">Welcome to my World</div>
    <div x-mojo-element="Button" id="button1"></div>
</div>

To actually see that button, we need to setup the button widget in the first scene’s assistant setup code. Let’s edit first-assistant.js to do that:

FirstAssistant.prototype.setup = function() {
    /* this function is for setup tasks that have to happen when the scene is first created */
    /* use Mojo.View.render to render view templates and add them to the scene, if needed. */
    /* setup widgets here */
    /* add event handlers to listen to events from widgets */
    this.controller.setupWidget("button1",
        this.attributes = {},
        this.model = {
            label : "OK",
            disabled: false
        }
    );
    this.handleButton1=this.handleButtonPress1.bindAsEventListener(this);
    Mojo.Event.listen(this.controller.get("button1"), Mojo.Event.tap, this.handleButton1);
}

Note that we reference the button through its id: “button1″. We also added functionality to actually do something when we press the button. For that, we first create an event handler, this.handleButton1. We’ll create the necessary function handleButtonPress1 next. The next line, Mojo.Event.listen, sets the button up to listen for taps and call our event handler if a tap is received.

Let’s create our event handler that handles button presses. Our event handler just pushes our second scene to the stage:

FirstAssistant.prototype.handleButtonPress1 = function(event){
    Mojo.Controller.stageController.pushScene("second");
}

At last, we edit second-scene.html to contain something useful:

<div id="main" class="palm-hasheader">
    <div class="palm-header">Second Scene</div>
    <div class="palm-text">This is the second scene</div>
</div>

Ok, now let’s package and reinstall. This should be the final result:

Wrap Up

You’ve just been given a whirlwind tour of developing applications for webOS. In the next part of this series, we are going to build an app to display and read the latest articles from the tuts+ network. Leave comments and feedback below to let us know what you think of this series!