Migrating Your RhoMobile App to v5.4

RhoMobile Suite 5.x and higher offers a set of common APIs to access device, system and framework capabilities from your JavaScript and Ruby code.

RhoConnect Client

In RhoMobile Suite 5.4, the RhoConnectClient API is accessed through an extension. To use the RhoConnect Client, you must specify rhoconnect-client in the extensions section of your application’s build.yml (as below). If you are using RhoConnect, you should also consult the RhoConnect Migration Guide for details about migrating your RhoConnect application.

extensions: ["rhoconnect-client"]

Android WebKit

RhoMobile Suite 5.4 uses the stock Android WebKit included with the Android SDK you’re building with as the default. Version 5.x RhoElement APIs will work only with the stock WebKit. However, pre-5.x RhoElement APIs must be used with the Zebra WebKit for Android.

Shared Runtime

RhoMobile Suite 2.0 included the RhoElements Shared Runtime, a pre-built RhoMobile application that provided application configuration options for the Zebra WebKit and RhoElements API extensions. This allowed HTML/JS applications to run without requiring the developer to build a separate a RhoMobile application.

Since the RhoMobile suite 5.4 no longer includes a pre-built shared runtime, it is recommended that you build a simple RhoMobile application to point to your HTML application. This will allow you to optimize the application by including only the extensions and capabilities used by your application.

JavaScript Licensing

RhoMobile Suite 5.4 increases the number of APIs with JavaScript access from prior versions. In addition, JavaScript licensing restrictions associated with some APIs and the Zebra WebKit are removed, and are now in sync with those of Ruby. Licensing restrictions are now at the API class level rather than the language level. For example, use of the Camera API is now free on JavaScript and Ruby. Read more about licensing.

API Platform Support

It is the intention for all APIs to work across all supported platforms. In RhoMobile Suite 2.2, support for platforms was indicated using an API compatibility matrix at the API class level. Version 5.4 contains fewer exceptions, and the platforms that are supported will be indicated at the individual API property or method level. Please refer to the API Summary for an overview.

Replaced APIs

New APIs that have replaced those previously available will be highlighted in the menus and descriptions of the API reference documentation, as below:

System.applicationInstall API Replaces: app_install.

Deprecated APIs

Deprecated APIs will be highlighted as such in menus and descriptions of the API reference documentation. While some deprecated APIs might remain functional, they will no longer be supported or enhanced, as below:

System.hasNetwork Deprecated

The associated description will indicate alternative API(s).

API Migration Table

The following is a summary of new APIs and how previous APIs relate to it.

Class Description Previous RhoMobile Suite 2.2 API
Application Interface with application level methods and properties Rename of RhoApplication and will also contain the MSI specific Application
Barcode Scan bar codes using device's camera, laser or 2d imager Barcode and Scanner have been amalgamated. All decoders have now been brought into the same API rather than having a separate API for each.
Battery Displays a battery signal icon in a native window without requiring users to draw their own icon Previously existed in 2.2 Battery
CardReader Interface for device's Mag Stripe Reader (MSR) Previously existed in 2.2: CardReader
Database Accessing RhoMobile's built in database Same as Database class in 2.2
KeyCapture Allows capturing hardware key events. Previously existed in 2.2: KeyCapture
KeyState Indicator of hardware key state (Shift, Caps, Alt). Previously existed in 2.2: KeyState
Log Interface for Rhomobile logging capabilities Rename of RhoLog as well as combine log settings from RhoElement's Config.xml file
Mediaplayer Playback audio and ringtones. Added functionality to RingtoneManager class
NativeMenubar Defining custom menus for your application. Replaces @menu and @default_menu api
NativeTabbar Provides native UI tabs with multiple webview instances. Similar to previous NativeTabbar class
NativeToolbar Provides a native toolbar UI element. Similar to previous NativeToolbar class
Navbar Native navigation for iOS applications. Similar to previous Navbar class
Network See device's network status or make network connections AsyncHTTP and Network have been amalgamated
Notification Provides visual, audio and tactile alerts to the user. 2.2 APIs: Alert and Notification have been combined
Orm & OrmModel Apis for user defined Data models Previously Rhomobile Data Models were accessible only through the Rhom API via Ruby
Push HTTP based push messaging RhoElemnents Push API
RhoConnectClient Synchronization interface with RhoConnect server applications Rename of SyncEngine
RhoFile Allows access to the device's file system. Mostly the same as the previous File class
ScreenOrientation Allows control or detection of screen orientation behavior. Uses 2.2 ScreenOrientation class and replaces set_screen_rotation_notification
Sensor Allows direct access to device sensors like accelerometer, proximity, light, etc Rename of 2.2 RawSensors class and adds additional functionality.
SignalIndicators Graphical indicator of WiFi strength Previous 2.2 API: Signal
System Control and modify core aspects of the device such as the screen, OS and device capabilities. Amalgamation of System and Generic
Webview Interface with application's Webview container Same as Webview class in 2.2. Also Contains text zoom and page zoom parameters previously found in the Zoom module.

