How to Use

 

Getting Started

Using CMaps Analytics in an HTML-5-enabled browser, requires:

  1. A valid CMaps Analytics key or access to CMaps Analytics Designer: Click Here to Sign Up 
  2. jQuery (any version higher than 1.8+): https://ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js
  3. CMaps Analytics API URL: https://api.cmapsanalytics.net/mapview?version=4.0

*For a complete list of JS API functions, events and properties, check out the API Reference.

What Makes a Map?

CMaps Analytics map is created with a base web map. The base m can use Google Maps, MapBox / Leaflet, HERE, ESRI and others).

On top of the base map is any number of layers. For example, you can simultaneously display and have drilling interaction between points, regions, and ESRI powered layers.

The CMaps Analytics base web map has a number of properties that you can set that control the behavior and appearance. Each layer has it’s own layer properties. There are over 20 available layer types that fulfill a lot of common functional requirements.

In this getting started guide you will create a base web map and then add layers on top.

CMaps Config (.CMAP template) + JS API Concept

*MapCfg’s are NOT required to use the map

Before you build your first map with CMaps Analytics, it is important to understand our CMaps Analytics configuration (also referred to as as a CMaps Analytics template, project, or .CMAP file). A CMaps Analytics configuration file is created by CMapsAnalytics Designer. Through point and click configuration, this output template file contains many map and layer configurations. This metadata can be formatted as XML or JSON format. A CMaps Analytics config file is not required to use the CMaps Analytics JS API, but if you are building a map for an app, it will save you lots of time and code. Learn more about CMaps Analytics building blocks

Hello World

It’s time to build our first map! The process for loading CMaps Analytics in the browser can be completed with or without a template. The following is a blank map:

Hello World Example

COMPLETE CODE:

We put together the complete code as it exists on a single HTML page for reference.. Everything we do moving forward will build upon this basic example.

<!doctype html>
<html>
<head>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js"></script>
  <script src="https://api.cmapsanalytics.net/mapview?version=4.0"></script>
  <script type="text/javascript">
		var cMap = new centigon.locationIntelligence.MapView();
		cMap.parseConfig({url:"https://cmapsconnect.com/demos/templates/HelloWorld.cmap"});
  </script>
</head>
<body>
  <div id="mapDiv"></div>
</body>
</html>

Setting CMaps Config Options with JS API

In our Hello World example we are loading a basic CMaps Analytics Config file.

https://cmapsconnect.com/demos/templates/HelloWorld.cmap

The Cmap config’s purpose is to rapidly design your map with the desired map & layer configurations. From there, you can use the JavaScript API to manage all aspects of the map and its layers to create a dynamic application.

Once you’ve load your map with a config file (or xml/json string), you can use the CMaps Analytics JS API to override anything, from data and appearance, to the number and type of map layers.

IMPORTANT NOTE: It’s important to note that in order to update a given layer’s data, the map configuration does not need to be edited and re-applied. Instead, use the JS api to update the underlying data whenever a data change is needed.

Important Properties you Should Know

There are a number of common properties that you may want to edit outside of the config:

CMaps Analytics API Key

cMap.key('enter_your_own_key');

Sign up for a key

Enable SSL - 

cMap.sslEnabled(true);

If you are loading maps into a secured environment, you will need to enable the maps APIs to load over SSL. Some maps providers like Google Maps do not permit SSL maps over non secured environments.

XML vs JSON Config Options

CMaps Analytics supports both XML and JSON based configurations. Based on your integration needs. Most modern implementations use the JSON format, but there is no limitations in using one or the other for the CMaps Analytics JS API.

CMaps Analytics Designer outputs both XML and JSON formats as a .CMAP file extension. This extension indicates what files can be imported back into CMaps Designer, and makes it easier to find on a file share than .XML and .JSON.

XML Config OptionsJSON Config Options

XML Config Options

XML Config Example

