Tutorials webOS Hello World

From WebOS Internals
Jump to navigation Jump to search

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:


Key Values Required Description
title String/Text Y This is the title used in the launcher, and also in the little gray tab thing that's always at the top left... what's that called, again?
version Numbers x.y Y Simply put, this is the current version number of your application. This will obviously be used to manage OTA updates of webOS applications, and such.
type web Y This is the application type... So far, the only value I've seen for this is “web”, even in more complex, plug-in-based applications such as Classic. This of course hints that there could be other options for this in the future, such as “java” or “native”, or who knows what else. This guide is only going to focus on “web”, though.
main index.html Y This is the name of the html file you want to be have run when the user launches the application from the launcher. Typically, this will always be “index.html”, but there's nothing that says it has to be.
id any String Y Now, this is a somewhat important one. This is your “Application ID”. Typically, is what this does, is gives the operating system a programmatic way of identifying your application. This must be completely unique, and it's suggested that you stick with the reverse DNS notation used in the existing applications. (ex. org.webosinternals.evanpro.app.helloworld). As a rule of thumb, I'd suggest keeping it all lowercase, and not using anything besides a through z, 0 through 9, and dashes for your application ID. We own the webosinternals.org domain, so you can use that reversed with your IRC nickname appended if you don't own your own domain that you can use here.
icon file path N This is, of course, the path and file name of the icon you want to appear in the launcher. Simple enough, right?
vendor String N The name of the person / company who made the application.
vendorurl String N The URL of the aforementioned vendor.
visible boolean, default: true N I'm pretty sure this just indicates whether or not to show the application in the launcher. (Credit to PreGame for pointing this one out)
removable boolean, default: true N Tells webOS if this application should removable or not.
miniicon path to icon N Path to file for icon to be used in notification area
category String N Default category for the application
noWindow boolean, default false N Indicates that this is a headless application that will be only called by other apps.

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:

Helloworld-icon.png


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: 

<?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, world title!</title>
	
	<!-- Load the Mojo Framework -->
	<script src="/usr/palm/frameworks/mojo/mojo.js" type="text/javascript" x-mojo-version="1"></script>
	
	<!-- Some fancy CSS styles -->
	<style type="text/css">
		#content { 
			text-align: center;
		}
		
		#app-footer {
			margin-top: 25px;
			font-size: 80%;
			text-align: center;
		}
	</style>
	
</head>

<body>

	<!-- Make a fancy Pre-looking header -->
	<div class="palm-page-header">
		<div class="palm-page-header-wrapper">
			<div class="title">
				My First webOS App!
			</div>
		</div>		
	</div>
	
	<!-- Make a fancy Pre-looking button -->
	<button class="palm-button" id="my-awesome-button">I'm an awesome button!</button>
	
	<!-- Just some text -->
	<div id="content">
		Hello, world!<br/>
		<img src="icon.png"/>
	</div>
	
	<!-- Footer -->
	<div id="app-footer">
		<hr/>
		© 2009 <a href="http://www.evan.pro/">Evan Coury</a>
	</div>
	
</body>
</html>

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: 

<!-- Load the Mojo Framework -->
<script src="/usr/palm/frameworks/mojo/mojo.js" type="text/javascript" x-mojo-version="1"></script>

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... 

<!-- Make a fancy Pre-looking header -->
<div class="palm-page-header">
	<div class="palm-page-header-wrapper">
		<div class="title">
			My First webOS App!
		</div>
	</div>		
</div>

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: 

<!-- Make a fancy Pre-looking button -->
<button class="palm-button" id="my-awesome-button">I'm an awesome button!</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 <img> 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 <link rel="stylesheet" type="text/css" href="css/styles.css" /> in the <head> 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:

  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:
* 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 {}

Screenshots:

Helloworld-launcher.jpg Helloworld-screenshot.jpg


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 

#!/bin/sh
#moveapp.sh
APP=com.foobar.app.$1

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: 

#!/bin/sh
# unpack new app into media internal, reset the command cache, and start watching the log
MYACCOUNT=myaccount
# you should sudo this or run as root        
                                             
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

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.
Retrieved from "http://wiki.webos-internals.org/index.php?title=Tutorials_webOS_Hello_World&oldid=17315"