Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

Creating a RhoMobile Project

A RhoMobile project can be created from within RhoStudio or from the command line. Under the hood, RhoStudio invokes the command-line tool anyway, so the approaches are equivalent; both apply the Rhodes open-source framework for building cross-platform apps.

This tutorial assumes that the RhoMobile Suite and its related components are already installed on your development machine. If that’s not the case, please refer to RhoMobile Suite installation instructions before beginning this tutorial.

Creating a new project…
Project structure
Running your application…
Related reading

Creating a new project…

…with RhoStudio

To create your first Rhodes project using RhoStudio:

Open RhoStudio using the appropriate launch script for your development host.
Select File > New > Project. The New Project window will open.
Select ‘RhoMobile application’ from wizard list.
Click Next.

On the next screen, enter a name for your new project. In the example below, we use “storemanager.”
Notice that ‘Create application in default workspace’ is checked.
To save the app in different location, uncheck and Browse to the new location.
Click “Finish” when done.

…from the command line

If you prefer to use the command line or a development environment other than RhoStudio, the Rhodes framework can be invoked manually using the commands and parameters below:

Usage: rhodes generator_name [options] [args]

Generate rhodes application

Available generators
    api                              Generate API sources from XML API file
    api_test                         Generate megatest XML for API generator
    app                              Generates a new rhodes application.
    extension                        Adds native extension to Rhodes based application.
    model                            Generates a new model for a rhodes application.
    spec                             Adds spec framework to rhodes application.

General options:
    -p, --pretend                    Run, but do not make any changes.
    -f, --force                      Overwrite files that already exist.
    -s, --skip                       Skip files that already exist.
    -d, --delete                     Delete files that have previously been generated with this generator.
    --no-color                       Don't colorize the output
    -h, --help                       Show this message
    --debug                          Do not catch errors
    --rhoconnect                     Include rhoconnect-client in the application

For example, to create an application called ‘storemanager,’ do the following:

Open a terminal window
Switch to the directory in which the app is to be saved
Execute the command:

:::term $ rhodes app storemanager

Project structure

The generated application has the following structure:

Here is an overview of the contents of each file and folder.

/app (folder)

/app
This root-level folder contains all the Ruby code for your application and its views. For newly-created applications there are two other folders inside:

/app/helpers
Contains view helpers, which are used to extract common functionality into reusable functions. Rhodes generates application_helper.rb and browser_helper.rb automatically; you can add your own helper files as needed.

/app/Settings
Default controller file that’s invoked when the user taps the “Settings” icon in the application. The Settings panel displays status of the data sync process, allows sync-server login/logout, and permits maintenance tasks such as clearing the database.

Other files in the /app folder:

application.rb
The entry point of your application. Any code that you want to run at startup should be placed here.

index.erb
The first image displayed when the application starts up (unless you change it in the build.yml file).

layout.erb
Contains elements present on all or most pages. Because most pages of an application typically have a similar structure and layout, it is recommended that you include elements common to most pages in a single file to ease maintenance. Rhodes acknowledges this best practice and provides you with a default template to minimize duplicate HTML code among your pages (views). Each page should contain only the code specific to that view, which is merged with the layout when the page is rendered.

loading*.png
Splashscreen images for several device orientations and platforms. You will swap these files with your own at some point before deployment.

build.yml
Controls compile-time settings such as the name of the application, the extensions to include, version of the Rhodes SDK to use for compiling, etc.

rhoconfig.txt
Controls runtime settings, such as the app startup page, URL of the synchronization server, how much logging output to retain, etc.

Rakefile
Standard Ruby rakefile designed to find the appropriate Rhodes SDK and use it to compile your application.

models / controllers - when you add a data model to your application, each model will be created in its own folder within /app. For example, a model called ‘Product’ will produce a folder called /app/Product.

/framework

Do not modify any files in this folder unless you are contributing to Rhodes. This is a link to the implementation of the Rhodes framework that RhoStudio shows for reference. The framework folder does not exist within your application.

/icon

Contains your app’s icon files in formats as required for each platform (Android, iOS, Windows Mobile/CE, etc.) that you plan to target.

/public

Any file linked from a view (or that must be reachable by the embedded web browser for any reason) belongs here. Rhodes organizes the files it generates in several sub-directories:

/public/css
Holds the stylesheets for your app’s pages.

/public/images
Image files for toolbars, lists, ‘OK’ and ‘Back’ buttons, etc.

/public/jquery
Files for JQuery, a cross-browser JavaScript library for manipulating HTML with an easy-to-use syntax.

/public/js
All JavaScript code specific to your app should be stored in this folder.

While you can create additional folders and organize your files any way you like, it is recommended that you stay as close to the default as possible to ease support and simplify team development.

Running your application…

…from RhoStudio

To start your application for the first time:

Open the RhoStudio Project Explorer window
Right-click on your project name
Select Run As > Run Configurations…
Select “RhoMobile Application” and click the “New” button
Click “Run”

RhoStudio will compile and launch your app in RhoSimulator.

…from the command line

To start a Rhodes application from the command line, switch to the folder that contains the application and execute the following command:

rake run:<platform to be simulated>:rhosimulator

where <platform to be simulated> can be:

android
iphone
win32 (for Windows desktop)
wm (for Windows Mobile 6)
uwp (for Windows 10 (UWP))

Due to memory limitations, RhoSimulator does not support Windows Mobile/CE apps.

The application will start inside RhoSimulator with a different look depending on the selected platform.

Creating a RhoMobile Project

Creating a new project…

…with RhoStudio

…from the command line

Project structure

/app (folder)

/framework

/icon

/public

Running your application…

…from RhoStudio

…from the command line

Related reading