Ares Documentation

Tutorial: Flickr Search

This tutorial will guide you throught the creation of a webOS application using Ares, Palm’s online visual development tool. Before following the steps here, be sure to read the Ares Oveview document. It contains important information about Ares that you will need to know before trying to build an app using the tool.

This tutorial will guide you through creating a Flickr Search application.

Prerequisites

Make sure you do the following before you attempt to follow this tutorial:

Install the webOS SDK from developer.palm.com

Download this zip file of images used in this tutorial, and unzip it on to your computer to a location you can easily find.

Create a new application and upload the images

In the New menu at the top of the screen (+ icon), select New Application and name the application FlickrSearch. This will create a new application and load the first scene’s chrome file onto the main Designer view.
On the top of the left column of the Designer, there are three tab buttons. One called Palette is active. It contains the widgets that can be used You will also see View and Files. Select Files to show the file tree.
Select the images directory under Applications/FlickrSearch in the file tree so that the folder is highlighted.
On your local file system, navigate to where you unzipped the zip file. Go to the images directory of the file to reveal the two images we will use. Ignore the code directory for right now.
Select the images on your local file system and drag them onto the area in the lower left corner of the Ares window to the dark area below the words Upload local files to the “images” directory. If you do not see those words, make sure you followed Step 3, above, correctly. For further information see the section in the Ares FAQ about uploading images.
Drop the files on that area, which should indicate that they uploaded. You should then see the tree refresh and those images will appear in the images/ folder.

Create first scene

First, we create the user interface for the first scene of our app.

Add logo
Click on the Palette tab to return to the designer.
Now it is time to create the first scene. Locate the Picture widget and drag it onto the canvas.
In the property inspector (in the Settings/General subsection), find the src property and click the magnifying lens to the side of the input to bring up the image picker.
You should see the two images you uploaded earlier. Select the Palm logo and click OK to close the dialog. The image on the screen should change to the Palm logo, and the path to that logo will appear in the picture’s src property.
Now, in sizing tools, select the X button to resize the logo to the entire width of the screen automatically.

Add search field
Back in the palette, locate the Group widget (in Layout) and drag it onto the canvas below the logo.
In the Property inspector, set the label property of the group to Search and press the Enter key. The group label should now show as SEARCH in the canvas.
In the palette, locate the TextField widget (in UI Widgets), and drag that inside of the group you just created.
In the property inspector, set the name of the textField to searchField. (Note: This is case-sensitive; if you get this wrong the application will not work with the supplied code.)
Still in the property inspector, set the hintText property (near the bottom of the General section) to search filter. If you cannot see all fields in this section click on the section and drag it up to scroll the contents. You should see the contents of the search input in the canvas change to reflect this.

Add search button
In the palette, locate the ActivityButton widget (in UIWidgets), and drag it onto the canvas below your group.
In the property inspector (in Settings/Common), set the name property of the activity button to searchButton. (Note: This is case-sensitive. If you get this wrong the application will not work with the supplied code.)
Still in the property inspector, set the label property of the button to Search - you should see the label on the button on the canvas reflect this change.

Add scroller
In the palette, locate the scroller widget (in Layout) and drag it onto the canvas below the search button.
In the property inspector (in Sizing Tools), select Maximize to resize the scroller to take up the rest of the available space on the screen.

Create list inside scroller
In the palette, locate the List widget (in UI Widgets) and drag it onto the canvas inside the scroller widget. The scroller will highlight with a purple border when the widget is in the right spot.
Still in the property inspector (in Common), set the name property of the list to photoList. (Note: This is case-sensitive. -If you get this wrong the application will not work with the supplied code.)

Create list template
Still in the property inspector (in Items), click the button on the right side of the itemHtml property and a code editor will appear.
Paste the following HTML code into the editor:
<div class='result palm-row' x-mojo-tap-highlight='momentary'>
  <div class="palm-row-wrapper">
  <div class="title">
  <div class="picture-container">
  <div id="picture" class="picture-icon">
  <img src="#{photoUrl_t}"/>
  </div>
  </div>
  </div>
  </div>
</div>
Click OK to leave the dialog.

Add event handlers
Select the searchButton in the canvas.
In the property inspector, select the events tab. In the ontap event field, type in searchButtonTap. (Note: This is case-sensitive. If you get this wrong the application will not work with the supplied code)
Select the photoList widget in the canvas.
In the property inspector, select the events tab. In the onlisttap event field (not ontap), type in photoListListTap (Note: This is case-sensitive. If you get this wrong the application will not work with the supplied code)

Import main-assistant.js
Open the Files tab to see your project again.
Open the tree to FlickrSearch/app/assistants/ and select but do not open main-assistant.js by single clicking it.
Click the X button at the top of the file tree to delete this file. You will add a new prebuilt one to save time.
Select the assistants folder in the tree.
Navigate to the location on your computer where you unzipped the supporting files for this tutorial, and this time enter the code directory.
Drag main-assistant.js from your file system to the upload area and release to upload the new main-assistant.js file into the assistants directory.
Open main-assistant.js and verify that it has approximately 52 lines of code.

