• Introduction
  • Dev Environment Setup
  • Developing Apps
  • Data Handling
  • Device Capabilities
  • Testing & Debugging
  • Extending
Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Migrating your RhoMobile application to 4.X

RhoMobile Suite 4.0 and up offers a set of common API’s to access device,system and framework capabilities across JavaScript and Ruby.

RhoConnect Client

In RhoMobile Suite 4.0 and up, the RhoConnect Client is available via an extension. In order to use the RhoConnect Client, you must specify rhoconnect-client in your applications build.yml extensions section. 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

In RhoMobile Suite 4.0 and up, the default webview used for Android is now the stock Android webkit that is included with the Andoid SDK version that you are building with. 4.0 RhoElement API’s will only work using the stock webkit. RhoElement API’s that have not yet moved to version 4.0, however will only work on the Zebra Webkit for Android.

Shared Runtime

In RhoMobile Suite 2.0, there was a RhoElements Shared Runtime that was included with the installation. This application was a pre-built RhoMobile application that included application configuration options including the Zebra Webkit and RhoElements API extensions. The intention of this runtime was to allow HTML/JS applications to run without having to compile and build a RhoMobile application. Although the RhoMobile Suite 4.0 installation includes a pre-built shared runtime for Windows Mobile and Windows CE 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

In RhoMobile Suite 4.0 and up, more API’s have JavaScript access that did not have this interface before. In addition some API’s previously had licensing restrictions on JavaScript (due to the fact of the API only being supported in Zebra Webkit) but not necessarily on ruby. In 4.0 and up, the licensing restrictions are at the API class level not the language level. So for example the use of the Camera API is now free to use on JavaScript or Ruby. Read more about licensing.

API Platform Support

It is the intention for all API’s to work across the supported platforms. Previously in RhoMobile Suite 2.2, support for platforms were indicated using an API compatibility matrix at the API class level. In 4.0 there are less exceptions and the platforms that are supported will be indicated at the individual API property or method level. See the API Summary for an overview.

Replaced APIs

In the API reference documentation, new APIs that have replaced previously available API’s will be highlighted in the menu as well as the description.

For example System.applicationInstall

Replaces:app_install

Deprecated APIs

In the API reference documentation, API’s that have been marked as deprecated will be highlighted in the menu and description. Deprecated means that the API should work, but will no longer be enhanced or supported. The associated description should indicate alternatives.

For example System.hasNetwork

Deprecated

API Migration Table

The following shows you a summary of these new API’s and how any previous API relates 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 Api's 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 API’s

Some API classes that may have been available in RhoMobile Suite 2.2 and have not yet have been incorporated in the new Common API class set for RhoMobile Suite 4.0. However these APIs are still available in the 2.2 format. The following API classes will soon be incorporated in furture versions of RhoMobile Suite 4.x in order to supply both a Common API format in both JavaScript and Ruby.

When using 2.2 API’s in RhoMobile 4.0, the 2.2 API compatibility matrix still applies.

RhoElements 2.2 APIs

The 2.2 RhoElement APIS are only supported on Zebra Webkit. This webkit is still available on Windows Mobile/CE and Android platforms, however on Android the default webkit that is used is the stock Android Webkit.

Rhodes 2.2 APIs

2.2 Rhodes APIs that were not replaced by an equivalent RhoMobile 4.0 API (ex: Camera) are supported on all platforms that were supported previously. Ruby API’s will behave exactly as they did before. Note that some of the Rhodes 2.2 API’s 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 putting rho-javascript into extensions in your build.yml.

extensions: ["rho-javascript"]

And then to use the JavaScript API, add the public/js/rho_javascript_api.js file – created at build time as part of the application package – to the .html, .erb, or .js file calling the JavaScript method. This file can coexist with RhoMobile 4.0 JavaScript API file: rhoapi-modules.js however it has been altered from the version that was built using 2.2. You must re-generate the rho_javascript_api.js file to properly coexist.

JavaScript ORM

If you are going to be using the JS ORM API, you’ll also need to include this line in any files that will be using it:

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

Backwards Compatibility Notes

RhoElements Meta Tags

RhoElement specific Meta tags should still function in a RhoMobile 4.0 application that has :::yaml app_type: ‘rhoelements’ capabilities: ‘motorola_browser’ in its build.yml 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.

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

Use instead: :::javascript Rho.Barcode.enable();

RhoElements JavaScript APIs

RhoElement specific JavaScript APIs should still function in a RhoMobile 4.0 application that has :::yaml app_type: ‘rhoelements’ capabilities: ‘motorola_browser’ in its build.yml. It is recommended that JS API calls should be converted to use the associated JavaScript capability using the new common API classes.

scanner.enable()  // should still work

Rho.Barcode.enable() // is the current 4.0 equivalent

Parameter ordering

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

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

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

Callbacks are now specified as the last parameter in all new 4.0 API classes.

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

API behavior on Page change

In version 2.2 APIs like Scanner would reset when you navigated between pages however, in 4.0 the APIs are not reset between page navigations, therefore if you have an application say with Page1 enabling barcode scanner with a callbackhandler, and then you navigate to page2 (no barcode scanner) - you should handle setting or disabling the barcode depending on the desired behavior. In 2.2 the barcode would have been disabled upon navigating to Page 2. In 4.0, the scanner is left in the previous state and it will be up to the application to control behavior on page load.

Removed APIs

The following API’s have been removed from Rhomobile 4.0

Back to Top