jHERE

Maps made easy.

Documentation

How to use jHERE

Using jHERE in your websites and applications is really easy.

Include either jQuery, Zepto.JS or Tire.js at the end of your page

<script type="text/javascript" src="js/jquery.min.js"></script>

or

<script type="text/javascript" src="js/zepto.min.js"></script>

or

<script type="text/javascript" src="js/tire.min.js"></script>

Download the plugin code, copy it in your project folder and add the necessary script tags after jQuery, Zepto.JS or Tire.js. If you are using Zepto.JS then you will need to include the Zepto adapter before including the plugin.

<script type="text/javascript" src="js/zepto.adapter.js">
<!--Only when using Zepto-->
</script>

If you are using Tire.js then you will need to include the Tire adapter before including the plugin.

<script type="text/javascript" src="js/tire.adapter.js">
<!--Only when using Tire-->
</script>

<script type="text/javascript" src="js/jhere.js"></script>

And you are done.

Make sure the DOM element that will contain the map has the appropriate size via CSS, e.g. by setting width and height.

Note that jHERE requires Zepto.JS, jQuery > 1.7 or Tire.js >= 1.1.1

Make a map

$('.selector').jHERE(options);

options is an object that looks like this:

{
 enable: ['behavior', 'zoombar'], //An array of components as strings.
 zoom: 12, //a positive integer.
 center: []|{}, //An object of type {latitude: Number, longitude: Number}
                //or array [latitude, longitude],
 type: 'map', //can be map (the default), satellite, terrain, smart, pt.
              //see type documentation below for details.
 appId: '_peU-uCkp-j8ovkzFGNU', //appId from the Nokia developer website,
 authToken: 'gBoUkAMoxoqIWfxWA5DuMQ' //authenticationToken from the
                                     //Nokia developer website
}
Components for enable can be:

  • 'behavior': enables map interaction (drag to pan, scroll-wheel to zoom)
  • 'zoombar': shows a zoom control
  • 'scalebar': shows a scalebar on the map
  • 'typeselector': shows a dropdown where the user can select map, satellite, terrain
  • 'overview': shows a button to activate the overview panel
  • 'traffic': shows a button to enable the traffic layer
  • 'publictransport': shows a button to enable the public transport view
  • 'positioning': shows a button that triggers detection of the user's position
  • 'rightclick': shows a contextual menu on right click to zoom in and out
  • 'contextmenu': shows an enriched contextual menu with: current address, zoom in/out, directions

Default for enable is ['behavior', 'zoombar', 'scalebar', 'typeselector']. Pass false for no components.

HERE API Credentials

jHERE uses by default the appId and authToken that I used for development, and it is ok for you to use the same credentials for development and testing purpose.

However you should really register on the HERE developer website and get your own. I strongly encourage you to do so especially for production use, as my credentials may unexpectedtly stop working at any time.

Map events

It is possible to listen for events on the map in the usual jQuery way (on, off). All the event names start with map. The event passed to the callback function always has a geo (data.geo for Tire users) property that contains latitude and longitude of the point where the event originated.

For example, to listen for clicks events:

$('.mymap').on('mapclick', function(e){ console.log (e.geo)});

Supported events are:

mapclick, mapmouseup, mapmousedown, mapmousemove, mapmouseover, mapmouseout, mapmouseenter, mapmouseleave, maplongpress, mapdragstart, mapdrag, mapdragend, mapresize, maptouchstart, maptouchend, maptouchmove.

Set default credentials

$.jHERE.defaultCredentials(appId, authToken);

Set the default credentials. After this method has been called it is no longer necessary to include credentials in any of the calls to $('.selector').jHERE(options);.

Center the map

$('.selector').jHERE('center', centerObject);

centerObject can be an object of type

{latitude: -43, longitude: 55}

or an array

[-43, 55]

Zoom the map

$('.selector').jHERE('zoom', zoomLevel);

zoomLevel is a positive integer

Set the map type

$('.selector').jHERE('type', mapType);

