# Modules.Map
Add-on Map module
# Overview
# Requirements
- Google Maps API key (required for both development and production)
- Google Play services SDK installed using the Android SDK manager
- This module only works on Android devices. This module is not supported on the Android emulator
# Getting Started
Edit the
modules
section of your tiapp.xml file to include this module:<ti:app> <modules> <!-- Add this line to your modules section --> <module platform="android">ti.map</module> </modules> </ti:app>
Obtain a Google Maps API key. For instructions, refer to the "Obtain and Add a Google API Key" section in the Google Maps v2 for Android guide (opens new window).
Add the following
meta-tag
element to the Android manifest section of the tiapp.xml file. You may need to add themanifest
andapplication
elements.<ti:app> <android xmlns:android="http://schemas.android.com/apk/res/android"> <manifest> <application> <!-- Replace "YOUR_API_KEY" with the Google API key you obtained --> <meta-data android:name="com.google.android.geo.API_KEY" android:value="YOUR_API_KEY" /> </application> </manifest> </android> </ti:app>
Instantiate the module with the
import Map from 'ti.map'
API, then make subsequent API calls with the new map object.import Map from 'ti.map'; const mapView = Map.createView({ mapType: Map.NORMAL_TYPE });
# iOS
This module is a replacement for the built-in Titanium.Map module on iOS.
For more instructions and examples of using the module, refer to the iOS Map Kit guide (opens new window).
# Requirements
- Applications using this module must be built using Xcode 5 or later.
# Getting Started
Edit the
modules
section of your tiapp.xml file to include this module:<ti:app> <modules> <!-- Add this line to your modules section --> <module platform="iphone">ti.map</module> </modules> </ti:app>
To use the
userLocation
property in iOS 8 and later, add either theNSLocationWhenInUseUsageDescription
(opens new window) orNSLocationAlwaysUsageDescription
(opens new window) key to the iOS plist section of the project'stiapp.xml
file.<ti:app> <ios> <plist> <dict> <key>NSLocationAlwaysUsageDescription</key> <string> Specify the reason for accessing the user's location information. This appears in the alert dialog when asking the user for permission to access their location. </string> </dict> </plist> </ios> </ti:app>
Instantiate the module with the
import Map from 'ti.map'
API, then make subsequent API calls with the new map object.import Map from 'ti.map'; const mapView = Map.createView({ mapType: Map.NORMAL_TYPE });
# Breaking Changes
- The
addRoute
method no longer accepts a dictionary as a parameter. Pass a Modules.Map.Route object instead.
# Examples
# Basic Map Example
This is a basic map example that places a custom annotation on the map, and listens for click events on the annotation.
In this example, a custom property (myid
) is added to the annotation object.
While adding custom members to a Titanium object is not generally recommended,
in this case it provides a mechanism for uniquely identifying an annotation. This
can be useful, for example, if the annotations are dynamically generated
and it is not practical to identify them by title.
import Map from 'ti.map';
const window = Ti.UI.createWindow();
const mountainView = Map.createAnnotation({
latitude: 37.390749,
longitude: -122.081651,
title: 'Appcelerator Headquarters',
subtitle: 'Mountain View, CA',
pincolor: Map.ANNOTATION_RED,
myid: 1 // Custom property to uniquely identify this annotation.
});
const mapView = Map.createView({
mapType: Map.NORMAL_TYPE,
region: {
latitude: 33.74511,
longitude: -84.38993,
latitudeDelta: 0.01,
longitudeDelta: 0.01
},
animate: true,
regionFit: true,
userLocation: true,
annotations: [ mountainView ]
});
const circle = Map.createCircle({
center: {
latitude: 33.74511,
longitude: -84.38993
},
radius: 1000, // = 1.0 km
fillColor: '#20FF0000'
});
mapView.addCircle(circle);
window.add(mapView);
mapView.addEventListener('click', event => {
Ti.API.info('Clicked ' + event.clicksource + ' on ' + event.latitude + ', ' + event.longitude);
});
windown.open();
# Alloy XML Markup
Previous example as an Alloy view.
In XML markup, use the View
element with the module
attribute set to ti.map
to create an
instance of a map view, then use the Annotation
element to define an annotation.
In the initializer file, load the map module and assign it to the Alloy.Globals.Map
namespace.
This variable can be used to reference map module constants in the project, as seen in the TSS
file to assign the pincolor
attribute.
alloy.js
:
// Loads the map module to the global Alloy scope, which can be referenced by Alloy.Globals.Map
Alloy.Globals.Map = require('ti.map');
app/views/index.xml
:
<Alloy>
<Window>
<Module id="mapView" module="ti.map" onClick="report" method="createView">
<Annotation id="appcHQ" myId="1337" />
</Module>
</Window>
</Alloy>
app/styles/index.tss
:
"#mapView": {
region: {
latitude: 33.74511,
longitude: -84.38993,
latitudeDelta: 0.01,
longitudeDelta: 0.01
}
},
"#appcHQ": {
latitude: 37.368122,
longitude: -121.913653,
title: "Appcelerator Headquarters",
subtitle: "San Jose, CA",
pincolor: Alloy.Globals.Map.ANNOTATION_RED
}
app/controllers/index.js
:
function report(event) {
Ti.API.info('Annotation ' + event.title + ' clicked, ID: ' + event.annotation.myID);
}
$.index.open();
# Map Clustering (iOS 11+)
This is a map-example which creates marker annotation and clustering of annotations.
The clusterIdentifier
property and the clusterstart
event are required in order to enable
clustering. You can control the clustering by defining the collisionMode
property and
setting special cluster annotations using the setClusterAnnotation
method on your map
view instance.
import Map from 'ti.map';
const window = Ti.UI.createWindow();
const annotations = [];
for (let i = 0; i < 10; i++) {
annotations.push(Map.createAnnotation({
title: 'Appcelerator Inc.',
subtitle: 'TiRocks!',
clusterIdentifier: 'abc', // Required for clusters
collisionMode: Map.ANNOTATION_VIEW_COLLISION_MODE_RECTANGLE,
showAsMarker: true,
markerGlyphText: i.toString(),
markerColor: 'blue',
markerGlyphColor: 'green',
markerTitleVisibility: Map.FEATURE_VISIBILITY_VISIBLE,
markerSubtitleVisibility: Map.FEATURE_VISIBILITY_HIDDEN,
markerGlyphImage: 'path/to/flag.png',
markerSelectedGlyphImage: 'path/to/flag-selected.png',
annotationDisplayPriority: Map.FEATURE_DISPLAY_PRIORITY_DEFAULT_LOW,
latitude: (Math.random() * 10) + 40,
longitude: Math.random() * 10,
}));
}
const mapView = Map.createView({
annotations: annotations,
rotateEnabled: true,
mapType: Map.MUTED_STANDARD_TYPE,
showsPointsOfInterest: false,
userLocation: true
});
mapView.addEventListener('clusterstart', event => {
Ti.API.info('clustering started!');
const clusterAnnotation = Map.createAnnotation({
showAsMarker: true,
markerText: event.memberAnnotations.length.toString(),
title: 'Cluster Title',
subtitle: 'Cluster Subtitle',
});
mapView.setClusterAnnotation({
annotation: clusterAnnotation,
memberAnnotations: event.memberAnnotations
});
});
window.add(mapView);
window.open();
# Search Request (iOS only)
The following example shows the MapKit based search request.
The options in search
(2nd parameter) are optional, but improve
the accuracy of the results.
import Map from 'ti.map';
Map.addEventListener('didUpdateResults', event => {
console.warn('Found place:');
console.warn(event)
});
Map.search('Colosseum', {
region: {
latitude: 41.890560,
longitude: 12.494270,
latitudeDelta: 1,
longitudeDelta: 1,
},
resultTypes: [Map.SEARCH_RESULT_TYPE_POINT_OF_INTEREST, Map.SEARCH_RESULT_TYPE_ADDRESS]
});
# Properties
# apiName READONLY
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button
returns Ti.UI.Button
.
# lifecycleContainer
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
# Methods
# applyProperties
Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.
Parameters
Name | Type | Description |
---|---|---|
props | Dictionary | A dictionary of properties to apply. |
Returns
- Type
- void
# createAnnotation
Creates and returns an instance of Modules.Map.Annotation.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.Annotation> | Properties to set on a new object, including any defined by Modules.Map.Annotation except those marked not-creation or read-only. |
Returns
# createCamera
Creates and returns an instance of Modules.Map.Camera.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.Camera> | Properties to set on a new object, including any defined by Modules.Map.Camera except those marked not-creation or read-only. |
Returns
- Type
- Modules.Map.Camera
# createCircle
Creates and returns an instance of Modules.Map.Circle.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.Circle> | Properties to set on a new object, including any defined by Modules.Map.Circle except those marked not-creation or read-only. |
Returns
- Type
- Modules.Map.Circle
# createImageOverlay
Creates and returns an instance of Modules.Map.ImageOverlay.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.ImageOverlay> | Properties to set on a new object, including any defined by Modules.Map.ImageOverlay except those marked not-creation or read-only. |
Returns
# createPolygon
Creates and returns an instance of Modules.Map.Polygon.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.Polygon> | Properties to set on a new object, including any defined by Modules.Map.Polygon except those marked not-creation or read-only. |
Returns
- Type
- Modules.Map.Polygon
# createPolyline
Creates and returns an instance of Modules.Map.Polyline.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.Polyline> | Properties to set on a new object, including any defined by Modules.Map.Polyline except those marked not-creation or read-only. |
Returns
- Type
- Modules.Map.Polyline
# createRoute
Creates and returns an instance of Modules.Map.Route.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.Route> | Properties to set on a new object, including any defined by Modules.Map.Route except those marked not-creation or read-only. |
Returns
- Type
- Modules.Map.Route
# createSnapshotter
Creates and returns an instance of Modules.Map.Snapshotter.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.Snapshotter> | Properties to set on a new object, including any defined by Modules.Map.Snapshotter except those marked not-creation or read-only. |
Returns
# createStreetViewPanorama
Creates and returns an instance of Modules.Map.StreetViewPanorama.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.StreetViewPanorama> | Properties to set on a new object, including any defined by Modules.Map.StreetViewPanorama except those marked not-creation or read-only. |
Returns
# createView
Creates and returns an instance of Modules.Map.View.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Map.View> | Properties to set on a new object, including any defined by Modules.Map.View except those marked not-creation or read-only. |
Returns
- Type
- Modules.Map.View
# geocodeAddress
Resolve address details using the CLGeocoder
to get information (e.g.
latitude, longitude, postal code and city) about a given input address.
The result is provided via the callback (second function argument).
Parameters
Name | Type | Description |
---|---|---|
address | String | The address to resolve. |
callback | Callback<Object> | Function to be called upon completion (either success with a place or an error). |
Returns
- Type
- void
# getLookAroundImage
A utility function that you use to create a static image from a LookAround scene.
Parameters
Name | Type | Description |
---|---|---|
callback | Callback<Object> | Function to be called upon completion (either success with an image or an error). |
latitude | Number | Latitude of the preferred region. |
longitude | Number | Longitude of the preferred region. |
Returns
- Type
- void
# isGooglePlayServicesAvailable
Returns a code to indicate whether Google Play Services is available on the device.
Returns
One of the following status codes: SUCCESS, SERVICE_MISSING, SERVICE_VERSION_UPDATE_REQUIRED, SERVICE_DISABLED or SERVICE_INVALID.
- Type
- Number
# openLookAroundDialog
Opens a LookAround window modally.
Parameters
Name | Type | Description |
---|---|---|
latitude | Number | Latitude of the preferred region. |
longitude | Number | Longitude of the preferred region. |
Returns
- Type
- void
# search
Uses the native MKLocalSearchCompleter
class to search places for
a given input value.
Please use the didUpdateResults
event to get updates for a search
completion request via the results
field. If the search failed, the
results
field is empty and an error
is provided.
Parameters
Name | Type | Description |
---|---|---|
value | String | The value to search with. |
options | SearchCompletionOptions | Additional options to fine-tune the search request. |
Returns
- Type
- void
# Constants
# ANNOTATION_AZURE
Color constant used to set a map annotation to azure via the pincolor property.
# ANNOTATION_BLUE
Color constant used to set a map annotation to blue via the pincolor property.
# ANNOTATION_CYAN
Color constant used to set a map annotation to cyan via the pincolor property.
# ANNOTATION_DRAG_STATE_END
Used in the pinchangedragstate event to indicate that the user finished moving the annotation.
# ANNOTATION_DRAG_STATE_START
Used in the pinchangedragstate event to indicate that the user started dragging the annotation.
# ANNOTATION_GREEN
Color constant used to set a map annotation to green via the pincolor property.
# ANNOTATION_MAGENTA
Color constant used to set a map annotation to magenta via the pincolor property.
# ANNOTATION_ORANGE
Color constant used to set a map annotation to orange via the pincolor property.
# ANNOTATION_PURPLE
Color constant used to set a map annotation to purple via the pincolor property.
# ANNOTATION_RED
Color constant used to set a map annotation to red via the pincolor property.
# ANNOTATION_ROSE
Color constant used to set a map annotation to rose via the pincolor property.
# ANNOTATION_VIEW_COLLISION_MODE_CIRCLE
Constant indicating that a circle inscribed in the collision frame rectangle should be used to determine collisions.
# ANNOTATION_VIEW_COLLISION_MODE_RECTANGLE
Constant indicating that the full collision frame rectangle should be used for detecting collisions.
# ANNOTATION_VIOLET
Color constant used to set a map annotation to violet via the pincolor property.
# ANNOTATION_YELLOW
Color constant used to set a map annotation to yellow via the pincolor property.
# FEATURE_DISPLAY_PRIORITY_DEFAULT_HIGH
Constant indicating that the item's display priority is high.
An annotation view with this priority is removed from the map when its bounds collide with the bounds of another view with a higher priority. If the priorities of the two views are equal, the view furthest from the center of the map's visible region is hidden first.
# FEATURE_DISPLAY_PRIORITY_DEFAULT_LOW
Constant indicating that the item's display priority is low.
An annotation view with this priority is removed from the map when its bounds collide with the bounds of another view with a higher priority. If the priorities of the two views are equal, the view furthest from the center of the map's visible region is hidden first.
# FEATURE_DISPLAY_PRIORITY_REQUIRED
Constant indicating that the item is required.
An annotation view with this priority does not participate in clustering.
# FEATURE_PHYSICAL_FEATURES
The option that represents physical map features such as mountain ranges, rivers, and ocean basins.
# FEATURE_TERRITORIES
The option that represents territorial boundaries such as a national border, a state boundary, or a neighborhood.
# FEATURE_TYPE_POINT_OF_INTEREST
The option that represents points of interest such as museums, cafes, parks, or schools.
# FEATURE_VISIBILITY_ADAPTIVE
Constant indicating that title text adapts to the current map state.
For markers in the normal state, title text is displayed and subtitle text is hidden. When a marker is selected, the title and subtitle text are hidden when the marker requires a callout.
# FEATURE_VISIBILITY_HIDDEN
Constant indicating that title text is always hidden.
# FEATURE_VISIBILITY_VISIBLE
Constant indicating that title text is always visible.
# HYBRID_FLYOVER_TYPE
Used with mapType to display a satellite flyover image of the area with road and road name information layered on top. Available in iOS 9.0 and later.
# HYBRID_TYPE
Used with mapType to display a satellite image of the area with road and road name information layered on top.
# MUTED_STANDARD_TYPE
Used with mapType to display a street map where your data is emphasized over
the underlying map details. Available in iOS 11.0 and later. On Android it is mapped to NORMAL_TYPE
.
# NORMAL_TYPE
Used with mapType to display a street map that shows the position of all roads and some road names.
# OVERLAY_LEVEL_ABOVE_LABELS
Place the overlay above roadways but below map labels, shields, or point-of-interest icons. Available in iOS 7.0 and later.
# OVERLAY_LEVEL_ABOVE_ROADS
Place the overlay above map labels, shields, or point-of-interest icons but below annotations and 3D projections of buildings. Available in iOS 7.0 and later.
# POLYLINE_JOINT_DEFAULT
Default: Mitered joint, with fixed pointed extrusion equal to half the stroke width on the outside of the joint.
# POLYLINE_JOINT_ROUND
Rounded on the outside of the joint by an arc of radius equal to half the stroke width, centered at the vertex.
# POLYLINE_PATTERN_DASHED
Polyline type constant used to display a dashed polyline via pattern property.
# POLYLINE_PATTERN_DOTTED
Polyline type constant used to display a dotted polyline via pattern property.
# REASON_API_ANIMATION
Used in the regionwillchange event. The animation was initiated in response to the user actions.
# REASON_DEVELOPER_ANIMATION
Used in the regionwillchange event. The camera moved in response to a request from the application.
# REASON_GESTURE
Used in the regionwillchange event. The camera moved in response to the user gestures on the map.
# SATELLITE_FLYOVER_TYPE
Used with mapType to display satellite flyover imagery of the area. Available in iOS 9.0 and later.
# SEARCH_RESULT_TYPE_ADDRESS
A value that indicates that search results include addresses.
# SEARCH_RESULT_TYPE_POINT_OF_INTEREST
A value that indicates that search results include points of interest.
# SEARCH_RESULT_TYPE_QUERY
A value that indicates that the search completer includes query completions in results.
# SERVICE_DISABLED
Code returned from isGooglePlayServicesAvailable. Google Play services has been disabled on this device.
# SERVICE_INVALID
Code returned from isGooglePlayServicesAvailable. The version of Google Play services installed on this device is not authentic.
# SERVICE_MISSING
Code returned from isGooglePlayServicesAvailable. Google Play services is not installed on the device.
# SERVICE_VERSION_UPDATE_REQUIRED
Code returned from isGooglePlayServicesAvailable. Google Play services is out of date.
# SUCCESS
Code returned from isGooglePlayServicesAvailable. Google Play services is available, and the connection is successful.