<mapView createdBy="name:cMapsAnalyticsDesigner;version:3.0" createdOn="6/27/2016"><viewName>My View</viewName><viewDescription></viewDescription><tags></tags><templateVersion></templateVersion><key>[your_cmaps_api_key]</key><googlePremierKey></googlePremierKey><dynamicZoomEnabled>true</dynamicZoomEnabled><currentLocationOnLoadDisabled>true</currentLocationOnLoadDisabled><panCoords></panCoords><zoomLevel></zoomLevel><dynamicZoomOnShapeSelect>false</dynamicZoomOnShapeSelect><dynamicZoomOnClusterSelect>false</dynamicZoomOnClusterSelect><dynamicZoomOnPointSelect>true</dynamicZoomOnPointSelect><showBreadcrumbsOnDrill>true</showBreadcrumbsOnDrill><dynamicZoomOnDrill>true</dynamicZoomOnDrill><multiSelectEnabled>false</multiSelectEnabled><adhocPanelVisibility>false</adhocPanelVisibility><radiusMeasureUnit>km</radiusMeasureUnit><indoorEnabled>true</indoorEnabled><sslEnabled>false</sslEnabled><useAdvancedInfowindow>false</useAdvancedInfowindow><includeAdvancedInfWinSummaryCard>true</includeAdvancedInfWinSummaryCard><includeAdvancedInfWinFilterCard>true</includeAdvancedInfWinFilterCard><includeAdvancedInfWinSearchCard>true</includeAdvancedInfWinSearchCard><includeAdvancedInfWinExportCard>true</includeAdvancedInfWinExportCard><includeAdvancedInfWinDriveCard>true</includeAdvancedInfWinDriveCard><includeAdvancedInfWinDrillCard>true</includeAdvancedInfWinDrillCard><includeAdvancedInfWinSelectCard>true</includeAdvancedInfWinSelectCard><includeAdvancedInfWinStreetViewCard>true</includeAdvancedInfWinStreetViewCard><includeAdvancedInfWinHelpCard>true</includeAdvancedInfWinHelpCard><advancedInfoWindowJsonCfg></advancedInfoWindowJsonCfg><infoWindowFontFamily>Arial</infoWindowFontFamily><infoWindowFontSize>12</infoWindowFontSize><infoWindowFontColor>000000</infoWindowFontColor><infoWindowFontAlign>left</infoWindowFontAlign><infoWindowUseBoldFont>false</infoWindowUseBoldFont><infoWindowFontUnderlineEnabled>false</infoWindowFontUnderlineEnabled><infWinItalicFontEnabled>false</infWinItalicFontEnabled><infoWindowVisibility>true</infoWindowVisibility><infoWindowValueVisibility>true</infoWindowValueVisibility><infoWindowLayerNameVisibility>true</infoWindowLayerNameVisibility><glowVisibility>true</glowVisibility><glowColor>0000ff</glowColor><baseMapImageryStyleType>styleTypeRoadmap</baseMapImageryStyleType><showTrafficLayer>false</showTrafficLayer><showTransitLayer>false</showTransitLayer><showBikelayer>false</showBikelayer><legendVisibility>false</legendVisibility><clusterToggleControlVisibility>false</clusterToggleControlVisibility><navigationControlVisibility>true</navigationControlVisibility><currentLocationControlVisibility>false</currentLocationControlVisibility><mapReady>true</mapReady><layerSelected>false</layerSelected><zoomChanged>false</zoomChanged><centerChanged>false</centerChanged><reverseGeocodeResponse>false</reverseGeocodeResponse><latLngToReverseGeocode></latLngToReverseGeocode><geocodeResponse>false</geocodeResponse><addressToGeocode></addressToGeocode><visible>true</visible><indoorMapVisibility>false</indoorMapVisibility><showPinsForIndoorMapLocations>false</showPinsForIndoorMapLocations><directionPanelVisibility>false</directionPanelVisibility><directionWaypoints></directionWaypoints><currentLocation>false</currentLocation><useFreeApi>false</useFreeApi><layers></layers></mapView>

Apply Config Using an XML File URL

cMap.parseConfig({url:"mapcfg.xml"});

Apply Config Using an XML String

cMap.parseConfig('<mapView createdBy=...');

JSON Config Options

JSON Config Example

