www.webOShelp.net

Welcome to the second attempt at writing up Palm's first official webOS / Mojo SDK tutorial.  This incarnation is much shorter than the previous and is split into two parts; one for the application that was built during the webcast and the other for the more advanced stuff that was discussed briefly at the end of the presentation.  The second part will be posted tomorrow. Update: Will be posted Monday.

A great high-level overview of the material covered during the webcast by Mitch Allen was written up by Andrew last week. This article will get into the technical details of the code tutorial section. If you're new to web development, you may want to start with our beginner or intermediate tutorials before diving in.

Topics covered in this tutorial:

• appinfo.json - what makes this file so important
• index.html - what goes into this file
• stage assistants - a very simple example that demonstrates pushing the first scene of an application
• scenes - palm-specific css styles, UI widgets
• scene assistants - moving between scenes, passing data between scenes

If you're just here to grab the sample application code, you can find it here.   To view the actual webcast in which this material was presented, click here.

The first thing covered was the folder structure of a webOS app. Here is the complete structure for this tutorial application:

• [myapp]
  • [app]
    • [assistants]
      • first-assistant.js
      • second-assistant.js
      • stage-assistant.js
    • [models]
    • [views]
      • [first]
        • first-scene.html
      • [second]
        • second-scene.html
• [images]
• [stylesheets]
• appinfo.json
• icon.png
• index.html

[]=folder

Following file naming conventions is important because webOS uses scene names (in this case "first" and "second") to coordinate scenes with their assistants.

webOS applications follow a model-view-controller (MVC) architecture. Assistants are Javascript-based controller-like objects that help manage your application. Views are represented by scenes, which are HTML files. It's unclear at this point what type of files would go in the model folder, but it was evident from the tutorial that having model files is not a requirement to get your application to run, though certain applications would almost certainly benefit from them.

The most important file here is appinfo.json. This file contains some important configuration info and is required for webOS applications:

{
   "title": "MyApp",   
   "type": "web",   
   "main": "index.html"   
   "icon": "icon.png",  
   "id": "com.yourdomain.app.myapp",   
   "version": "1.0",   
   "vendorid": "com.yourdomain.app.myapp",   
   "removable": true   
}

The elements covered in the tutorial were:

• title: The title of your application, which will be displayed at the top of your application's card.
• icon: The file that will represent your application in the webOS launcher.
• id: Your application's id, which is used by webOS to properly communicate with your application. It must be unique among all applications. The reverse dns notation seen above was recommended to help quickly find a unique name for your app.

That was actually all that was covered during the tutorial. However, we can guess what a few of the other elements are:

• main: The main file of your application; probably the first one that gets loaded after appinfo.json.
• version: The current version of your application. Most likely will be used to automatically determine if an update for your application is available.

There are also a couple that inspire some speculation:

• removable: An indication as to whether this application is uninstallable? Probably not, as I would expect it be a requirement that all applications be removable. More likely it's a reference to whether the application can be installed on removable media vs. on the device's internal memory. This was a feature of older Palm devices, and although the Pre does not support removable memory, future webOS devices almost certainly will.
• type: A reference to other application types that may be available in the future? e.g. "native"? We can only hope.

The next file we went through was index.html. Code that was automatically generated by the SDK appears in black, and code that was added during the course of the tutorial appears in red:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" https://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd>
<html xmlns=https://www.w3.org/1999/xhtml xml:lang="en">
   <head>
      <title>MyApp</title>
      <script src="/usr/palm/frameworks/mojo/mojo.js" type="text/javascript" x-mojo-version="1"></script>
      <script src="/app/assistants/stage-assistant.js" type="text/javascript"></script>
      <script src="/app/assistants/first-assistant.js" type="text/javascript"></script>
      <script src="/app/assistants/second-assistant.js" type="text/javascript"></script>

      <!--application stylesheet should come in after the one loaded by the framework -->
      <link href="/stylesheets/main.css" media="screen" rel="stylesheet" type="text/css"        />
   </head>
   <body>
   </body>
</html>

There are several items of note here. The first is that you must include the mojo framework explicitly in every application. You must also include the stage assistant and assistants for your scenes. Mitch mentioned alternatives to managing your files this way, but didn't go into details during the tutorial.

The first file referenced after the mojo framework was stage-assistant.js:

function StageAssistant () {
}
StageAssistant.prototype.setup = function() {
   Mojo.Controller.stageController.pushScene ("first");
}

By default it contains the two functions above, which are both empty. We added the pushScene command to the setup function which is run when the application is launched.