Values can be functions or literals, changes to `fillKey`

@markmarkoh markmarkoh released this Apr 18, 2015 · 117 commits to master since this release

The v0.4.0 release of DataMaps includes 3 major updates:

1. Instead of specifying fillKey for each geography, you can now specify a color value in fillColor.

Previously, the coloring of subunits (geographies - states & countries) relied on fillKey and a corresponding fills object. While this is still supported, you can now directly specify a color under the fillColor value.

For example:

new Datamap({
  element: document.getElementById('map'),
  scope: 'usa',
  data: {
    NC: {
       fillColor: '#FA0FA0'
     },
    TX: {
        fillKey: 'home'
     }
  },
  fills: {
     home: '#FA0FA0',
     defaultFill: '#DDDDDD'
   }
})

Live Example Here

In the above example, both North Carolina and Texas will be filled with the color #FA0FA0, while all other states will be filled with #DDDDDD.

For backwards compatibility, fillKey will take priority, then fillColor, then defaultFill.

2. Values can now be functions instead of literals

Instead of passing literal values in the configuration for your map, you can now pass functions to return values dynamically.

For example:

new Datamap({
  element: document.getElementById('map'),
  scope: 'usa',
  data: {
    NC: {
       fillColor: '#FA0FA0'
     },
    NJ: {
       fillColor: function(geography, data) {
          return '#00FF00'
       }
    },
    TX: {
        fillKey: 'home',
       governor: 'Abbott'
     },
    NY: {
      governor: 'Cuomo'
   }
  },
  fills: {
     home: '#FA0FA0',
     defaultFill: function(geography, datum) {
        if ( ['FL', 'MT', 'CA', 'OH'].indexOf(geography.id) > -1 ) {
          return '#000FFF';
        }
        return '#BAFBAF';
     }
   }
})

Live Example Here

A few things to note about the above example:

  1. When dealing with states and countries, the function parameters will be geography and datum. datum will be undefined if there is no corresponding object in the data object ( *in this example, there will be 3 non-undefined datums: NC, NJ, NY, and TX. However all 50 states will have a defined geography, and it contains all of the GeoJSON data pertaining to that state.
  2. When defaultFill is called for NY, the datum parameter will be an object like: {governor: "Cuomo"}
  3. When defaultFill is called for AK, the datum parameter will be undefined, so you'll have to rely on the fact that geography.id is AK to figure out what fill to return.
  4. Each function needs to return a value or unexpected things may happen (fills may be black, for example).
This also works with the arcs and bubbles plugins.

Example:

map.bubbles([
  {centered: 'NY', fillKey: 'home', radius: 10, highlightFillColor: '#aaafff'}, // literal value
  {centered: 'KY', fillKey: 'home', highlightFillColor: function(datum) { return '#fa0fa0'; }}, //function
  {centered: 'TX', fillKey: 'bubbleEx', radius: function(datum) { return 20; }}, //function
  {centered: 'CA', fillKey: 'bubbleEx2', radius: 46},
  {centered: 'GA', fillKey: 'Visited', radius: 15, highlightFillOpacity: function() { return 0.5 }}
],
{  popupOnHover: false,
   highlightFillOpacity: function(datum) { if ( datum.fillKey === 'home' ) return 0.8; else return 0.4; }
});

Live Example Here

The above code has a few examples of mix-and-matching functions and literals. For bubbles that don't have a value set explicitly, DataMaps will fall back to functions passed in in the second parameter. Otherwise defaults will be used.

map.arc([{
  origin: {
    latitude: function(datum) { return 30 },
    longitude: -97
  },
  destination: {
    latitude: 40,
    longitude: -110
  }
}]);

This example is a bit contrived - but it's just meant to demonstrate that almost any literal value can be replaced by a function.

3. Custom settings like highlightFillColor and highlightFillBorderWidth can now be set per country/state.

new DataMap({
   element: document.getElementById('map'),
   geographyConfig: {
     highlightFillColor: '#0FA0FA' 
   },
   data: {
        TX: {
          fillKey: 'home',
          highlightFillColor: '#FFF',
          highlightBorderColor: '#222',
          governor: 'Abbott'
        }
   });

Live Example Here

In the above example, all states except for TX will have #0FA0FA set on hover, while NY will use the custom value set (#FFF).

Dynamic zooming & dragging based on mouse wheel / scroll pad

This isn't a library update, but a great how-to for a commonly asked for feature.

Example:

var map = new Datamap({
  scope: 'world',
  element: document.getElementById('container1'),
  projection: 'mercator',
  done: function(datamap) {
     datamap.svg.call(d3.behavior.zoom().on("zoom", redraw));

     function redraw() {
       datamap.svg.selectAll("g").attr("transform", "translate(" + d3.event.translate + ")scale(" + d3.event.scale + ")");
     }
  }
})

Live Example Here
Live Example #2

The done method is called after the map has drawn and it provides the D3 selection for users to add custom behavior to (like add event listeners, or in this case - set up zooming and dragging).

Downloads