User Guide

Updated 4/19/10

What is Ares

Ares is the code name for Palm's browser-based, web-hosted development environment for the creation of webOS applications. It contains:

• A drag-and-drop visual interface builder
• A code editing environment
• Visual Javascript debugger
• Log Viewer Utility
• Framework enhancements to support easier layout and event handling
• Single-click deployment/launch on device or emulator
• Drag-and-drop file upload, file/project download
• Version Control Integration (SVN/Mercurial)

Prerequisites for using Ares

• Installed webOS SDK - While not strictly required for application development, the SDK has drivers for running applications on the device over USB, and has the superior debugging/logging configuration of the Palm Emulator. For best results, you will want the SDK installed.

Browser Support

Ares has been tested on:

• OSX: Safari 4.0+, Firefox 3.5+
• Windows: Chrome 3, 4, Firefox 3.5+, Safari 4.0+
• Linux: Firefox 3.5+

Ares will not work on:

• Chrome 4 beta for mac (Launch, other plugin-related features don’t work)
• Firefox 3.0.x
• Internet Explorer

You will need to accept the security dialog of our plugin in order to have drag and drop file upload, as well as debugging/logging/installation of applications locally.

Status of Ares

Ares is now version 1.0, and is no longer in beta.

Logging into Ares

Ares uses the same username and password as the Palm developer portal

How Ares differs from "regular" Mojo

If you want to import or create an existing project in Ares without using the Interface Builder, you can do so entirely in the code editor portion and the application will be no different than an existing Mojo application. If you use the visual Interface Builder, there is an additional <scenename>-chrome.js file for each view. This file is JSON metadata created by the Interface Builder, and contains extra code that supports the visual and advanced layout aspects of Ares. How this differs from regular Mojo is there is a scaffolding of container objects that handle layout, and at runtime Mojo widgets are instantiated in those containers.

You can mix and match Ares and regular scenes in your application, but if you try and mix the two within the same scene, your mileage may vary and this is not supported.

You can import an existing mojo application for the purposes of debugging or log viewing or editing. This is fully supported and encouraged, as Ares offers a vastly improved debugging experience over the current toolset.

 

 

Ares Interface

Focused Project

All actions in Ares assume that you want to perform them on the current focused project. Which project that is determined by what file is currently open. If you have a file open from a particular project, that is the project that will be the focus of any action performed.

Main Menu

 

View

This menu switches between the various views within Ares. The main elements are:

• Designer/Interface Builder - used to edit *-chrome.js files visually using Drag and Drop
• Code Editor - used to edit javascript, html, text, or JSON files
• Debugger - Toggles the debugger panel on top of the code editor - it is resizable once visible
• Log Viewer - Toggles the log viewer panel on top of the code editor - it is resizable once visible
• Debug/Log - Shows both the debugger and log viewer on top of the code editor.

Ares also navigates between the designer and code editor depending on whether you have a -chrome.js file in focus or not.

 

New

This menu is used to create new artifacts within Ares. It has the following options:

• New Application - this creates the application framework for a new Mojo application. It also creates on default chrome file and opens it in the designer, so you can start creating your user interface right away.
• New Scene - this creates a new scene in the current application. This will create a new <scenename>-chrome.js file and open it in the designer, and a matching <scenename>-assistant.js file.
• New Document - this creates a blank document in the code editor, which can be edited and saved using the save menu to create a new HTML, javascript, json, or other file.

Save

The Save menu is a “split button” - meaning it is a dropdown menu, but also has a default action (“save all”) that is performed if the button is merely clicked. To see the menu, click on the dropdown arrow to the right of the save icon.

The options are pretty self-explanatory - Save current file, Save All, and Save As.

 

Launch

The launch button is also a split button. The actions that can be performed:

• Launch Application - this will package, download, install, and launch the current application either in the emulator or an attached webOS device over USB. Note - when a webOS device is plugged in, that device takes precedent over the emulator. If you are wondering why your application did not show up in the emulator, first check to make sure you don’t have a device plugged in as well!
• Browser - this will preview the user interface of your application in the browser. This is limited, because services will not be available. It also only works for Ares-created applications, though it is possible to get an existing Mojo application to also show up.
• Package - this will package your application as an ipk file that can be installed separately, shared with friends or testers, or uploaded to the Palm App Catalog
• Restart Emulator - especially when debugging, you may do something that causes the emulator to trip up. Rather than restart Virtualbox, you can use this menu item, which will restart the LunaSysMgr process on the emulator, which just takes a few seconds.

Help

The help menu contains a list of the resources we have available to assist you in understanding Mojo and Ares.

Interface Builder (Designer)

The interface builder has three main sections. By default the left side contains a palette of widgets that you can drag and drop onto the canvas in the middle. The far right section is the property inspector, which has 4 tabs that contain all of the properties, style options, and events for a widget that has been selected.