{ "mapView": { "createdBy": "name:cMapsAnalyticsDesigner;version:3.0", "createdOn": "6/27/2016", "viewName": "My View", "key": "[your_cmaps_api_key]", "dynamicZoomEnabled": "true", "currentLocationOnLoadDisabled": "true", "dynamicZoomOnShapeSelect": "false", "dynamicZoomOnClusterSelect": "false", "dynamicZoomOnPointSelect": "true", "showBreadcrumbsOnDrill": "true", "dynamicZoomOnDrill": "true", "multiSelectEnabled": "false", "adhocPanelVisibility": "false", "radiusMeasureUnit": "km", "indoorEnabled": "true", "sslEnabled": "false", "useAdvancedInfowindow": "false", "includeAdvancedInfWinSummaryCard": "true", "includeAdvancedInfWinFilterCard": "true", "includeAdvancedInfWinSearchCard": "true", "includeAdvancedInfWinExportCard": "true", "includeAdvancedInfWinDriveCard": "true", "includeAdvancedInfWinDrillCard": "true", "includeAdvancedInfWinSelectCard": "true", "includeAdvancedInfWinStreetViewCard": "true", "includeAdvancedInfWinHelpCard": "true", "infoWindowFontFamily": "Arial", "infoWindowFontSize": "12", "infoWindowFontColor": "000000", "infoWindowFontAlign": "left", "infoWindowUseBoldFont": "false", "infoWindowFontUnderlineEnabled": "false", "infWinItalicFontEnabled": "false", "infoWindowVisibility": "true", "infoWindowValueVisibility": "true", "infoWindowLayerNameVisibility": "true", "glowVisibility": "true", "glowColor": "0000ff", "baseMapImageryStyleType": "styleTypeRoadmap", "showTrafficLayer": "false", "showTransitLayer": "false", "showBikelayer": "false", "legendVisibility": "false", "clusterToggleControlVisibility": "false", "navigationControlVisibility": "true", "currentLocationControlVisibility": "false", "mapReady": "true", "layerSelected": "false", "zoomChanged": "false", "centerChanged": "false", "reverseGeocodeResponse": "false", "geocodeResponse": "false", "visible": "true", "indoorMapVisibility": "false", "showPinsForIndoorMapLocations": "false", "directionPanelVisibility": "false", "currentLocation": "false", "useFreeApi": "false" } }

Apply Config Using a JSON File URL

cMap.parseConfig({url:"mapcfg.json"});

Apply Config Using a JSON String

cMap.parseConfig('{"mapView":{...');

Create a single layer map, using the map cfg vs using the api

For all maps, either be sure you have a div present, with the id of “mapDiv” (the default id), or simply pass the div id you want to use along to the MapView constructor, e.g.

var cMap = new centigon.locationIntelligence.MapView("myDiv")

Using the JS API only

Using a Map Config XML File

View Running Code Example

There are a lot of layers that can be created that require some additional work/tweaks beyond what’s above, but this is the minimum needed to create a basic points layer and listen for point clicks. For additional information on creating various layers, refer to the “Working With Layers” section.

More Information about Layers

CMaps Analytics allows you to customize these layers through a visual designer or via JS API. If you need to extend an existing layer or create a new one, it is also possible to add custom layers via the api.

All layers inherit from the same base layer class:

centigon.mapping.Layer

This base class is where all of the common functionality among layers is contained. What this means, is that while coding with the API, common/less code can be written to handle all layers, with more specific code being written to handle any layer-type-specifics. Further, as a developer, you can follow our custom layer development example to inject anything from D3 JavaScript-powered visualizations, to a layer from a 3rd party mapping provider.

Create a multi-layer map, using the map cfg vs using the api

For all maps, either be sure you have a div present, with the id of “mapDiv” (the default id),
or simply pass the div id you want to use along to the MapView constructor, e.g.

var cMap = new centigon.locationIntelligence.MapView("CMapsCustomDIV")

Chaining

Most functions of the map class return a reference to the map, allowing functions to be chained.

Using the JS API only

Using a Map Config file

View Running Code Example

Data Sources

The following are data sources that the map API supports access to.

Data Source Notes
API The map can be fed Arrays of raw data using the API. For example, to create an
integration between a Google RSS feed and the map, you could simply extract the data from the RSS feed and format it as arrays of data to pass to the API.