mapType is a string:

  1. 'map': the normal map type. This is the default.
  2. 'smart': a map with most of the colors grayed out. Useful for data visualization.
  3. 'pt': a smart map where the tiles also contain the public transport lines.
  4. 'satellite': satellite view.
  5. 'terrain': terrain view.
  6. 'community': HERE Maps community layer.
  7. 'satcommunity': HERE Maps community layer with satellite imagery.
  8. 'traffic': traffic layer.

Add markers to the map

$('.selector').jHERE('marker', positionObject, markerOptions);

positionObject can be an object of type

{latitude: -43, longitude: 55}

or an array

[-43, 55]

markerOptions can be an object of type

{
 text: '!',
 textColor: '#333333',
 fill: '#ff6347',
 stroke: '#333333',
 icon: 'urlToIcon',
 anchor: {x: 12, y: 18} //an icon 24x36 would result centered
 click: function(event){/this is the element, event.geo contains the coordinates/},
 dblclick: function(event){/this is the element, event.geo contains the coordinates/},
 mousemove: function(event){/this is the element, event.geo contains the coordinates/},
 mouseover: function(event){/this is the element, event.geo contains the coordinates/},
 mouseout: function(event){/this is the element, event.geo contains the coordinates/},
 mouseenter: function(event){/this is the element, event.geo contains the coordinates/},
 mouseleave: function(event){/this is the element, event.geo contains the coordinates/},
 longpress: function(event){/this is the element, event.geo contains the coordinates/}
}
All parameters are optional.

Remove all the markers from the map

$('.selector').jHERE('nomarkers');

Add bubbles to the map

$('.selector').jHERE('bubble', positionObject, bubbleOptions);

positionObject can be an object of type

{latitude: -43, longitude: 55}

or an array

[-43, 55]

bubbleOptions can be an object of type

{
 content: 'Hello World!',
 closable: true,
 onclose: function(){}
}

content can be a String or a jQuery object.

Remove all the bubbles from the map

$('.selector').jHERE('nobubbles');

Display KMLs on the map

$('.selector').jHERE('kml', KMLfile, zoomToKML, ondone);

KMLfile is the URL to a KML file

zoomToKML is a boolean. If set to true, once the KML has been parsed and displayed the map will be zoomed to the bounding box of the KML.

ondone is a function, called once the KML has been rendered.

It is required that the KML is hosted on the same domain where the application is hosted, or that the server that hosts the KML file has CORS enabled.

Add heatmap layers to the map

$('.selector').jHERE('heatmap', data, type, options);

data is an array of objects of type:

{latitude: 43, longitude: 26, value: 35}

Values will be automatically normalized between 0 and 1.

type defines the type of heatmap, can be density or value. Heatmaps on Wikipedia.

options is an object that can have a colors property used to customize the heatmap look.

colors is an object of type:

{
 stops: {
   "0": "rgba(0, 0, 64, 1)",
   "0.3": "rgba(0, 0, 64, 1)",
   ...
 }
}

Access the underlying HERE JavaScript API framework

$('.selector').jHERE('originalMap', closure);

This is useful when advanced operations that are not exposed by this plugin need to be performed. Check developer.here.com for the documentation.

closure should look like this:

function(map, here){
   //this is the DOM element
   //map is the HERE JavaScript API map object
   //here is the whole HERE JavaScript API namespace
}

Inspect map properties

var properties = $('.selector').jHERE();

Returns an object containing some properties of the map canvas.

{
 center: {latitude: float, longitude: float},
 zoom: integer,
 bbox: {
   topLeft: {
          latitude: float,
          longitude: float
        },
        bottomRight:{
          latitude: float,
          longitude: float
        }
 }, //bbox is the bounding box, i.e. the geographical area currently displayed
 type: string //can be: map, smart, pt, satellite, terrain, community, satcommunity, traffic
};
Note that these properties will all be undefined if the map hasn't been yet initialized.

Extend jHERE

jHERE can be easily extended with additional features. Some example of extensions are located here. An extension should be implemented within a self-invoking function. Add the function(s) that will be called via

$('.selector').jHERE('myextension', param1, param2);

as follows:

$.jHERE.extend('myextension', function(param1, param2){
 //this is the plugin object
 //this.element is the DOM element
 //this.map is the HERE JavaScript API map
});

A good example of extension is the routing extension.