Behind the palette are two other sections - A "view" tree, which is a tree-representation of your interface (useful if you have a complicated interface with many nested objects), and a File tree, which shows you the assets of your project. This will be discussed below in "The File Tree"

The File Tree

The file tree shows you all of your projects and their assets. Here you can also download all or part of your project, integrate with source control, and upload custom assets to your project.

Code Editor

The code editor is based on Mozilla Bespin [LINK]. It lets you edit code. Every chrome file has a matching assistant file that contains the code for that scene. For example, the default scene in a application is called main. Main consists of two files - main-assistant.js and main-chrome.js. The chrome file is edited visually in the interface builder. The assistant file is javascript code and is opened in the code editor. Switching between files and palette will swap between these two files.

Debugger

The debugger can be toggled on from the view menu. In order to debug an application, use the Palm Emulator from the SDK for now. A project must be present in Ares to debug, as well as already installed on the emulator. After toggling the debugger on, you can set breakpoints by clicking to the left of a given line number, then pressing "continue" and running your application until you hit the breakpoint.
At that point you can use the console (after the ">") to inspect variables, including complex variables that are returned as name/value pairs you can drill down on. You can also use the stack trace button, and step into, over, out of your code. Be sure to turn off the debugger when you are done debugging, or the emulator can get stuck on random exceptions and will need to be restarted. There is a 'restart emulator' menu item under "launch" in the top menu.

More Information

Log Viewer

The log viewer allows you to view logs at the device or application level, as well as see the results of version control (VCS) operations.

Creating a New Project

You will have one fresh project created automatically for you on your first login to Ares. To create another project, use the "+ New” menu in the top toolbar, and select Application. This will generate the app template for you, and open the main-chrome.js file. This is the Ares visual design file

File Upload

From the file tree, you can drag and drop files from your computer onto the panel in the bottom left corner of the screen, and released to upload to the selected folder in the tree. Dragging a directory/folder is not supported, but groups of files are, and zip files of multiple directories/folders can be uploaded and will be automatically unpacked into the selected folder.

File Download

Click on any file, project, or folder in the tree and then select the download button at the top of the tree. This will package it up as a zip file for download. You can then delete the files in Ares if you don't want to store them on our server, and after editing locally, drag the zip file back onto the screen as described above to re-upload it.

You can also download an ipk file of your project from the launch menu at the top of the screen.

Source Control

In order to set up source control, your server must be accessible from Ares - meaning hosted online outside of your firewall, or something like bitbucket.

More Information

First, you have to set up a keychain password for use with Ares. After that, you can check out a project, or add your project to an existing version control system.

A few "gotchas":
1. When adding a project to source control, you must include in the path a directory that will contain your project, not just the root of all project directories. This is the most common mistake when attempting this. So you want something like http://svn.mycompany.com/svn/myroot/<projectname>/ as the URL.
2. Source control commands are project-wide (check in, etc). You can't keep parts of your project local/dirty - it is all or nothing. This will be addressed in a future version.
3. Diffs, etc take place as in the command line for these systems, in the log viewer under "VCS".

More Information

Running your project

In the launch menu (symbol is a "play" triangle) - select launch. You can also just click the play button. This will package, locally download, and install your application on the device or emulator. This works the same way as in the SDK, just over a plugin. If a device is plugged in, it takes precedence over the emulator.

There is also a browser preview mode that will show you your interface in the browser directly. It will do scene transitions kind of like Palm Host used to do.

 

The Interface Builder

Layout

More Information

There are a few different ways to lay out an application in Ares. There are three basic containers that can be mixed/matched/nested to achieve the desired results:

• VBox Panel - this is the default behavior of the main canvas. VBox Panels arrange their children vertically. They assume a vertical stack - you can't free-form drag an object to any location - only a given location in the vertical stack. This will seem restrictive at first but is best practices, which is why it is default.
• HBox Panel - this is just like a VBox Panel, but horizontal. VBox Panels and HBox Panels can be combined to create a very HTML-like layout that is flexible with screen rotation and different sizes.
• Absolute Panel - this is the one that is closest to a traditional interface-drawing tool. It allows you to exactly position its children in x/y coordinates and with precise sizes, It also allows use of the "resize behavior" widget to maintain relationships with its parent borders, but is less flexible with rotation and different screen sizes. This is why it isn't the default. For games or other fixed-screen areas of an application, absolute is appropriate.

To change the layout type of any panel, including the main canvas, set the "layoutKind" property to the desired value. "vbox", "hbox", and "absolute" are valid values.

There are also a few other widgets that are useful for layout:

• Scroller - this is a scrolling container. If you want your whole app to scroll, which it wont by default (different than mojo), you want to first drag a scroller widget out and select "Maximize" from the property inspector. Then your whole screen will scroll. Alternately any sub-container of your application can be made to scroll this same way - drag a scroller into a panel and select "maximize"
• Drawer/Collapsable - These are hidden areas of the screen that can be shown/hidden using a header or code.

Mojo UI controls tend to be fixed-height, and many are not resizable in this direction. Resizing their container only changes things like padding or margin.

Sometimes it can be tricky to get widgets inside of each other or a given container - if something strange happens, consult the "view" tree. It can be illuminating as to what happened and what needs to change to fix it.

Not all widgets can render in design mode, such as webview, which requires a webkit extension present only on the device/emulator. Those widgets are represented only as a blank container in design mode.

Drop Targets

When you are dragging a widget, the target container for that widget will highlight with a purple border, and the position within that target will show up as a green box (in absolute) or green line (in vbox/hbox)

Palette

The palette contains these sections:

• UI Widgets - these are the main UI controls in Mojo. Note that many of these are not resizable in all directions. For these widgets, the bounding box in the designer is mostly to give those widgets extra space if needed.
• Images - these are image-related controls from Mojo
• Layout - these are containers for other widgets that control the layout of their child widgets.
• System Services - New - These are non-visual components which can be dragged and dropped onto the canvas, where they will show up at the bottom of the screen and be inspected and configured in the property inspector, and called with simple lines of code.
• Sensors - New - Contains components for the sensors on the device, like GPS
• Media - New - Components for playing a sound or using the camera
• PIM Data - New - Components for accessing calendars, tasks, etc - and setting events or new objects
• File I/O - New - Components for uploading, downloading, or opening a file
• Web Services - New - Components for accessing an RSS feed or web service
• Launch Apps - New - Components that allow you to launch built-in applications with parameters, for example launching the email app with the recipient and subject pre-filled in.

Components:

• Ares now has Components, which are widgets that provide functionality, but without any user interface. The palette now contains the service calls, sensors, etc that are in the webOS SDK.
• Components can be drag-and-dropped onto the canvas, where they will show up as icons across the bottom of the screen. They can be selected and configured in the property inspector, and then called in a single line of code.
• Inline help - When a component is selected on the canvas or view tree, the last tab of the property inspector will show jsdoc-style inline help for that component, so you can see what you can call on each component.
• For example, you can drag out a camera component, and in the ontap handler of a button, type this.$.camera1.execute(); to launch the camera in your app!
• See the 1.0 tutorial to see how easy it is to create an app that connects to phone services using components.

Property Inspector

The property inspector is where you set properties on a widget that is in focus in the designer. These properties are grouped into four main sections:

Settings

This is the basic core set of properties. Near the top are common properties shared across most widgets.

The Sizing tools buttons can be used to quickly change the geometry of a widget to take up all available space, or available space in the X or Y direction. More Information in Layout In-Depth

There are a number of properties that can affect layout that are under geometry. In most cases these properties are set for you as you arrange widgets on the canvas or change a widget’s size on the canvas, but can be fine-tuned manually here. This is the case for left, right, top, bottom, height, and width.

Plane is similar to z-index in CSS, and can be used to place widgets in front of other widgets, if, for example, you want a header widget to stay on top while the contents scroll by behind it. You would set the header to be on a higher plane than a scroller widget in the background.

Resize Behavior is really only useful in absolute panels. The red “struts” are used to indicate which relationships between a widget’s outer edges and its parent’s margins will be maintained. The green “springs” are used to indicate in which directions a widget will grow when orientation is changed, or in which dimensions the widget is maximized.

General is used to modify exposed Mojo properties. These can vary greatly from widget to widget.

Styles

Styles are used to affect the style of text or a widget. Note - in many cases Mojo’s built-in styles override user-specified styles, depending on the widget and how it is structured and how classes are inherited. This will be addressed in a future version of Mojo and Ares. So not all styles will work with all widgets, but all will work with entered text, for example.

Images - (bgImage) this brings up a picker, that will let users select from images within the focused application’s /images directory. You need to upload images to that directory to see them in this picker.

Colors - colors can be entered in any valid HTML way (examples: “white”, “#FF0000”, “#F00”)

Margin, Padding, others - in general, pixel values are used. “55” and “55px” are both valid.

Events

Defining event handling in an Ares application is a little different than standard Mojo. From a widget, in the property inspector events tab, you can type in any method name you want for an exposed event, and click the button at the end of the text field to have that event stubbed out in code in the code editor. By default those methods are passed the event (event) and the widget (inSender) that called it.

Model

Model contains model-related properties within Mojo. These are not visible for all widgets. You can set your widget properties to be defined by a certain model attribute using these properties.