Homebrew webOS Documentation

Where to go when the docs don't help, or if you're just plain curious about what is brewing in Mojo.

To Pre or Not to Pre

Last time we hacked up one of the built-in Palm webOS applications. Nothing very serious mind you, we simply changed the title of the Calculator application and ran it in the emulator to demonstrate our skills. That was simple and fun, so perhaps now you are intrigued by the webOS and might like to write your own application but perhaps wondering if:

  • A) you should bother?
  • B) just where to start?

Let’s address the first question: should you bother writing an application for Pre? Well, iPhone and BlackBerry are the market-share kings with Android poised for a strong Q3 as new devices are on the near horizon, so where is the opportunity with Pre? Does it have a chance? Well, the Palm Pre is a new device with a very small but growing market-share, and Palm has just introduced their second device, the Pixi. It is a “cute” device — it looks like a cross between the Pre, a BlackBerry and a Palm Centro on slim-fast. It is supposed to be aimed at a younger crowd that is interested in text messaging. Probably a smart move as texting (and other less edifying uses of phone-cameras…) is a dominant mobile application, and certainly so in the younger market demographic segments. Palm has released this device in time to be on the early side of holiday shopping — yes, the holiday season is just around the corner! The Palm webOS App Store is sparsely populated, but I think it is actually a good thing because an app doesn’t get lost there like in other app stores. If you have a good application idea, you’ve got a great chance for it to be seen by Palm Pre owners perusing the App Catalog. Big fish in a small(er) pond and all that. So, if you’re with me and interested in writing an app for webOS, welcome to the club!

Now, to the second question, where to start? You will want to start by registering as a developer at http://developer.palm.com. Download and install the latest SDK including Sun’s Virtual Box, Eclipse and all the trimmings you can read about on Palm’s site. Then you’ll peruse the online docs and getting started guides. You might try building the HelloWorld application or cruising through the sample code shipped with the SDK. All good things to do. But then comes the wall. You know there is something more that you want to know about the OS but the docs just don’t go broadly enough and they certainly don’t go deep enough. Not yet anyway. In time they will no doubt flesh out and become more valuable to developers, but for now we’ve got to come up with something else because we don’t know what we don’t know. Welcome to the bleeding edge.

webOS Documentation

Our version of the webOS docs are actually the Mojo framework’s source files. After writing my first few applications I found myself wondering just what was in the Mojo framework. I grew tired of trying to cross-reference the online documentation so I went in search of the framework files themselves. Recall that webOS applications are written in JavaScript, HTML and CSS — all of which is written as plain text and is human readable. We are ignoring the fact that some folks munge their JavaScript libraries such that they are not readable — luckily for us, the Mojo framework files are easily found and read.

We are going to work with the Emulator found in the Palm SDK. Before we proceed, make sure you’ve got the Palm SDK installed and you are able to run the Emulator. For our purposes here you will not need Eclipse but it is a good idea to get Eclipse and the webOS plug-in for Eclipse installed and operational. We’ll be using it in future articles. Here is a shot of the emultor running on my development laptop:

emulator.png

With the emulator running, we need to connect with an ssh client. Linux and MacOSX clients have a built-in ssh client. For Windows users, run the program named putty.exe which is found in the /bin sub-directory of the Palm SDK folder. On my machine it is found in c:\program files\palm\sdk\bin. Connect to at port 5522. Sign in as user root and just hit enter when prompted for a password:

login as: root
root@localhost's password:
root@qemux86:/var/home/root#

The Mojo framework is installed in /usr/palm/frameworks/mojo/submissions/<build number>. On my emulator I’ve got a directory named 191.14 which contains the Mojo source files.

root@qemux86:/usr/palm/frameworks/mojo/submissions/191.14# ls -l
drwxr-xr-x    2 root     root         2048 Jul  7 16:20 formats
-rw-r--r--    1 root     root           30 Jul  7 16:14 framework_config.json
drwxr-xr-x    4 root     root        12288 Jul  7 16:20 images
drwxr-xr-x    2 root     root         3072 Jul  7 16:20 javascripts
-rw-r--r--    1 root     root         6388 Jul  7 16:14 mojo.js
drwxr-xr-x   24 root     root         1024 Jul  7 16:20 resources
drwxr-xr-x    2 root     root         1024 Jul  7 16:20 stylesheets
drwxr-xr-x   29 root     root         1024 Jul  7 16:20 templates
root@qemux86:/usr/palm/frameworks/mojo/submissions/191.14#

If you are comfortable cruising around the Linux file system and using the vi editor, you’re all set and can take take it from here. Start cruising around these subdirectories — you’ll probably spend most of your time in the javascripts directory. You will also want to sue grep to help you find something you’re interested in. For example, I was looking to find out how to put my application’s version number into an About dialog. The version number is set in the appinfo.json file. When I couldn’t find an answer in the documentation, I came to my home-brew docs here.

root@qemux86:/usr/palm/frameworks/mojo/submissions/191.14/javascripts# grep appinfo *
framework.js:   var loadedInfo = Mojo.loadJSONFile(Mojo.appPath + "appinfo.json");
root@qemux86:/usr/palm/frameworks/mojo/submissions/191.14/javascripts#

