Runtime Application Configuration

Apart from your source code, there are other important files that control how your application behaves at runtime: rhoconfig.txt and Config.xml

• rhoconfig.txt
• Config.xml
• Config.xml File Format
• Configuration settings and values
• Substitution Variables
• Remarks

rhoconfig.txt

What it affects

The values in rhoconfig.txt control different aspects of your application, such as what page is loaded when the application starts or the address of the RhoConnect synchronization server, while those in Config.xml refer to features of the RhoElements runtime itself like what keys can be intercepted by the application or whether to pre-load modules on startup.

Apart from the settings recognized by the platform, you can add arbitrary values that are specific to your application:

# application-specific value
foo = 'bar'

All values will be accessible at runtime via Rho::RhoConfig

foo = Rho::RhoConfig.foo
start_path = Rho::RhoConfig.start_path

You can also check if a configuration property actually exists before accessing it

start_path_exists = Rho::RhoConfig.exists?("start_path") # will return true

The rhoconfig.txt file generated with a new application contains the following default values, as well as descriptions of each setting:

# startup page for your application
start_path = '/app'

# path to the options page (in this case handled by JavaScript)
options_path = '/app/Settings'

# location of bundle url (i.e. from rhohub.com); used by desktop win32 simulator
rhobundle_zip_url = ''

# optional password to access bundle (usually not required); used by desktop win32 simulator
rhobundle_zip_pwd = nil

# Rhodes log properties
# log level
# 0-trace, 1-info(app level), 2-warnings, 3-errors
# for production set to 3
MinSeverity  = 1

# enable copy log messages to standard output, useful for debugging
LogToOutput = 1

# '*' means all categories, otherwise list them : Cat1, Cat2
LogCategories = *

# what categories to exclude
ExcludeLogCategories =

# max log file size in Bytes, set 0 to unlimited size; when limit is reached, log wraps to beginning of file
MaxLogFileSize=50000

# turn on local http server traces, off by default
#net_trace = 0

# timeout of network requests in seconds (30 by default)
#net_timeout = 60

# where log will be posted by RhoConf.send_log or from the log menu
# source is also open and up on http://github.com/rhomobile/rhologs, so you can deploy your own logserver
logserver = 'http://rhologs.heroku.com'

# log file prefix - contain human-readable text
logname='rhodes-app'

# Keep track of the last visited page
KeepTrackOfLastVisitedPage = 0
LastVisitedPage = ''

# sync server url, typically this will look like 'http://<hostname>:<port>/application'
# for example: 'http://localhost:9292/application'
syncserver = ''

# 0 will disable auto sync
sync_poll_interval=0

# geo location inactivity timeout (in seconds)
#geo_location_inactivity_timeout = 30

# open rhodes app in full screen mode
# default 1 for Android up to Rhodes 2.2.5.
# on all other platforms and on Android from Rhodes > 2.2.5 default 0
full_screen = 0

# show top menu on Windows desktop in full screen mode (default is 0=don't show top menu)
#w32_fullscreen_menu = 1

# disable the Android page loading progress bar
disable_loading_indication = 1

# Port of the local (embedded) HTTP server. This parameter is mainly for debug purposes.
# If not specified, application will use dynamically selected one.
# WARNING!!! Remove this parameter before put application to production.
#local_server_port = 8080

# show status bar on windows mobile. default 1
#wm_show_statusbar = 1

# disable screen rotation (enabled by default) - disable possible for ANDROID and iPhone ONLY
#disable_screen_rotation = 1

# disable close app when pressing back on home screen on blackberry
#bb_disable_closebyback = 0

# load images in background, this improve reaction speed on user actions, 0 by default
#bb_loadimages_async = 0

# set to 0 to reset the bulksync_state and trigger a bulk sync the next time rhodes synchronizes
#bulksync_state = 1

# hides forward button and animates back button transition
jqtouch_mode=1

splash_screen='zoom'

use_bb_full_browser=6

esri_map_url_roadmap: type: string

ESRI server url with roads map tiles.
    iOS             - supported in esri extension.
    Android      - supported with ESRI map type.
    WM             - supported with WM mapview.
    WP8           - mapping is not supported.

esri_map_url_satellite: type: string
    ESRI server url with satellite map tiles.
        iOS             - supported in esri extension.
        Android      - supported with ESRI map type.
        WM             - supported with WM mapview.
        WP8           - mapping is not supported.

OSM_map_url_roadmap: type: string
    OSM server url with road map tiles.
        iOS            - not supported as only Google and ESRI maps are supported.
        Android     - supported with OSM map type.
        WM             - supported with WM mapview.
        WP8           - mapping is not supported.

disable_loading_indication:type - Bool
    If enabled, blocks loading indication in webview
        Supported only on Android.

