Tutorials webOS Hello World

This guide assumes you have a rooted Pre, with SFTP access. If you don't, please follow the other guides on this wiki first. This guide also assumes that you have at least a basic knowledge of HTML, CSS, and maybe a little JavaScript.

Note: All of this information was acquired via referencing the applications on the Pre, dissecting the Mojo sources available on the Pre, and possibly other publicly available information. The author of this guide has no access to, or knowledge of Palm's unreleased SDK, aside from what has been made publicly available so far.

I'll start by walking you through building your first “Hello, world!” application for webOS from scratch, without copying an existing application and modifying it. Then we'll slowly get into the cooler, meatier parts of Mojo, so that you can actually start bringing your ideas to life. This guide will also cover how to “install” your newly created webOS application(s) on your rooted Pre.

Building your first webOS application:
First off, a webOS application requires only three files to become functional:


 * appinfo.json – This is file contains a simple JSON object, describing basic meta information about your application, such as the name, version, vendor, etc...
 * index.html – This file is really the first file that is run when your application is launched. It doesn't have to be called “index.html” since you specify the name for this file in your appinfo.json file. However, I think index.html fits well, and it seems to be what most (if not, all) of the existing webOS applications are using.
 * icon.png – This is the icon that will be displayed in the launcher for your application. Like index.html, the filename doesn't have to be “icon.png”, since the filename for the launcher icon is specified in your appinfo.json file.

That's it! Only three files to create a basic webOS/Mojo application... In fact, it would probably work without the launcher icon, but let's be honest... who wants an application without an icon? In a typical application (especially if you follow the Mojo framework's MVC structure) you'll have many more files and directories than this, but for simplicity's sake, we'll start with the basics.

Anyway, now let's get started building our first webOS application.

First, create a new, blank directory for your application. Note: Create this directory on your computer. We'll cover how to install your application on your Pre later.

Now for the first, and arguably the most important part of your webOS application: the appinfo.json file.

Here's the contents of a typical appinfo.json file:

{	"title": "Hello, world!", "version": "0.0.1", "type": "web", "main": "index.html", "id": "org.webosinternals.evanpro.app.helloworld", "icon": "icon.png", "vendor": "Evan Coury", "vendorurl": "http://www.evan.pro/", "visible": true, "removable": true }

If you're not familiar with JSON, I urge you to [*http://en.wikipedia.org/wiki/JSON read up on it]. JSON has many other valuable uses in building web applications. The appinfo.json file is really just a self-explanatory key-value pair file, defining some simple information about your application. Here are some details on each value:

TODO: Finish specifying which values in the appinfo.json are required and which are optional. Also mention what the default values for optional ones are. Additionally, add any new values as they're discovered.

In the empty directory you made, create a new file called appinfo.json... In it, paste my sample from above. Feel free to change the title, version, id, vendor, and vendorurl to whatever you want. (Remember what I said about the characters in the application ID, though.)

Next, either go find or make an application icon. 64 x 64 seems to be a good size for launcher icons, O'Reilly's book states that the icon's image should be about 56 x 56 pixels within the 64 x 64 png bounds. PNG's with alpha transparency obviously will look the best. Note: if your icon is smaller than 64 x 64, I believe the launcher will stretch it to 64 x 64, causing it to look fuzzy or pixelated.

If you're too lazy to find or make an icon, I've made a little hello world icon that you may use:



Now that we have an appinfo.json and an awesome icon, we can move onto the fun part: index.html. If you're familiar with the basics of the web (HTML / CSS / JavaScript), then this will be very simple....

We'll start with the basics... Create an index.html in the directory you created, alongside your appinfo.json and icon.png, and paste the following code into it:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

 Hello, world title!   #content { text-align: center; }		#app-footer { margin-top: 25px; font-size: 80%; text-align: center; }

My First webOS App! I'm an awesome button! Hello, world!  &copy; 2009 Evan Coury

You'll notice that webOS lets you use the exact same HTML / CSS as you would if you were simply developing for a browser.

The only real distinguishing factor of this application is here:



This line tells webOS to load all of the components of the Mojo framework, including pre-built CSS classes for UI elements, and the valuable Mojo JavaScript functions, which are what will allow us to access and interact with all of the fun stuff like GPS, messaging, alerts, vibration, etc, etc.

Really, if you're just doing some HTML / CSS stuff, and don't wish to use Palm's pre-built UI styles, then you really don't even need to include Mojo... but then what's the point?

In the example, I use a couple of the pre-built CSS UI styles from Mojo. Firstly, the header...

My First webOS App!

I don't have a list of all of the palm-* CSS classes, but they're very easy to find by referencing the existing applications.

The second Mojo style I used was the button:

I'm an awesome button!

Other than that, everything else is just normal HTML and CSS, exactly how you would use it on the web. One thing to note is how I referenced the application icon from within the application using a simple tag.

Some Protips:


 * Any files you place in your application's directory are available to you to use from within your application. This includes images, CSS, JavaScript files, etc.
 * You do not have to have your CSS styles in-line like the example. For example, you could create a “css” subdirectory to hold all of your CSS files. Then you can use  in the just like normal.
 * Theoretically, the files you include (images, JavaScript, CSS) do not have to be relative paths to files in your application's directory. You can also reference remote files using absolute paths... However, be sure to note that if you reference remote files like this, your application may take longer to load, as the files need to be downloaded over EV-DO or WiFi. Also, if the Pre is unable to get a network connection, there would obviously be problems with this. I'm simply noting that it is possible, and that it does work. However, including remote JavaScript can be extremely helpful with rapid development (TODO: Add example for remote JS development).
 * You may include and use jQuery (and other JS libraries, I'm sure), but make sure to include it before Mojo, and use jQuery.noConflict; since Mojo uses Prototype (TODO: Add jQuery example).

Installing your first webOS application:
Now that the application has been written, you need to install it on the Pre. Fortunately, installation is quite simple: * Reboot the Pre ( ##FF5500|Orange## + Sym + R ). * Stop/restart LunaSysMgr. * As root, from a shell, execute //initctl stop LunaSysMgr// to stop and //initctl start LunaSysMgr// to restart. * run the following command to refresh the Launcher Cache: luna-send -n 1 palm://com.palm.applicationManager/rescan {}
 * 1) Rename the source directory to match the "id" tag defined in the //appinfo.json// file.
 * 2) Copy the source directory (not just the files) to ///usr/palm/applications// on the Pre so that the full path to your appinfo file looks like this: ///usr/palm/applications/YOURAPPID/appinfo.json//
 * 3) Restart the GUI using either of the following methods:

