jHERE

jHERE 1.0.0 is here

on announcements, release, code

Three years later, maps are even cooler than they were back when I first released jHERE. Maps APIs are however still complicated. With version 1.0.0 jHERE addresses once again this problem by offering a simple yet powerful maps API.

jHERE 1.0.0 no longer depends on jQuery, keeping your webpages even more lightweight. jQuery is still very popular, and lots of websites still use it. However as older and buggy browser are disappearing developers start dropping jQuery and rely on native JS APIs, which are faster and remove the need of downloading more bytes just to do some DOM manipulation. For this reason I decided to rebuild jHERE from scratch and drop everything that was jQuery specific. At a later stage I will provide a jQuery wrapper around the core of the library.

This first iteration (jHERE 1.0.0-beta.1), I am releasing a beta version of jHERE. The core API is there and is somehow stable, but there are some things that I still have not ported from earlier version, namely heatmaps and KML support and all the extensions that were shipped with jHERE. Additionally, the core methods to add markers and information bubbles only support very basic options.

The plan is to release a number of beta versions until everything is ready for a proper release.

Below is a summary of the API that is currently available.

Create a new map

The first step before using jHERE to add beautiful maps to your website is to go to developer.here.com, sign up, register a new application and obtain your app_id and app_code.

Then you can create a map like this:

var element = document.querySelector('#map');  
var map = jHERE(element, {  
                          app_id: 'your_app_id',
                          app_code: 'your_app_code'
                          zoom: 14,
                          center: {lat: 52.5, lng: 13.3}
                         });

Set the center of the map

//Sets the new center with animation
map.center({lat: 52.1, lng: 13.23});  

Set the zoom level of the map

map.zoom(13);  

Set map type

The API here is a bit different than it use to be, due to how the HERE Maps API handle map types and layers in version 3.

//Sets the map type to normal map
//uses a very basic layer with no roads an no labels
map.type('normal', 'xbase')  

Event listeners

Event listeners are also handled a bit differently than they used to be. The HERE Maps API now does some normalization so click events are treated the same as tap events, so the event names exposed by jHERE have changed accordingly. More information is available in the documentation.

As in earlier versions of jHERE, events are extended by adding a geo property that contains latitude and longitude of the pointer on the map (for pointer events).

//Logs latitude and longitude of a tap event
map.on('tap', function(e){  
    console.log(e.geo);
});

Add markers

//Creates a new simple marker
map.marker({lat: 52.1, lng: 13.23})  

Markers can be cleared with

map.nomarkers();  

Add info bubbles

The following code shows an info bubble on the map. content can be a string of text or a DOM node.

var options = {  
    content: 'foo',
    onclose: function(){
        //Called when the info bubble is closed
    },
    //Specifies that the current info bubble
    //is the only one present on the map.
    //Useful when only one info bubble should be
    //open at any given time
    only: true
}
map.bubble({lat: 52.5, lng: 13.3}, options);  

Info bubbles can be cleared with

map.nobubbles();  

Advanced usage

As in previous versions of jHERE, more advanced functionalities are supported by exposing the original map object of the HERE API.

map.originalMap(function(map, H){  
    //map is the instance of the H.Map object that represents the map
    //H is the main namespace of the HERE Maps API
});

Contribute

To contribute please submit a pull request to the Github repository, jsla3 branch.

The code style recommendations have not changed:

  1. ☼ Like: semicolons at the end of the line.
  2. ☁ Don't like: tabs, use 4 spaces instead. Not 1, not 2, 4.
  3. ☼ Like: single quotes for strings.
  4. ☁ Don't like: trailing whitespaces, messed up indentation.
  5. ☼ Like: meaningful variable names. Don't steal the job to the minificator. Also I want to keep the size of the plugin small, so do facilitate the minificator's job by caching long namespaces and functions that are invoked often.
  6. ☁ Don't like: globals.
  7. ☼ Like: well documented API. If you add functionalities, take the time to write the documentation. Use JSDoc-style comments, grunt docs will do the rest.

What differs from previous versions is that jHERE 1.0.0 uses ES6 features (mostly modules, arrow functions, const) and is transpiled with Babel and built with Webpack.

The build setup is Grunt-based and for now the documentation is generated with doxdox from JSDoc inline comments.