Guide to the code

Trademapper is a pure client side web app - the browser downloads the HTML, CSS and javascript files and runs them all in the browser. If you load a CSV file into trademapper then it is processed, filtered, aggregated and displayed by javascript in the browser and the data never leaves the browser.

The Javascript App

Overview

The javascript is loaded using RequireJS - the index.html file loads require.js and tells it to use main.js which then requires/loads the other files.

The app heavily uses d3.js and those files are in trademapper/js/lib/

The core of trademapper is in the trademapper.*.js files - this is where we draw the map, import and process the CSV data, produce the form to filter the data, filter the data, and draw the filtered data on the map. This page gives an overview of the files - there is some more detailed information at the top of each of the files.

trademapper.js

trademapper.js is the main file - it loads and configures the other trademapper files, including setting callbacks. It is set up by calling the init() function - see the file itself for details. The config has default values which can be seen in the object in config.js. The init function also checks the URL parameters, as detailed in How to use Trademapper.

trademapper.arrows.js

This code draws the arrows and points on the map based on the data in a RouteCollection and PointRoles.

trademapper.csv.js

This code reads in the CSV file and does aggregation and filtering of the data to convert it into a RouteCollection and PointRoles which are then used to draw the arrows.

trademapper.csv.definition.js

This contains mappings for different types of CSV file that lets them be parsed into meaningful data.

trademapper.filterform.js

This code produces the form used to filter the data, and processes changes in the form

trademapper.mapper.js

This code draws the map itself and also implements the pan and zoom functionality.

trademapper.route.js

This code defines various data structures used elsewhere, including various types of Point, RolesCollection, Route and RouteCollection.

spiralTree.js

This code draws the arrows as a flowmap - so the path can start as a single path, and then sub-paths split off as the path nears its destination.

This functionality isn't working at the moment, but the code is left in for future improvement.

util.js

A handful of utility code.

map js files

The following js files basically just contain map-related data as JSON

• worldmap.js - the country borders.
• disputedareas.js - the parts of the world claimed by more than one country.
• countrycentre.js - a latitude/longitude point for each country in the world, indexed by the two letter country code.
• ports.js - air and seaport data.

Data

See the page about using TradeMapper.

Other code

Pre Processing Map Data

This is in the mapdata/ directory. The extract_world.sh script processes the shape files we download from http://www.naturalearthdata.com/ to convert it to geojson and then to topojson. It needs ogr2ogr and topojson to be available if you want to run it - though you shouldn't need to run it.

The simplify_topology script can be used to simplify topojson files so they can be loaded more efficiently as layers.

The convert_ports_csv script is for converting port data in CSV format into JavaScript, so that it can be searched more quickly and easily. See the top of that file for the required CSV format.

Reusing the code

TradeMapper is designed so it can be included in other sites. With your own HTML file, CSS and a main.js file, you can pull in the rest of TradeMapper and have it embedded in your own site.

TODO: How to reuse

Terms of reuse

Code originally written for TradeMapper is licensed under the GPLv3.

To find the origin and licenses of code not originally written for trademapper, see the project COPYING file - this file also records which files are redistributed by trademapper and which are written for TradeMapper.