cMap.layerNames(["Choropleth Pins"]).
locations([["37.7693911,-122.4290072","37.790998,-122.431254","37.7480245,-122.4208806","37.789675,-122.417049", "37.7565985,-122.4045723","37.7956765,-122.4092976","37.7630855,-122.4578733","37.7739893,-122.4544912", "37.7473074,-122.4592076","37.780416,-122.403231","37.779602,-122.402201","37.778856,-122.402201"]]).
labels([["Dr. Goldstein", "Dr. Pinenuts", "Dr. Smith", "Dr. Jones", "Dr. Roger", "Dr. Rasheed", "Dr. Dongle", "Dr. Douglus", "Dr. Favre", "Dr. Oliver", "Dr. Alexander", "Dr. Mueller"]]).
values([[50, 11, 12, 14, 15, 16, 17, 18, 19, 10, 12, 5]]);
CSV CSV Files with Location, Label, Value, Color, Category and DrillId Columns are supported.

cMap.remoteLayerDataFeeds([{url:"mywebsite.com/stores.csv"}]);
JSON JSON Files with Location, Label, Value, Color, Category and DrillId columns are supported. “location”, “label”, “value”, “color”,
“category”, “drillid” and all other column names are all lowercase with no spaces or special characters.

cMap.remoteLayerDataFeeds([{url:"mywebsite.com/stores.txt"}]);
GeoJSON GeoJSON Feeds are supported for creating shapes.

cMap.polyDataSources([centigon.locationIntelligence.CMapAnalytics.DATA_PROVIDERS.GEOJSON_DATAPROVIDER]);
					cMap.locations([["united_states_shapes.geojson"]]);
ESRI Shapefiles Shapefiles are supported for creating shapes.

cMap.polyDataSources([centigon.locationIntelligence.CMapAnalytics.DATA_PROVIDERS.SHAPE_DATAPROVIDER]);
					cMap.locations([["united_states_shapes.shp"]]);
ESRI ArcGIS REST API With the ESRI Feature Layer and ESRI Shapes/Points layers,
metadata is consumed through ArcGIS, using the ArcGIS REST API.Further, the ArcGIS REST API may be leveraged when using ESRI layers. To get
access to this data and these properties, simply get a reference of the layer using the API, e.g. cMap.getLayerAt(), etc. As an additional resource, use the CMaps API Reference to view the corresponding ESRI functionality for the given layer.

var arcGisWrapper = cMap.getLayerAt(myEsriLayerIx).getEsriArcgGisRestApiWrapper();
CartoDB Public CartoDB Layers offer access to the underlying SQL data and querying capabilities.

Further, the CartoDB SQL API may be leveraged when using public CartoDB layers. To get
access to this data and these properties, simply get a reference of the layer using the API, e.g. cMap.getLayerAt(), etc. As an additional resource, use the CMaps API Reference to view the
corresponding CartoDB functionality for the given layer. Anything related to CartoDB should be clearly labeled.

console.log(cMap.getLayerAt(myCartoLayerIx).getLayerSQL());
cMap.getLayerAt(myCartoLayerIx).setLayerSQL("select * from .....");

Map Appearance

Size & PositionMap ImagerySelectorsAdvanced InfoWindows

Size

For the map’s size, simply set it’s div’s width/height. Then you can read the size back if needed.

<div id="mapDiv" style="height:100%;width:100%;position:absolute;top:0px;left:0px"></div>

cMap.getWidth();
cMap.getHeight();

Position

For the map’s position, simply set it’s div’s width/height. Alternatively, the xPos and yPos methods are read & write.

cMap.xPos(10);
cMap.yPos(10);

Map Imagery – Based on Google Maps

cMap.baseImageryStyle("whiteout" |
"grayscale" |
"military" |
"coolgray" |
"black" |
"satellite" |
"terrain" |
"roadmap" |
"hybrid");

Map Imagery – Custom

cMap.baseImageryStyle([{"featureType": "water","stylers": [{ "lightness": -99 },{"color":"#222222"}]},
{"featureType": "landscape","stylers": [{ "color": "#444444" }]}]);

