Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

MapView API

Provides an embeddable map interface. See GeoLocation/controller.rb of System API sample application for some examples of using the MapView class.

There are several settings you should know when you use the MapView API, such as setting . Refer to the MapView settings in Device Capabilities.

Using JavaScript API

You can call the MapView methods from JavaScript as well as Ruby. 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.

The JavaScript API methods with a return value can pass it as a parameter in jQuery-compatible continuation (deferred object, a kind of callback). Possible continuations to handle are done, fail, and complete.

Rho.Class.method(params).done(function(handler) { /* handler... */ })

You must enable JavaScript by putting rho-javascript into extensions in your build.yml.

extensions: ["rho-javascript"]

You must have a RhoElements license to use the JavaScript API.

create

Create a map on your device. Click here for an example of MapView create.

Ruby syntax:

MapView.create map_params

JavaScript syntax:

Rho.MapView.create(map_params)

map_params hash

Click here for an example of MapView create, which sets the map_params hash.

map_params is a hash consisting of:

provider 'Google' supported on iPhone, Android and BB. 'ESRI' supported on iPhone, Android, BB and WM. 'RhoGoogle' supported on Android and WM, Rho's own GoogleMap provider based on Google Static Map API, has additional features (offline caching, for example). 'OSM' - Open Street Map - supported on Android and WM, supports only "roadmap" map type.
settings A hash that provides map settings. See table below.
annotations Array of map annotation objects (list of pins on the map). See table below.

To use ESRI maps in your projects on iPhone:

  • Install ESRI iOS SDK – use default folders during installations !
  • Add “esri” to your applications extensions list in build.yml file.

annotations array (in map_params hash)

The annotations parameter within the map_params hash is an array. Click here for an example of MapView create, which sets this array.

The annotations array has the following format.

latitude,longitude map coordinate of the annotation
street_address if map coordinate is not specified, framework will attempt to obtain it using provided street address from google geo-coding service
title title of the annotation callout
subtitle subtitle of the annotation callout
url url to follow when user clicks on the callout button

settings hash (in map_params hash)

The settings parameter within the map_params hash is also a hash. Click here for an example of MapView create, which sets this hash.

The settings hash has the following format.

map_type Display "standard", "satellite", or "hybrid". You can use "roadmap" in place of "standard".
region two types allowed: [latitude,longitude,latitudeDelta,longitudeDelta] or {:center => center, :radius => radius}.
zoom_enabled true to enable zoom of the map
scroll_enabled true to enable scroll of the map
shows_user_location true to display current user location on the map
api_key Maps JavaScript API Key (sign up for it here). (Ignored in Android).

api_key is ignored in Android; get another key and specify it in the app’s build.yml as described here.

region (in settings hash)

In the settings hash (settings ia a parameter within the map_params hash), the region can be of two types: [latitude,longitude,latitudeDelta,longitudeDelta] or {:center => center, :radius => radius}.

region type [latitude,longitude,latitudeDelta,longitudeDelta]

Click here for an example of MapView create, which sets this region type.

latitude,longitude the map coordinate of the region center.
latitudeDelta Degrees of north-to-south distance. One degree of latitude is approximately 111 kilometers (69 miles).
longitudeDelta Degrees of east-to-west distance. One degree of longitude is approximately 111 kilometers (69 miles) at the equator, and 0 kilometers at the poles.

region type {:center => center, :radius => radius}

center string describing center of area that is allowed by google geocoding service. Examples: “1 infinite loop, cupertino, ca 95014”, “California, USA”, “37.365519,-121.982918”
radius radius of displayed area measured in degrees

set_file_caching_enable

Enable file caching for map tiles. The file cache can be used for offline map browsing.

Caching saves map tiles to your device. It increases performance of map view: when the device user scrolls map view to an already viewed map area, the device does not have to reload the map tiles. Tiles take up memory, so the developer should decide when to use caching.

Ruby syntax:

MapView.set_file_caching_enable(enable)

JavaScript syntax:

Rho.MapView.set_file_caching_enable(enable)
enable 1: enable file caching. 0: do not enable file caching.

preload_map_tiles

Preload a map tiles for a region defined by a zoom level range (0<=zoom<=18). This function requires some understanding about map engine funtionality, such as map tiles.

Click here for an example of MapView preload_map_tiles.

When the map view is opened after preload_map_tiles is called, the preloaded area can display more quickly because the only map tiles displayed are in the defined zoom range.

Ruby syntax:

MapView.preload_map_tiles(options_hash, url_for(:action => :preload_callback))

JavaScript Syntax:

Rho.MapView.preload_map_tiles(options_hash, callback)

Returns the total number of tiles for this preload. You can use this total to calculate the required space, predict the required time, etc.

options_hash A hash containing parameters.

options_hash

options_hash is a hash containing the following parameters for preload_map_tiles.

engine 'Google' supported on iPhone, Android and BB. 'ESRI' supported on iPhone, Android, BB and WM. 'RhoGoogle' supported on Android and WM, Rho's own GoogleMap provider based on Google Static Map API, has additional features (offline caching, for example). 'OSM' - Open Street Map - supported on Android and WM, supports only "roadmap" map type.
map_type Display "standard", "satellite", or "hybrid". You can use "roadmap" in place of "standard".
:top_latitude the top latitude of the map region
:left_longitude the left longitude of the map region
:bottom_latitude the bottom latitude of the map region
:right_longitude the right longitude of the map region
:min_zoom the minimum zoom the user can do to the map region. 0 to 18. A larger min_zoom (and max_zoom) means you can see more map tiles. Each next larger zoom level requires 4 times more tiles for the same map region.
:max_zoom the maximum zoom the user can do to the map region. 0 to 18.

preload_callback

The preloading process can take a long time. Write the preload_callback method to get periodic information about the process, using the parameters “status” and “progress”.

status "DONE" when the preloading process is complete.
progress the current preloading progress as a percentage (0..100).
Back to Top