Using 2.2 APIs

Below is a list of API classes available in RhoMobile Suite 2.2 and have not yet have been incorporated in the new Common API class set for RhoMobile Suite 5.4. These APIs are still available in the 2.2 format. The following API classes will be incorporated into furture versions of the RhoMobile Suite so as to supply a common API format for in both JavaScript and Ruby.

When using 2.2 APIs in RhoMobile 5.4, the 2.2 API compatibility matrix still applies.

RhoElements 2.2 APIs

The 2.2 RhoElement APIs are supported on Zebra WebKit only. This WebKit is still available on Windows Mobile/CE and some Android platforms, but the default for 5.4 is the stock Android WebKit.

Rhodes 2.2 APIs

2.2 Rhodes APIs that were not replaced by an equivalent RhoMobile 5.4 API (ex: Camera) are supported on all platforms that were supported previously. Ruby APIs will behave exactly as they did before. Note that some of the Rhodes 2.2 APIs provided JavaScript support, but used a different version of the RhoMobile JavaScript API library: rho_javascript_api.js.

To generate this file, you must enable JavaScript by including rho-javascript in the extensions section of your build.yml file.

extensions: ["rho-javascript"]

To use the JavaScript API, you must add the public/js/rho_javascript_api.js file to the .html, .erb, or .js file that’s calling the JavaScript method. This file is created at build time as part of the application package and can coexist with RhoMobile 5.4 the JavaScript API file rhoapi-modules.js. However, it has been altered from the version built using 2.2, and must be regenerated to allow it to properly coexist with other files of your 5.4 app.

JavaScript ORM

If you’re using the JavaScript ORM API, include this line in any files that will be calling it:

<script type="text/javascript" charset="utf-8" src="/public/api/rhoapi-modules-ORM.js"></script>

Backward Compatibility

RhoElements Meta Tags

Meta tags that are specific to RhoElements should continue to function in a RhoMobile 5.4 application, as long as its build.yml contains the following:

app_type: 'rhoelements'
capabilities: 'motorola_browser'

However, the use of Meta tags is a deprecated feature and will not be supported in future versions of RhoMobile. It is recommended that all Meta tags be converted to use the associated JavaScript capability using the new common API classes.

Deprecated format:

<META HTTP-Equiv="scanner" Content="Enable">

Use instead:


RhoElements JavaScript APIs

JavaScript APIs that are specific to RhoElements should continue to function in a RhoMobile 5.4 application, as long as its build.yml contains the following:

app_type: 'rhoelements'
capabilities: 'motorola_browser'

It is recommended that JavaScript API calls be converted to use the associated JavaScript capability using the new common API classes.

Old format:

scanner.enable()  // should still work

New format:

Rho.Barcode.enable() // the current 5.4 equivalent

Parameter ordering

In a few rare cases, an API in version 2.2 has the same naming as in 5.4, but the ordering of parameters may have changed. For example:

# In RhoMobile 2.2 Params are callback, paramHash
# This will fail in a 5.4 application
Rho::Barcode.enable(url_for(:action => :barcode_callback), {:camera => 'front'})

# In RhoMobile 5.4 Params are now paramHash, callback
Rho::Barcode.enable( {:camera => 'front'},url_for(:action => :barcode_callback))

In all new 5.4 API classes, callbacks are now specified as the last parameter.

The benefit of converting these APIs to the current 5.4 methods includes support for additional combinations of supported operating systems and platforms. There also are several new ways of accessing these APIs through instance objects and special common methods that were not implemented previously.

API behavior on Page change

In version 2.2, some APIs by default will reset the device they control when navigating between app pages. In 5.4, the devices are not reset between page navigations, but is left in the previous state. Therefore, it will be up to the application to control behavior on page load.

For example, if a 2.2 application activates the barcode scanner on Page1 with a callbackhandler, navigating to a page with no scanner will disable it. Depending on the desired behavior, an equivalent 5.4 app must handle the setting or disabling of the scanner on page load.

Removed APIs

The following APIs are no longer included in the RhoMobile Suite:

Back to Top