Google API Special Layers

cMap.toggleSpecialApiLayer("bike" | "traffic" | "transit", true | false);

Selectors

 

cMap.adhocPanelVisible(true | false);

Advanced InfoWindow

The Advanced InfoWindow can be customized out of the box, allowing certain features a.k.a. “cards” to be enabled or disabled. Beyond that, there’s a standard way to inject your own custom components. For more on this, refer to the section Include Your Custom Components

cMap.useAdvancedInfowindow(true | false);
cMap.showAdvancedInfowindow(true | false);

Enable Advanced InfoWindow Widgets

Summary Tab

Summary

Filter

Filter

Rank

Rank

Time Filter

Time Filter

Search

Search

Search Places

Search Places

Export

Export

Driving

Directions

Driving Polygons

Distance Polygons

Drilling

Drilling

Street

Street View

Custom Widgets
 

Misc Map Properties

*For a complete list of functionality, check out the API Reference.

cMap.visible(true | false);

cMap.glowVisible(true | false);
cMap.glowColor("#00ff00");
cMap.glowTransparency(.75);

cMap.navigationControlVisible(true | false);

cMap.clusterToggleVisible(true | false);

cMap.legendVisible(true | false);

cMap.currentLocationControlVisible(true | false);

var modes = centigon.mapping.CMap.INFO_WINDOW_SELECTION_MODES;
cMap.showInfoWindowsOn(modes.SHOW_WINDOWS_ON_MOUSE_CLICK | modes.SHOW_WINDOWS_ON_MOUSE_OVER | modes.SHOW_WINDOWS_ON_CLICK_AND_MOUSE_OVER);

cMap.infoWindowsVisible(true | false);
cMap.infoWindowFontAlign("left");
cMap.infoWindowFontColor("#000000");
cMap.infoWindowFontFamily("arial");
cMap.infoWindowFontSize(12);
cMap.infoWindowLayerNamesVisible(true | false);
cMap.infoWindowLayerValuesVisible(true | false);
cMap.infoWindowUseBoldFont(true | false);
cMap.infoWindowUseFontUnderline(true | false);
cMap.infoWindowUseItalicFont(true | false);

Map Behaviors

*For a complete list of functionality, check out the API Reference.

Panning / Zooming

 

//Enable Auto-Zoom
cMap.dynamicZoomEnabled(true | false);
cMap.zoomLevel(1-20);
//Map Center - takes string address or lat,lng
cMap.panTo("california");
//Centers AND zooms to
cMap.panZoomTo("san diego");
//Center Map On Point Selection
cMap.dynamicZoomOnPointSelect(true | false);
//Auto-Zoom to Cluster Bounds on Select
cMap.dynamicZoomOnClusterSelect(true | false);
//Auto-Zoom to Shape Bounds on Select
cMap.dynamicZoomOnShapeSelect(true | false);
//Disable Current Location Detection on Load
cMap.preventCurrentLocationOnInit = true | false;
//Sets viewport based on CSV lat,lng's
cMap.setMapViewport(["32.71119959,-117.10787645", "33.0838130,-117.2503880"]);

//Gets location wherever the user clicks
cMap.addMapClickListener(function(location){

	console.log("clicked here on the map: " + location.toCsvLatLon());
});

//Clears all locations accumulated from dynamic zooming
cMap.clearAllLocationsForDynamicZooming();
//Adds all of a layer's locations for dynamic zooming
cMap.addLayerLocationsForDynamicZooming(layer);
//Triggers this type of dynamic zooming
cMap.setMapViewportToFitAllLayerLocations();

/*Say you've zoomed into Denver and have
selected a number of points and peformed some
filtering. This method will clear selections
across all layers in the map and reset the
dynamic zoom to it's automatic bounds.*/
cMap.clearSelectionsAndRefreshDynamicZoom();

//Removes all layers and resets all main map properties
cMap.resetMap();

Drilling

 

//Dynamically Zoom on Drill
cMap.dynamicZoomOnDrill(true | false);
//Show Breadcrumb on Drill
cMap.drillBreadcrumbsVisible(true | false);

