= Introduction 

The Rhodes framework is a platform for building locally executing, device-optimized mobile applications for all major smartphone devices. These applications are optimized for interacting with transactional enterprise application backends. It is also designed to work with synced local using  RhoSync at http://github.com/rhomobile/rhosync/tree/master. It is initially available for iPhone, Windows Mobile and Research in Motion (Blackberry) smartphones.  Support for Android and Symbian is planned.  

Rhodes takes much of its inspiration from web-oriented MVC style frameworks such as Ruby on Rails. However it has several simplifications and optimizations for the mobile scenario. Some of these are to make it easier for the developer. Most of them are to keep the framework as lightweight as possible to be able to run on mobile devices with limited memory. As with developing apps on any good app framework (Rails, Merb, Django), building a Rhodes mobile application consists of building a set of files and putting them into the right directories for the respective models.

= Starting a Rhodes Application

The first step in using Rhodes is to make a clone of Rhodes itself so that you can work in the \apps subdirectory.  

	git	clone git://github.com/rhomobile/rhodes.git rhodes
	
Notice that we are using the public clone URL.  We would prefer that you don't check your apps back in to Rhodes (and you won't be able to anyway).  So this is what makes sense for working on apps versus contributing to Rhodes itself. You will then do your work in \apps directory as described below.  

= Directory Structure 

The directory structure is as appears below. Beneath the Rhodes root directory (as determined by doing a git clone of the Rhodes projects) there is an apps subdirectory.  There is an index.html in this that contains the "top level" content, which will generally be a list of available applications.  It starts out as a link to our sample app for mobilizing SugarCRM called RhoSugar.   You can delete the link to that sample app and provide a link to your own app.

Below the apps directory will be a subdirectory for each application name. For example \Rhosugar might be the subdirectory for an application that provides mobile access to SugarCRM. Beneath the application subdirectory there will be an index.html file that contains links to controllers for specific models, or whatever content the app developer wishes to appear at the top level of the application. This default landing page will typically have links to the controllers for each of the data models. 

There will also be several subdirectories, one for each model or synced data object. For example, there might be subdirectories called \Accounts, \Employees, and \Cases. The subdirectory contains a controller in the file controller.rb. These subdirectories each contain a set of template files as Embedded Ruby (ERB) files. These control how data from the model is displayed and what links are available to other actions. Note that this structure is reminiscent of Rails and MERB's structure, but is a bit simpler by design..

=== Directory Layout 

Specifically the structure of the directories is as follows:

\Rhodes (or whatever you call the directory where you do the git clone)
 index.html (modify this "overall Rhodes index page"  to point to the new app you are building, it ships with a link to our Rhosugar sample app)
 \apps (there will be other directories below Rhodes but this is what we care about)
   index.html  
   \<app_name>  (directory for a single app, for example \RhoSugar)
     index.html (the home page of the app, always generated with links to all synced data models by default, can be edited by user)
     config.rb (configure for the right sync source)
     \<model directory> (for example \Accounts)   
       index.erb
       new.erb
       edit.erb
       controller.rb  
     \<model directory> (for example \Cases)
       index.erb
       new.erb
       edit.erb
       controller.rb 

= Scaffold Generation 

Rhodes features an application generator called rhogen that generates controllers and view for a given model.  The syntax for running Rhogen is:

  rhogen application <appname>

This will generate a config.rb and an index.html file.  Currently config.rb is focused on describing what source to sync with.  Modify the URL that you see in this file with whatever your RhoSync server URL and source ID are for this particular "source" or data model.   It is assumed that you've already set up a RhoSync "source adapter" as described by the RhoSync README.

=== Generate a Model and Associated Controller and Templates

  rhogen model <modelname>

will generate a controller as the file controller.rb and several views as <action-name>.erb (corresponding to the actions below). Each Rhodes model/controller pair has several actions to perform basic CRUD (create, read, update and delete) on the object generated by default by the scaffold . These actions are:

    * index - to list all objects
    * new - to display the editing form for creating a new object
    * edit - to edit the actual object

=== iPhone 

You need to have the iPhone SDK installed and be part of the Apple Developer program.  Rhodes itself is not available in the iPhone App Store. Nor should it be since its not an application but merely a development tool for you to create great iPhone apps (and at the same time run on other smartphones). 

Inside the iPhone directory is an iPhone XCode project.  Load that project (currently called Rhorunner but will be changed to Rhodes later) and do a build.  Once you have tested on your iPhone simular and iPhone devices to your satisfaction, follow Apple's instructions to submit your application for consideration on the App Store.

= More Resources

There is a tutorial available at http://rhomobile.com/wiki/index.php?title=Mobilizing_Your_Application_with_Rhomobile on the Rhomobile site

The Rhodes spec (http://rhomobile.com/wiki/index.php?title=Rhodes) is also available on the Rhomobile wiki: http://rhomobile.com/wiki/index.php?title=Rhomobile

For further questions email us at mailto:info@rhomobile.com

= Known Issues

    * To use rhodes on RIM 4.6 devices, you'll need a micro SD card installed.
    * Sync is not incremental yet, so you'll see a period when the application starts up where there is no data.
    * UI is not consistent between RIM, Windows Mobile and iPhone