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:
'map'
: the normal map type. This is the default.'smart'
: a map with most of the colors grayed out. Useful for data visualization.'pt'
: a smart map where the tiles also contain the public transport lines.'satellite'
: satellite view.'terrain'
: terrain view.'community'
: HERE Maps community layer.'satcommunity'
: HERE Maps community layer with satellite imagery.'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.