Home

Awesome

MapTable

GitHub stars GitHub release license

MapTable's primary function is to convert any dataset to a customizable set of components of Map, Filters and Table:

This library was originally conceived to render the home page and next generation of IXP directory for Packet Clearing House (PCH).

You can also browse other code samples and examples

<img src="https://packet-clearing-house.github.io/maptable/screenshots/minimal.png"> <img src="https://packet-clearing-house.github.io/maptable/screenshots/table-only.png"> <img src="https://packet-clearing-house.github.io/maptable/screenshots/custom-markers.png">

<img src="https://packet-clearing-house.github.io/maptable/screenshots/tooltip-country.png"> <img src="https://packet-clearing-house.github.io/maptable/screenshots/6000-markers.png"> <img src="https://packet-clearing-house.github.io/maptable/screenshots/heatmap.png">

Table of Contents

Dependencies

* Only used if you need a map

<a name="render"></a>Install

Here is minimum amount of HTML to render a MapTable with Map, Filter and Table.

<div id="vizContainer"></div>

<script src="d3.min.js"></script>
<!-- You can import it from cdnjs.com or bower-->
<script src="topojson.min.js"></script>
<!-- You can remove this line if you're not using the map -->
<!-- You can import it from cdnjs.com or bower -->
<script src="maptable.min.js"></script>
<!-- You can import it from cdnjs.com or bower -->
<script>
  var viz = d3
    .maptable('#vizContainer')
    .csv('dataset.csv')
    .map({ path: 'world-110m.json' }) // You can remove this line if you want to disable the map
    .filters() // You can remove this line if you want to disable filters
    .table() // You can remove this line if you want to disable the table
    .render(); // This is important to render the visualization
</script>

MapTable is available on cdnjs.com. Remember though, cool kids concatenate their scripts to minimize http requests.

If you want to style the MapTable elements with some existing styles, you can prepend the above HTML with:

<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css" /> <link rel="stylesheet" href="../maptable.css" />

Declaring MapTable elements

To create a visualization (Map or/and Table or/and Filters) of your dataset, you need to provide first the container of your visualization

<div id="vizContainer"></div>

The default order of the 3 components is Map, Filters and Table. If you want to place the components in a different order, you can put them on the main container:

<div id="vizContainer">
  <div id="mt-map"></div>
  <div id="mt-filters" class="panel panel-default"></div>
  <div id="mt-table"></div>
</div>

You instantiate the MapTable library into the viz variable based on the #vizContainer ID you declared in the DOM:

<script>
  var viz = d3.maptable('#vizContainer'); // #vizContainer is the css selector that will contain your visualization
</script>

The MapTable viz declaration in the above example is a chain of functions. The possible functions that you can use are:

Example with preFilter

var viz = d3
  .maptable('#vizContainer')
  .json('dir_data.json', (d) => parseInt(d.traffic) > 0)
  .map({ path: 'countries.json' })
  .render();

Import datasets

Datasets can be defined by using one of the these three sources:

<a name="viz-json">#</a> viz.json(url)

Import JSON file at the specified url with the mime type "application/json".

<a name="viz-csv">#</a> viz.csv(url)

Import CSV file at the specified url with the mime type "text/csv".

<a name="viz-tsv">#</a> viz.tsv(url)

Import TSV file at the specified url with the mime type "text/tab-separated-values".

Map datasets

To plot lands and countries on the map, we're using TopoJSON library. The map can be generated through this tool: topojson-map-generator.

Dataset requirements

In order to plot your dataset on a map, there are minimum set of columns needed.

If you're planning to add markers on your map, you would need to provide latitude, longitude of your markers. You can also edit these keys name using the map options longitudeKey, latitudeKey.

[
  { "longitude": "13.23000", "latitude": "-8.85000" },
  { "longitude": "168.32000", "latitude": "-17.75000" }
]

If you're planing to add country related information, you should provide consistent country information on your dataset from the TopJSON file. You should provide at least one of these types on your mapOptions:

For example for this dataset:

[
  { "country_code": "MAR", "Country Name": "Morocco", "bar": "foo" },
  { "country_code": "FRA", "Country Name": "France", "bar": "foo" }
]

You would use these options:

{
  countryIdentifierKey: 'country_code',
  countryIdentifierType: 'iso_a3'
}

or

{
  countryIdentifierKey: 'Country Name',
  countryIdentifierType: 'name'
}

Columns details

By default, MapTable imports all the columns and detects their format automatically. As well, you can customize behaviors of specific columns and create virtual columns.

# viz.columns(columnDetails) with columnDetails as a JS dictionary. You can add/remove it of you want to customize your columns or create virtual columns based on the data.

columnsDetails format

Example (adding nowrap and type to the region column key):

.columns({
  region: {
    nowrap: true,
    filterMethod: 'dropdown'
  }
})

Naming conventions

For the below examples, we define viz as the variable that loads MapTable.

Functions that have d as parameter, means that d is a JS dictionary that contains data for one row.

Functions that have groupedData as parameter, means that groupedData is a JS dictionary { key: 'groupedByKey', values: [ {d}, ... ] } that contains the key that have been used to group the data, and the matching values related to that grouping.

Map

#viz.map(mapOptions) with mapOptions as a JS dictionary. You can add/remove it of you want a map on your visualization.

Options

Filters

# viz.filters(options) with filtersOptions as a JS dictionary. You can add/remove it of you want filters on your visualization.

Options

Table

If you want to add a table on your visualization:

# viz.table(tableOptions) with tableOptions as a JS dictionary. You can add/remove it of you want a table on your visualization.

Options

Export as SVG

You can enable this feature via exportSvg and set it to a URL. This will allow users download the map on their computer as an SVG. However, you would need to set up a server endpoint that is going to allow users download the SVG file.

The sample code for a PHP server is located in /server/exportSvg.php. Contributions are welcomed for implementations of in other languages.

In the version 1.4.0 exportSvgClient was added to use only the browser to export the SVG.

Credits

Contribute

You are welcomed to fork the project and make pull requests.

Set up your development environment

Requirements

Install any items with "sudo":

Getting Started

Run these commands as your unprivileged user you're doing your development as:

  1. Run nvm install 16 to install node 16
  2. Run nvm use 16 to use node 16
  3. Run npm config set python $(which python) to use set the python path
  4. Run npm install to install dependencies
  5. Run npm run dev to start the local dev environment on http://localhost:5000
  6. Edit files in ./dev and they will be automatically compiled to ./src
  7. To have production ready files, run: gulp dist. All built files are located in the folder ./dist
  8. Enjoy 🍻

Release History