Run in emulator
You can run your application at this point. We assume you have installed the Mojo SDK and that you are running the emulator.
Click the Launch button at the top of the screen. This will package, download, install, and run your application in the emulator

You should be able to run a search for flickr photos and see a list of results. This is the first part of the application.

Create the detail scene

Now we’ll create and add the last scene we’ll need to make the app fully functional.
Back in the Ares window, in the New menu at the top of the screen, select New Scene and enter the scene name first. (Note: this is case-sensitive. If you get this wrong the application will not work with the supplied code.)
This will create the new scene, and load its first-chrome.js file into the designer.

Create interface for detail scene
Select the canvas of the second scene by clicking on the canvas.
In the property inspector, click the Styles tab button.
In that section, under Background, select the magnifying lens icon inside the bgImage property to launch the image picker.
Select the flickr background image and click OK to close the dialog. The background image should appear on the canvas.
In the palette, locate the imageView widget and drag it onto the canvas.
In the property inspector, set the name property of the imageView widget to photoView.
In Sizing Tools in the property inspector, click the Maximize button to resize the photoView widget so it takes up the entire screen.

Add the code for the detail scene
Select the Files tab button above the palette.
Open FlickrSearch/app/assistants/first-assistant.js if it does not open automatically for you.
In the function FirstAsistant(argFromPusher), add the following line of code:
this.photo = argFromPusher;
In the FirstAssistant.prototype block, add the following code after cleanup, and be sure to include the comma in the first line:
  ,
      activate: function() {
            this.controller.get("photoView").mojo.centerUrlProvided(this.photo.photoUrl);             }
Your first-assistant.js file should now look like this:
function FirstAssistant(argFromPusher) {
      this.photo = argFromPusher;
      }

FirstAssistant.prototype = {
      setup: function() {
            Ares.setupSceneAssistant(this);
      },
      cleanup: function() {
            Ares.cleanupSceneAssistant(this);
      },
      activate: function() {
            this.controller.get("photoView").mojo.centerUrlProvided(this.photo.photoUrl);
      }
};

Run completed app

Your app is now complete, and you can run it either in the emulator or on a webOS device to search for photos. Now when you select a photo in the list, you will see the detail scene pop up, which will allow for full-screen viewing of the photo.

Debugging (optional)

Now a brief tutorial on how debugging works. This is going to assume you have just completed the rest of the tutorial and that your app is installed on the emulator. In order for debugging to work, you need to load the app on both the debugger and Ares so you can set breakpoints correctly and keep code in sync.

Back in Ares, in the main document-selecting drop-down, select FlickrSearch/app/assistants/main-assistant.js.
In the View menu in the top left corner, select Debugger to toggle the debugger panel open.
In the Debugger toolbar, set the debugger to On. This will enlarge the gutter to the left of the line numbers in the code editor. This lets you set breakpoints by clicking in this area.
Set a breakpoint on line 32 of the file by clicking to the left of the 31. Note: It can be a bit tricky to click the right spot.). This line should start with this.request. You should see a red circle appear in the gutter next to 32.
Go to the emulator and run your application by finding FlickrSearch in the launcher and running it.
Enter a search string and hit the search button. The application should freeze, and if you go back to Ares you will see line 31 with a breakpoint set on it highlighted with a reddish background. The debugger should display the word Stopped in red.
You can now use the debugging console to inspect the values of variables. For example, type url into the line at the bottom of the debugger that starts with a >, and press the Enter key. You should see the url of the flickr api.
You can also inspect more complicated variables in the debugger. Type this after the > and press the Enter key.
You will see the name/value pairs of everything contained in the this object. You can click on a highlighted item to then see its name/value pairs, navigating complex objects.
You can use the Step over, Into, Out, and Continue buttons to step through your code.
You can also use the Stacktrace button to see the current stack in JavaScript.
When you are done debugging, be sure to turn the debugger off to return the emulator to its natural state.

Log viewing (optional)

Log viewing is easy. To activate the log viewer, select it from the View menu in the top left corner of Ares. It looks very similar to the debugger.

Turn on the log viewer in the View menu.
Select Application from the drop-down menu for log type.
Run your application in the emulator to see the logs live.
Be sure to turn the log viewer off before exiting.

View device logs

Turn on the log viewer in the View menu.
Select Device from the drop-down menu for log type.
Run any application or system UI in the emulator to see the logs live.
Be sure to turn the log viewer off before exiting.

The log viewer also allows for viewing the logs from version control operations. To see these logs, select VCS from the Log type drop-down menu. This will show you a view similar to that if you were using command-line SVN or Mercurial.

Palm Developer Center

Tutorial: Flickr Search

Prerequisites

Create a new application and upload the images

Create first scene

Add logo

Add search field

Add search button

Add scroller

Create list inside scroller

Create list template

Add event handlers

Import main-assistant.js

Run in emulator

Create the detail scene

Create interface for detail scene

Add the code for the detail scene

Run completed app

Debugging (optional)

Log viewing (optional)

View device logs