Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

229 lines (126 sloc) 14.262 kb

Building your first Crossplatform Native Smartphone App with RhoHub

The Rhodes framework allows you to quickly create and build applications for multiple smartphone platforms. RhoHub makes deploying Rhodes applications even easier, reducing the overhead of getting started and as well as streamlining ongoing development effort.
Rhodes applications are written in Ruby, and use standard conventions recognized by all web developers to navigate between views.
Interface design is quick and easy, as create your views using HTML and CSS, using embedded Ruby code to create dynamic, data-driven elements.
This tutorial shows you how to build a simple product inventory application that allows users to create, retrieve and edit local data without requiring a connection to a the internet.

Step 1. Create your Rhohub account

Create a Rhohub account at rhohub.com. After signing up, you will receive an email containing a link directing you to http://.rhohub.com/dashboard. This is your public profile page. To access your dashboard, click the “Login” link in the upper right-hand corner of the page and enter your login information.

Step 2. Create a new application

  1. From your dashboard, click on the “Create application” button.
  2. On the page that follows, enter a code name for your application and a description that will help you identify the app. The name and description you enter here will be visible to all other RhoHub users, unless you have created a private project.

Step 3. Create an Object

  1. Enter “product” as your object’s name.
  2. Add attributes ‘brand’, ‘name’, ‘price’, ‘quantity’ and ‘sku’ to your object.
  3. Click “Create Object”.

By default, each your application will contain views that allow your users to interact with the object, and each attribute you add to your object will be available as field or strings in your UI. RhoHub also generates your controller file, containing code that supports default actions like listing, creating, displaying, updating and deleting your object will be created for the object as well.
Note that each object you create must contain at least one attribute. Object attributes should be named using alphanumeric strings.

While in this app we only use one object, you can create additional objects for your app by following the “Create new object” link under QuickLinks".

Step 4. Take a look at your application

Once you have created the Product object, you will be passed to a text editor embedded within the browser. The RhoHub text editor supports several keyboard shortcuts, so you can develop your mobile applications from any location.
A file tree is located on the left-hand side of the window that will allow you to inspect the files that have been automatically created for your application. The tabs at the top of the tree allow you to view the client- and server-side code that has been generated: for this application, we’ll ignore the server code. Under the client tab, all of the code for your “product” object is in a single folder in the app directory called “Product.”

Step 5. Define your app’s Start page

  1. Select “rhoconfig.txt” at the root level of the client directory.
  2. Define the path to your start page.
  3. Change the start path (start_path) to
start_path = '/app/Product'

Note: paths are case-sensitive.

Save your change (the button is to the upper-right hand side of the text editor).

By default, a new Rhodes application displays the content in app/index.erb on launch. In more complex applications, you can edit that file to contain links to different pages in your application. However, since this application only has a single object, we will use the products index as the start page.

Step 6. Build the App

RhoHub allows you to build native applications for Android, iPhone, BlackBerry, and Windows Mobile based phones using the same simple code base.
However, mobile device simulators may only be supported on particular operating systems, so you may not be able to test your application locally for all platforms without some virtual machine magic:

  • Windows is required to test builds and install to a device for BlackBerry and Windows Mobile, however, running the simulators in Windows virtual machines such as VMware or Parallels works fine.
  • Mac OS X 10.5+ is required for testing iPhone applications.

Since Android simulators are available for all major operating systems, we’ll build our app for Android in this tutorial.

  1. Select the “Builds” tab at the top of the window.

  1. Select “Android” as the “Build Type”.
  2. “Version” refers to the Rhodes version used to build the application – leave the default value in place.
  3. Click “Create Build” to begin building your application. While your application is building, you will see the build status displayed below.

When your application is finished building, you will see “Success” in the status column:

Step 7. Test the App

To test your app, you need to download and install the Android SDK 1.5 on your development machine. Don’t forget to modify your path to include “path_to_android_directory/tools”
You’ll need to verify that you can run the simulator before installing your application. At the command line, enter the following command to create a virtual device :

 android create avd --name rhoAndroid11 --target 1 --sdcard 32M --skin HVGA

The following output will be displayed:

 Android 1.1 is a basic Android platform.     
Do you wish to create a custom hardware profile [no]

Press return (you don’t need a custom hardware profile), and you should see:

 Created AVD 'rhoAndroid11' based on Android 1.1

To ensure backward compatibility, you will build your application for Android 1.1.

Running the emulator

To run the emulator, type the following at the command line:

emulator -avd rhoAndroid11

The Android emulator will open in a window. The emulator window will open quickly, but you may see a black screen on the simulated device for a few minutes while you wait for the emulator to start up. Continue to wait until it looks like this:

Install the app

Return to RhoHub in your browser. Click on the Builds tab. You will see your build under the heading “Build Downloads”. You will need to download your build by clicking on the download icon.