A couple of scripts to make development easier
I use two scripts. Say I am creating the "something" app. I'd want to use something like com.foobar.app.something. When I want to move the app over to my Pre, I run the following script from the directory above com.foobar.app.something by typing "moveapp.sh something". Here is the moveapp.sh script

APP=com.foobar.app.$1
 * 1) !/bin/sh
 * 2) moveapp.sh

TIMESTAMP="`date '+%Y%m%d-%H%M'`" echo archive $APP to "$APP"_$TIMESTAMP.tgz

echo tar zcvf "$APP"_$TIMESTAMP.tgz $APP tar zcvf "$APP"_$TIMESTAMP.tgz $APP

echo scp -P 222 "$APP"_$TIMESTAMP.tgz myaccount@192.168.23.151:new.tgz scp -P 222 "$APP"_$TIMESTAMP.tgz myaccount@192.168.23.151:new.tgz

On the pre, I have included adding /media/internal/applicaitons to the application search list in /etc/palm/luna.conf. I use this script on my phone to unzip ~/new.tgz created and copied above, then rescans so you can run the new app:

MYACCOUNT=myaccount echo "go to /media/internal/applications/..." cd /media/internal/applications/ echo "Unpack new code from ~my unpack $MYACCOUNT/new.tgz   tar zxvf ~$MYACCOUNT/new.tgz                                    echo "rescan the the launcher's cache"                          luna-send -n 1 palm://com.palm.applicationManager/rescan {} echo "tail the log file just in case" tall -f /var/log/messages
 * 1) !/bin/sh
 * 2) unpack new app into media internal, reset the command cache, and start watching the log
 * 1) you should sudo this or run as root

To Do List:

 * Tips for speeding up the development process with remote JS files (while we wait for the SDK).
 * Deeper examples into the Mojo MVC structure (controllers, scenes, etc) and using phone-related functions (GPS, messaging, etc).

Development notes:

 * If you want to interact with the local file system (read text files, etc) you will need to use the serviceRequest of com.palm.applicationManager with an "open" method. However, application Manager checks the registration in command.resource.handers.json to see what applicatoins are registered to handle a particular mime type.  So, you will need to add YOUR app to the list for that mime type, or some other app may be passed your file.  :-(  --RickB

Can this open method of the appMgr service execute shell cmds and if so how? Can we get some code samples?

--

Note: Despite the //fake// copyright notice in the sample application, the code in the preceding example(s) is released under the MIT license.