Cool, we’ve found a js file which knows something about the appinfo.json file — the file is named framework.js. And here’s something new — there is a property of the “Mojo” class named appPath. I bet that is the full name to the application’s directory. We can find out by adding this line to one of our application’s source files:

Mojo.Log.info("Mojo.appPath is [" +  Mojo.appPath + "]");

Continuing to sift through this file I found what I needed: Mojo.appInfo.version.

Yeah, but I don’t do vi and grep!

OK, so you’re not looking to live in the ssh emulator world? No problem, let’s bring those files back to the desktop of choice and we can look at them in notepad, print them out, try to load them into Safari/webkit or whatever other fun thing we might like to do. Before we get too excited with what we’ll do with the files on the desktop we’ve got to get them there to begin with. There may be other ways of accomplishing this task, but I’ll show you what I came up with. The first thing we want to do is zip up the files. We’re going to need to do this in few steps.

  1. Navigate to /usr/palm/frameworks/mojo/submissions
    cd /usr/palm/frameworks/mojo/submissions
    
  2. Create a tar file:
    root@qemux86:/usr/palm/frameworks/mojo/submissions# tar -cf webos.tar *
    root@qemux86:/usr/palm/frameworks/mojo/submissions# ls -l
    drwxr-xr-x    8 root     root         1024 Jul  7 16:20 191.14
    -rw-r--r--    1 root     root      4188160 Sep 13 20:32 webos.tar
    root@qemux86:/usr/palm/frameworks/mojo/submissions#
    
  3. Then compress the tar file
    root@qemux86:/usr/palm/frameworks/mojo/submissions# gzip webos.tar
    root@qemux86:/usr/palm/frameworks/mojo/submissions# ls -l
    drwxr-xr-x    8 root     root         1024 Jul  7 16:20 191.14
    -rw-r--r--    1 root     root      1431258 Sep 13 20:32 webos.tar.gz
    root@qemux86:/usr/palm/frameworks/mojo/submissions#
    

Now that we have our files compressed and ready for travel, we need to get the archive file to our desktop machine. Perhaps there is an ftp client lurking somewhere on the emulator. I didn’t find it, so we’re going to use the Secure Copy program, scp. This basically uses a protocol similar to SSH to copy a file securely. Here is the syntax I used to push the file to a Mac on my network:

root@qemux86:/# cd /usr/palm/frameworks/mojo/submissions/
root@qemux86:/usr/palm/frameworks/mojo/submissions# ls
191.14        webos.tar.gz
root@qemux86:/usr/palm/frameworks/mojo/submissions# scp webos.tar.gz fableson@hostname:/Users/fableson/webos.tar.gz
WARNING: Ignoring unknown argument '-x'
WARNING: Ignoring unknown argument '-oForwardAgent no'
WARNING: Ignoring unknown argument '-oPermitLocalCommand no'
WARNING: Ignoring unknown argument '-oClearAllForwardings yes'
Password:
webos.tar.gz                                  100% 1398KB   1.4MB/s   00:01
root@qemux86:/usr/palm/frameworks/mojo/submissions#

You should be able to exercise this on any machine which has a secure shell server. Use your own credentials of course. If I knew more about scp I would share it with you — the short version is it works so give it a try. From here you can unzip the webos.tar.gz file with WinZip or with gunzip.

root@qemux86:/usr/palm/frameworks/mojo/submissions# gunzip webos.tar.gz
root@qemux86:/usr/palm/frameworks/mojo/submissions# ls -l
drwxr-xr-x    8 root     root         1024 Jul  7 16:20 191.14
-rw-r--r--    1 root     root      4188160 Sep 13 20:40 webos.tar
root@qemux86:/usr/palm/frameworks/mojo/submissions#

To extract the tar file, use tar -xf webos.tar. Be careful to not do this on your emulator — you don’t want to mess with your installation! WinZip on WinRAR will magically take care of all of this for you on Windows. From here you can run whatever kind of “Find in Files” search you might like.

Log Files

I have found it helpful to poke around the files and then test something out by just printing it to the log with a call to Mojo.Log.info(). Of course, we now need to know where that shows up, so let’s take a quick look at how you see the log on webOS.

There are (at least) three ways to see logging statements made from our application.

  1. From your ssh session, tail the file /var/log/messages. This will show messages from your applicaiton along with many other messages that may be confusing if you’re trying to pick up only your application.
    tail -f /var/log/messages
    
  2. From your ssh session, type log . This will “tail” the log and filter to only show you messages relevant for your application.
    log com.mycompanyname.myapplicationname
    
  3. Set up our application for Debugging and run the Palm Inspector found in the SDK. Be sure to check the box “Inspectable” in the Run Configuration as seen below:

    debugconfig.png

Until a new version of webOS documentation becomes available, enjoy your home-brew documentation. Be sure to keep your “documentation” up to date as you update the SDK. Happy Hacking — and see you at the App Store!

Fatal error: Call to undefined function aa_author_bios() in /opt/apache/dms/b2b/linux-mag.com/site/www/htdocs/wp-content/themes/linuxmag/single.php on line 62