RhoMobile Suite 4.0 and up offers a set of common API’s to access device,system and framework capabilities across JavaScript and Ruby.
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"]
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.
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.
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.
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.
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
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
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. |
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.
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.
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.
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>
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();
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
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.
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.
The following API’s have been removed from Rhomobile 4.0