Additional parameters that can be used in rhoconfig.txt

# Address and port of proxy server. This settings uses Network module.
http_proxy_host = 'server'
http_proxy_port = port

# Login and password for access to proxy server. Only basic authentication is supported
http_proxy_login    = 'user'
http_proxy_password = 'password'

# CLient SSL Configuration. The path to the p12 formatted certificate file and the password used with the client certificate.
# The path to the p12 formatted certificate file used for client SSL authentication. This setting is used in any Network API calls which setting up secured SSL
# connections requiring client authentication (get, post, downloadFile, uploadFile). This setting only takes effect if `verifyPeerCertificate` is enabled.
# Therefore, if `verifyPeerCertificate` is set to fail and remote server requests the client certificate, connection fill fail.
# These two settings are only supported for use on Android devices.
clientSSLCertificate         = 'certificate path'
clientSSLCertificatePassword = 'password'

Config.xml

What it affects

Note: The Config.xml effects applications that are using Zebra Webkit. However the setting CAFile in this file will be used for 4.0 applications using the stock browser.

Runtime configuration of RhoElements is managed through an XML file called Config.xml. This file is mandatory for proper RhoElements execution: not every setting has a default and if the configuration file cannot be found, RhoElements will not start. An example configuration file is provided as part of the installation and contains sensible defaults, this page explains the meanings of each of the settings and their possible values. The example Config.xml file is bundled with the rhoelements gem; its location depends on the operating system:

• Windows: <RhoMobile Suite installation directory>\ruby\lib\ruby\gems\1.9.1\gems\rhoelements-4.0.0\libs\data\Config\Config.xml

• OS X: ~/.rvm/gems/ruby-1.9.3-p392/gems/rhoelements-4.0.0/libs/data/Config/Config.xml

Configuration File Location in a mobile device

The location of the configuration file loaded by RhoElements is dependant on a number of factors:

• When running on the Enterprise Tablet the configuration file is read from /Android/data/com.motorolasolutions.rhoelements/Config.xml.
• When running on all other devices RhoElements will attempt to launch the configuration file Config.xml located in the folder Config off the installation root.
• You can change which configuration file is loaded using the /C: configuration option

For persistant installations, on cold boot the Config.xml file is copied from \Application\RhoElements\Config\Config.xml to \Program Files\RhoElements\Config\Config.xml; bear this in mind if you want your configuration to persist across cold boot. This behavior may be modified by changing \Application\RhoElements.cpy.

Config.xml File Format

The following is an example of a typical configuration file :::xml

Configuration settings and values

Note: The following settings effects applications that are using Zebra Webkit. However the setting CAFile in this file will be used for 4.0 native applications using the stock browser

Note: Fullscreen Mode is currently unavailable for the iOS7 SDK. For details and other differences, see the Differences in iOS7 section in the Build for iOS doc.

* The configuration identifiers are used in the ReadConfigSetting and Write Config Setting methods of Generic

Substitution Variables

The following substitution variables are available in the configuration file

Remarks

†Case Sensitivity

The operating systems of some devices have case sensitive file systems. Therefore it is good practice to always keep URL values in the Config.xml file case identical to the names of the actual files.

*Page Zoom Configuration

Sometimes, while navigating from any page to any other page, the actual page zoom setting reflects after few milli seconds delay. This doesn’t happens everytime.

Setting page zoom property on page load event does not reflect the set value for the Application start page for the first time. Users are advised to set the page zoom property with a minimum of 1 second delay on page load.

Setting page zoom property on page load will reflect only for that page.

*Battery Polling on the Enterprise Tablet

On the Enterprise Tablet the battery notification is asynchronous. For this reason, BatteryRefresh is not supported on the Enterprise Tablet. The effect of this is that a batteryEvent is fired only when the battery level changes. This has been done to save battery power compared to polling.

Interaction between FunctionKeysCapturable and EnableFunctionKey configuration settings

On Windows Mobile and Windows CE devices full control is given to the developer over how their application handles function keys. Because of the limitations of the operating system any settings applied will persist until the device is next warm booted. Which function keys have default operating system behavior will vary from device to device, e.g. on the MC75a F3 and F4 represent the red and green phone keys and on many devices the volume keys are also mapped as Function keys. Not all function keys will have default operating system behavior.

Unblocking function keys may expose the underlying operating system, particularly the red and green phone keys will give access to the start menu and programs.

The table below shows the behavior of RhoElements when Function Keys are pressed given the possible configuration settings:

HTTP Authentication Limitations

On Windows Mobile and Windows CE, using the Webkit, we only support the “Basic” and “Digest” forms of the Authenticate header as described in This article. This means that whenever using WM or WinCE, you’ll need to pass the username and password over the network as clear-text. Keep this in mind when thinking about your app’s security on these platforms.