The 10-minute guide to Ares for WebOS

This is the 10-minute reference that I was looking for when I started using Ares for my WebOS projects.  Topics covered:

• UI Basics
• Widget Fundamentals
• Using Widgets the Ares Way
  

UI Basics

After starting a new project, you will have a fresh canvas full of potential!  Your screen will look like this.

If you haven’t familiarized yourself with the UI then let’s take a quick tour together.

Left Panel

On the left-hand side, you have a menu that toggles the left pane between 3 views.  The 3 views are:

• Palette This view contains all of the pre-built widgets that can be used in your app.  Buttons, check boxes and text boxes are just some of the choices here.  You will notice that this panel is organized by widget type, with visible widgets listed first and then things like system services coming later.  Everything under the Palette panel can be added to your application by dragging the widget onto the scene.
• View Don’t dismiss this panel, it is incredibly useful!  The view panel shows you the hierarchical layout of your widgets.  If you are wondering why your widgets don’t quite look right, this panel can be invaluable.  For instance, you can quickly see whether a button is contained inside of a horizontal scroll panel.
• Files This panel allows you to browse your projects and files, double clicking a file will open it in the viewer.

Right Panel

On the right-hand side, you have a menu that toggles the right pane between 4 views. The 4 views are:

• Settings This panel displays the settings for the selected widget.  Each widget has a unique set of properties.
• Styles This panel displays the style for the selected widget, allowing you to change padding, background color and opacity on a per-widget basis.
• Events This panel displays a list of events that can be hooked for the given widget.  Events are used as a way to perform an action based on user interaction with a widget.  For instance, a Button has the following events. Clicking on the icon that looks like a piece of paper will automatically add a new event handler for a given event and will create an empty event handler method in your code!
• Help This panel display help for a selected widget.  As of this time, only non-visible widgets contain help entries.

Bottom Panel

At the bottom of the screen you’ll see the Non-Visual Components section.  When you drag services and other non-visual widgets to the canvas, this is where they show up.

UI Navigation Tips

• When a widget is selected, the ESC key will select the parent widget
• The View tab makes selecting the correct widget infinitely easier
• When dragging a widget across the UI, the dragging pop-up shows you which container you are currently hovering over. This makes it much easier to place widgets
• Dragging/dropping in the View menu does nothing

Widget Fundamentals

Scrollers

One thing you will almost always want to do is add a Scroller widget (Palette -> Layout -> Scroller) as the first item in your scene.   If you do use a scroller widget then you can simply use your mouse-wheel to scroll the scene up/down while designing.  If you don’t use a scroller widget and your scene extends beyond the height of the screen, you will have to hide widgets to be able to reach the widgets further down on the screen.

Once you add the Scroller, you may notice that it does not fill the scene.  To easily make the Scroller fill the scene, you can use the right-hand panel (Settings -> Sizing Tools -> Maximize).

Widget Names

Even if you never plan on sharing your code, it is good practice to give useful names to the widgets that you will be referencing often (Buttons, labels, services).  It is important that you do this before you start adding event handlers to your widgets, otherwise you may have to go and change the names of any event handlers attached to the widget.  Many people use the objectVerbNoun naming scheme for things that perform an action (buttonCloseAlert or buttonSendData) and the objectNoun scheme for things like labels (labelAddress).

Note: I usually don’t rename my scrollers and headers since I never refer to them in the actual code.

Using Widgets the Ares Way

Ares makes widgets easy to use.  To illustrate how to interact with widgets in Ares, I have created a simple project.  You should have no trouble creating the same project by looking at this screenshot.

Here we have a very simple scene, a scroller, header, label and button. The top right panel under the Common section is where you make your basic modifications like changing the name and label of a widget.  For instance, on my header, I changed the label property to Widget Fundies. I also changed the label property of labelForce so that it is empty and buttonUpdateForce to The Force.

Updating Widgets Programatically

Select buttonUpdateForce and add an event handler for ontap:

After clicking, you will be whisked away to the code view where you will find this event handler:

buttonUpdateForceTap: function(inSender, event) {

}

Let’s make our button do something by modifying line 2 as shown below.

buttonUpdateForceTap: function(inSender, event) {
  this.$.labelForce.setLabel(Is Strong!);
}

Because the buttonUpdateForceTap event handler is defined in the MainAssistant.prototype, this refers to MainAssistant.  Adding the dollar sign this.$ refers to the collection of objects inside MainAssistant, meaning that every widget contained in main-chrome.js is available through this.$.  Although you cannot see the code generated, when you switch to the GUI view of main-assistant.js, you are actually modifying main-chrome.js. You can modify any common property using this method, here are a couple examples.

//Get the current value of the label
var currentValue = this.$.labelForce.getLabel();

//Change the label of our button
this.$.buttonUpdateForce.setLabel(Join the Dark Side);

//Change the class of our button
this.$.buttonUpdateForce.setButtonClass(secondary);

//Make our button disappear
this.$.buttonUpdateForce.setShowing(false);

//Get the value of showing
var isShowing = this.$.buttonUpdateForce.getShowing();

That is all for this brief introduction, go forth and program!