Multi-Select

 

//Show Adhoc Selector Panel
cMap.adhocPanelVisible(true | false);
/*Enable multiple selection. This is only
necessary if doing this programmatically.
Otherwise, the map automatically toggles itself
in and out of multiselect mode
based on the AdHoc Selector Panel*/
cMap.multiSelectEnabled(true);

//Returns true if any type of multiselect is currently being used
cMap.isCurrentlyInMultiselectMode();

//Select item 1 of layer 1
cMap.selectItem("1,1");
//Select item 2 of layer 1
cMap.selectItem("1,2");
//Select EVERYTHING in layer 1
cMap.selectItem("1,1");
//-1 Clears all selections
cMap.selectItem("-1");
//Clears all selections
cMap.clearAllSelections();

Enable Indoor Map Viewer

If indoor maps are detected at a given location, the indoor map viewer will be loaded and ready.

 

cMap.indoorEnabled(true | false);

Map Events

*For a complete list of functionality, check out the API Reference.

Map Ready

 

cMap.onMapReady  = function(){console.log("map ready");};

Layers

 

cMap.onLayerMoused = function(layer){console.log("layer moused");};
cMap.onLayerSelected  = function(layer){console.log("layer selected");};

cMap.onLayersReady = function(){console.log("all layers ready");};

Panning / Zooming

 

cMap.onCenterChanged = function(){console.log("map moved");};
cMap.onZoomChanged  = function(){console.log("map zoomed");};

Directions/Travel

 

cMap.onDirectionsRawResponse = function(rawBaseApiResponse){};
cMap.onDirectionsResponse = function(directionsResponse){};
cMap.onTravelResponse = function(travelResponse){};

Drilling

 

cMap.onDrill = function(selectedLayer, layersInDrillPath){};

Current Location

 

cMap.onCurrentLocationChanged = function(){console.log("current location changed");};

Geocoding

 

cMap.onGeocodeResponse = function(geocodeResponse){};

Custom Layers

These get called whenever the map thinks the custom layer should be refreshed/redrawn.

 

cMap.renderCustomLayer  = function(layer){};
cMap.renderCustomLayerSelected = function(layer){};

Map Utility Functions

*For a complete list of functionality, check out the API Reference.

 

//Returns the area of the currently-visible map in meters.
cMap.getAreaOfViewportInMeters()

//Converts square meters to square miles.
cMap.sqMetersToMiles(sqMeters);

//Converts square meters to square km.
cMap.sqMetersToKm(sqMeters);

//Converts meters to miles.
cMap.metersToMiles(meters);

//Converts meters to km.
cMap.metersToKm(meters);

//Converts given value and unit of measure to meters.
cMap.convertDistanceToMeters(value, "mi" | "km" | "yards");

//Returns straight-line distance between 2 locations
cMap.getDistBetweenLocationsInMeters(["32.71119959,-117.10787645", "33.0838130,-117.2503880"]);

//Returns drive distance between 2 locations
cMap.getDriveDistBetweenLocationsInMeters(["32.71119959,-117.10787645", "33.0838130,-117.2503880"]);

//Tests if a given csv lat,lng is contained in the shape.
cMap.isLocInShape(shape, csvLatLng);

/*Check to see if the csvLatLng is contained
in the bounds made up of the lat,lngs in arrLatLng.*/
cMap.boundsContain(arrLatLng, csvLatLng)

/*Goes through the 1D array and
finds the first cell it considers
blank (uses isEmptyCellValue below)*/
cMap.getFirstIndexOfBlank(array);

//Returns true if ",", "", null or undefined
cMap.isEmptyCellValue(value)

//Converts all cells to lowercase
cMap.toLowercaseAllElementsIn2DArray(arr2D);
//Converts all cells to strings
cMap.toStringAllElementsIn2DArray(arr2D);
//Converts all cells to numbers
cMap.toNumberAllElementsIn2DArray(arr2D);

Browser Compatability

In general, a modern browser with HTML 5 Canvas support is required.

Browser Verified/Min Good Version
IE 10
Firefox 25
Chrome 50
Safari 6
[post-content id=7776]
Next Post