Once you have downloaded and unzipped the file, open a second terminal window and go to the directory where you unzipped the build from RhoHub
To ensure that you have downloaded the correct build files (and not the source!), list the contents of the directory and verify that you only see the following two files:

 Inventory.apk* 
log.txt* 

To install the app in the emulator, use the Android adb command:

 $ adb install Inventory.apk 
2099 KB/s (698543 bytes in 0.324s)
pkg: /data/local/tmp/Inventory.apk 
Success

Open the app

To see your app running in the simulator, click on the gray tab at the bottom of the screen:

The tab will slide up to reveal the built-in and installed applications. Your new “Inventory” application will be displayed with the Rhodes logo by default.

Click the application icon and Inventory will open to the product page:

Using the Inventory application

Your Inventory application features several auto-generated pages corresponding to the actions in your Product object’s controller.rb file ( “index”, “show”, “new”, “edit”, “create”, etc). The page we are using as our start page uses the index action and the “/product/index” view file, so the first thing a user will see when launching the application is the list of products they have added.

But our list is empty! Aha – we need to add records to the before they can be displayed in the list!
To create a new product record, click the “new” button on the index page. You will see the following page:

When you click “New”, the controller creates an instance of the Product object, then renders the page using new.erb. You can see the method for the “new” action in your applications source code at Product/controller.rb line 18.

You can now enter data for new product records. New products you create will be displayed in a list on the index page. The following screenshots show data entered for the Acme Hovercraft. When you click create, the controller.rb action “create” is called, creating the instance of the object and returning you to the main product page.

The main product index will now show one item in the list. By default, only the first attribute you created for your object will be displayed to represent the product – in this case, Acme represents the Acme Hovercraft.

To view all of the item’s attributes, click the link for that item. If you click on the “Acme” item, you will see a page that displays all of the attributes for the hovercraft:

To edit a product, click “Edit” in the top-right. The application will display a page similar to the “new” page which allows you edit or delete the record:

Step 8. Customize your views

By default, the index page displays items using the item’s first attribute, the brand of each product. But what if we have multiple products from the same manufacturer? We won’t be able to distinguish between them from the index alone.
So that our users won’t have to view each record to find out which of the 27 Acme products is the hovercraft, let’s add the name of the product to the index page, allowing us to we can distinguish between different products from the same brand. To modify the display of our application’s index page, we can simply edit our index.erb file.

  • Back in your RhoHub editor for your project, find the following line (around line 11) in app/Products/index.erb
 <li><%=link_to "#{x.brand}", :action => :show, :id => x.object%></li>
  • Add the product’s name to the list item as follows:
 <li><%=link_to "#{x.brand} #{x.name}", :action => :show, :id => x.object%></li>
  • Save the file.

Load the new version of the app

  • Go to the builds tab and create a new build.
  • While the build is in progress, uninstall the last build if necessary. Different simulators may differ in how you reinstall your application. Since we’re working with Android, we need to uninstall the previous version of the app from the simulator.
$ adb uninstall com.rhomobile.inventory
Success

Note: the uninstall command uses your application’s identifier (com.rhomobile.inventory) instead of the application’s name used by the install command.

  • When the build is complete, follow the same steps you used above to download and install the application in the simulator.
$ adb install Inventory.apk 
1626 KB/s (657878 bytes in 0.395s)   
pkg: /data/local/tmp/Inventory.apk 
Success
  • After you have installed the application, launch it from the simulator.
  • Add another product by clicking the “New” button. Create a product with using the brand “Ford”, and the name “Flitter”. The main page should now look like this:

Building for other platforms

Okay, now we have an Android app that lets us add products to a list. What changes do we need to make to our code for it to run on other platforms?
Nothing! You can use the same code without any modifications to build your application for other target platforms using RhoHub.
To test other device builds, you will need to install the appropriate simulator and/or SDK from the platform vendor.

iPhone Launcher

If you are developing applications for the iPhone on a Mac and have installed the iPhone SDK, download the Rhodes Desktop Client from your Inventory application’s overview tab.
The desktop client provides a single button that enables you to easily build, download and run your app in the iPhone simulator with a single click.

Note: if you are running in the iPhone simulator and you want to look at the client log you can find it in the following directory under your user account:

~/Library/Application Support/iPhone Simulator/User/Applications/

The application is contained in a folder named after its GUID. If you have multiple projects in your iphone directory, finding the GUID might be tricky… but sorting the files by date modified usually puts the most recently installed app at the top of the list.

Note: If you sort the contents of the Applications directory by date modified descending, there will be a file ending in .sb near the top of your list of applications – if the timestamp on that file matches the time you clicked “Reload Application”, the filename most likely represents the GUID of your application.
In the folder labeled with your application’s GUID you will find your logs in the Documents folder.

Windows Desktop Client

Testing with the Rhodes Desktop Client is an alternate workflow on Windows that reduces the number of steps required to test your application (and starts much faster than the device simulators); however, you will still want to test your final application on the specific target platform.

Jump to Line
Something went wrong with that request. Please try again.