To enable your web app for RhoElements, perform these steps.
In order for RhoElements to start with your web app, you need to configure RhoElements so that it knows which URL to start with. This can be accomplished in multiple ways.
If you do not plan on building native apps, then you do not need to install any of the prerequisites, such as other mobile development platforms or the Java Development Kit. However, to obtain the individual mobile platform RhoElements runtimes for your web app, you must minimally install RhoMobile Suite.
After you install Zebra RhoMobile Suite, you will have access to a set of executables — the RhoElements runtimes — for Windows Mobile, Windows CE and Android. You will need to install the RhoElements Runtime on each device that will be used for your application.
On Windows Mobile/CE devices, install the RhoElements Runtime.cab to \Program Files\RhoElements using ActiveSync or Windows Mobile Device Center. On Android, install the RhoElements Runtime.apk using the Android SDK.
Once installed, you will have access to the RhoElements config.xml file.
When installing a newer version of the runtime on Windows the existing config.xml will be overwritten with the default one. You should redeploy your customized config.xml along with an upgrade of the runtime. On Android, the config.xml is not overwritten on upgrades of the runtime.
This section will take you step by step through creating your first web-based scanning application for your Zebra mobile device using RhoElements. The tutorial is based on the ubiquitous “Hello World” application but instead of simply displaying this message, it will enable the scanner on the mobile device and display a message when a barcode is decoded. Once you have completed this tutorial you should be familiar with the RhoElements language “EMML” and how this applies to the other features of RhoElements such as the Signature Capture or Gesture modules.
1) Using your favorite text editor, create a blank text document and save it as HelloScan.html.
2) Create the basic framework of a web page as shown below adding an <html>, <head>, <title> and <body> section.
|Although RhoElements does not have a title bar due to it providing you with the maximum screen real estate for your application, the title will appear in any dialog boxes (alerts, etc.) that are displayed.|
<html> <head> <title>Hello Scan</title> </head> <body> </body> </html>
3) Now add some text to the <body> section so that we can see something on the screen when we start Hello Scan.
<html> <head> <title>Hello Scan</title> </head> <body> <b><h2>This is my first RhoElements application!</h2></b> <b><p>Please scan a barcode...</p></b> </body> </html>
When this tag is parsed, two actions will be performed: firstly, the decode event will be setup to call the doScanDecode function, and then the scanner will be enabled. The parameters and their values and methods are written as they would be in CSS, with parameters and values separated by a colon “:” and pairs separated by semi-colons “;”. When setting up the decode event, you will see that we have chosen to retrieve the parameters vis JSON object.
The Retrieval Events help section explains how to specify the returned parameters to be sequential or returned as a JSON object.
In the decode event, you will see that we retrieve from the JSON object the parameters for the data decoded, the source of the code, and the event type. If you take a look at the scanner section of the help file, you will see the parameters listed.
Your first application is now complete. For the purpose of this tutorial, we will copy the file to the device; however, if you have a web server at hand and you have configured the device to communicate on the network, you could equally view the page from there.
This section assumes you have created your application on a Zebra Windows Mobile or CE device; you can create on an Android device also.
|If you are using a localized variant of the operating system, you may need to edit the default config.xml and plugin.xml shipped with RhoElements to account for the localized folder names on the system, e.g. The Italian build of the OS uses \Programmi\ rather than \Program Files\.|
It is recommended that you get familiar with the Configuration Parameters in the configuration file config.xml, both for developing/debugging as well as deployment.
The location of the configuration file loaded by RhoElements is dependent on the mobile device.
If you wish to keep all default parameters and just change the starting url, then it is recommended that you simply create a shortcut as described below.
If you wish to modify other parameters in the config.xml, you should replace the config.xml file after the RhoElements Runtime is installed. Locate the config.xml file, copy it to your desktop for modification, and then you can use this file along with your distribution of the RhoElements Runtime. This file will need to be overwritten after the installation of the runtime.
You can create a shortcut file to have the RhoElements Runtime launch with your web app.
You can setup Windows Mobile shortcut files to launch the RhoElements runtime with different startup options that will override the default settings. You set these parameters in a shortcut (.lnk) file for Windows Mobile/CE; you must create this shortcut file. You can use a text editor such as Notepad on Windows CE, or use the File menu in Platform Builder (New Project or File, Text File type). Edit the file for command line parameters and save it to \Windows\Start Menu. This will put the shortcut at the top level in your Start Menu.
The RhoElements runtime installation path on Windows CE/Mobile devices is
\Program Files\RhoElements and the path to the executable is
The shortcut file supports the following command line parameters.
/C: specifies the location of the configuration file for the RhoElements v1.0 application. This will override all default configuration settings. If the full file name contains spaces, surround URL with single or double quotes, e.g.:
/C:file://\application\config.xml /C:'file://\Program Files\application\Config.xml' /C:"file://\Program Files\My Application\config.xml"
/S: specifies the start page of the RhoElements v1.0 application. Other configuration parameters will be used from the default config.xml file. If the full file name contains spaces, surround URL with single or double quotes, e.g.:
/S:file://\HTML\index.html /S:'file://\RE App\index.html' /S:"file://\Program Files\MyApp\index.html" /S:http://www.motorola.com
If neither the
/C parameters are specified in the shortcut file, then the default values for the location of the configuration file and the start page of the RhoElements application will be used.
|Urls that contain query string parameters (?name=value) can not be used within a shortcut on Windows Mobile / CE. This is a limitation on Windows Mobile/CE for creating shortcuts.|
The format in the .lnk file is:
<line-length>#<runtime-exe> <command-line-parameter> <app-folder>
For example, this code in the .lnk file will change the startup page to be a local HTML file.
70#"\Program Files\Rhoelements\rhoelements.exe" /S:file://\helloscan.html
The Zebra Technologies Enterprise Tablet (ET1) has been customized so that android shortcuts can be created very easily. Once RhoElements is installed on the ET1:
The shortcut will be placed on the ET1 home screen. At this time there is no way to provision an ET1 with this shortcut file, as you can with Windows Mobile.
If you have multiple web apps that you would like to point RhoElements Runtime to, you can create multiple shortcuts as described above. FOr example, one startup file could be:
68#\Program Files\Rhoelements\rhoelements.exe /S:file://\helloscan.html
And another could be:
66#\Program Files\Rhoelements\rhoelements.exe /S:file://\helloscan.html
|The last application will launch using the same runtime container. Only one application will be running at a time. When launching the second application the runtime simply changes the starting URL.|
The RhoElements Runtime is a prebuilt Rhodes application that launches in full screen mode and loads the configuration parameters as described above. If you would like to modify the behavior of the RhoElements runtime, such as change the startup screen or icon, then load the Rhodes project from which you can build a RhoElements Runtime into RhoStudio.
The RhoElements Runtime is only available for Zebra Technologies devices.
On the command line on your Windows PC, navigate to this folder:
<RhoMobile Suite Install Folder>\Rhoelements2
To build, run this command.
cab file can be found at
<RhoMobile Suite Install Folder>\RhoElements2\bin\target\<platform_id>\RhoElements2.cab.
On the Macintosh, the RhoElements Runtime project is located in the Zebra RhoMobile Suite Installer for Mac, in the RhoElements2 folder.
Copy the RhoElements2 project folder to your Macintosh at a location where you can run your RhoElements/Ruby rake commands. One way you can do this is to import this project into RhoStudio.
To build for Android, run this command from the RhoElements2 directory on your Windows PC (
<RhoMobile Suite Install Folder>\RhoElements2) or the location where you imported the RhoElements2 project from the RhoMobile Suite Installer for Mac.
apk file can be found in the RhoElements2 project
\bin\target folder, such as at
<RhoMobile Suite Install Folder>\RhoElements2\bin\target\RhoElements2.apk.
To install your customized Runtime application on your specific device, go to the build instructions for your platform and use the instructions to deploy an application on your device.
|The runtime application must be installed to the primary disk partition on the Windows CE/Mobile device, i.e. it has to be installed to `\Program Files\RhoElements2` only.|
On Windows Mobile, the
Device option must be selected when the installer asks for the location to install.
On Windows CE, the default path (
\Program Files\RhoElements) must be selected.
The RhoElements WebApp (hybrid) application log file is configured in the configuration file Config.xml.
The location of the log file of a RhoElements WebApp (hybrid) application is defined by the following rules (in the order of priority):
Value attribute of
LogProtocol tag in the configuration file equals “FILE” or “HTTP”, then the path to the log file is taken from the
LogURItag is ignored and
rholog.txtis used as a file name.
LogURItag is used.
LogPorttags via POST HTTP-requests.
If the start page parameter is a local file, then this file folder is used to store the log file.
The file name part of the start page parameter is ignored and
rholog.txt is used as the file name.
This rule is not applied to Android.
Otherwise the log file has the name
rholog.txt and is placed at this location:
rhofolder of the Runtime installation folder.
rhodatafolder of the Runtime installation folder (accessible at emulator or rooted device only).
By default the local web server is switched off, you will need to manually enable and configure the server using the RhoElements configuration file. See the Configuration Settings help page for the server options, specifically those under the <WebServer> hierarchy.
This option is only available for Windows Mobile/CE. As an alternative you should consider building a native application. RhoElements native applications have a built in web server that runs on all platforms. The HTML files could be placed in the /public folder of the native application folder and the application would use the Webview API to load the initial starting html page.
Using the following example configuration:
Navigating to file://\myWeb\index.htm will load the page from the file system.
Navigating to http://localhost:8080/index.htm will load the same page via the local web server.
To uninstall RhoElements on the Windows Mobile device:
Any user generated files and folders and any log files in the \Program Files\RhoElements directory will not be deleted.
By completing this tutorial you will now be familiar with EMML and having realized how simple it is to produce applications using RhoElements for Zebra mobile devices.
Here are a few points to remember or consider when designing and writing your application:
When writing your RhoElements application, be sure to avoid the following common mistakes: