Development

How we run development

TradeMapper is open source and our preferred method for contributions is pull requests. For discussion etc we have a google group.

What you need for development

As TradeMapper is a single page client side web app, the main things you need in order to write and try out code for TradeMapper are:

• a web browser - we tend to use Firefox and Chrome - though it should work on any modern web browser.
• a text editor - at least with syntax highlighting
• git - so you can get the code and contribute your changes back
• (ideally) a basic web server - in our experience trademapper itself runs by loading the files directly from the filesystem, but the tests need a local web server to run properly.

Build Tools

• Node.js is required to run the npm package manager. You can check if you have Node installed via the command line using node --version. Otherwise, you can install Node from here: http://nodejs.org/
• Grunt.js [http://gruntjs.com/] is used as a front-end task manager. To install Grunt run npm install -g grunt-cli [if npm throws errors you may need to use sudo npm install -g grunt-cli]. Once you have the Grunt CLI installed globally, navigate to your trademapper root folder via the command line and run npm install. This will download Trademapper's Grunt instance and other necessary packages.
• Sass Trademapper uses the Sass css pre-processor. You will need to install Sass to edit Trademapper styling [http://sass-lang.com/install]. Sass watch currently runs on the default grunt task grunt.

Get the code

If you just want to play with the code locally then:

git clone https://github.com/trademapper/trademapper-js

See the github set up git page if you need help.

If you want to contribute back, then please fork our repository and then send us a pull request.

Get the data

We include one file in CITES format - cites_unicorn.csv - that you can play with. You can download further CITES data from http://trade.cites.org/ and upload it.

We hope to give access to other data soon.

Run the code

We host the code at http://trademapper.co.uk/ so you can have a quick play there.

Once you have a clone of the code (see above), copy trademapper/js/configextra.default.js to trademapper/js/configextra.js (this file configures the Google Analytics tracking ID; in development, you don't need to edit it as no analytics data is collected, but the file does need to be present).

Once you've done this, you can just open the trademapper/index.html file in your web browser - it should then load all the required CSS and javascript files so you can start using TradeMapper.

Local web server

You can also set up a local web server to serve the files on a local port. There are many ways to do it, but here are two simple ones:

Python web server

If you have python installed (and it should be there by default on Max OS X and Linux) then you can open a terminal in the trademapper/ directory and run:

python -m SimpleHTTPServer 8080

And then point your web browser at http://localhost:8080/

Mongoose (for Windows)

Mongoose is a simple Windows application that you can point at a directory and it will server on port 8080 - so you can view the files at http://localhost:8080/

Running Tests

The tests use QUnit. From our tests you need a local web server running for the tests to run successfully. If you move your web server up one directory, then (if using port 8080) the tests can be run by loading http://localhost:8080/tests/test_runner.html while trademapper itself would be at http://localhost:8080/trademapper/

Front end builds

Build directory

Please note that the assets in the build directory are compiled files and should not be directly edited. To edit styles and add or update images please edit only the corresponding source files in the resources folder and then use grunt to build the compiled files.

Grunt commands

grunt runs sass, watch, copy and dist tasks.

Distributable build

Running grunt dist will create a distributable version of the app in the dist/ directory. To deploy the application, you should copy the files from inside the dist/ directory to your web server's docroot (or equivalent if not using Apache).

If you want to activate Google Analytics in your deployed version of the application, edit the trademapper/js/configextra.js file in the dist/ directory, setting the trackingId variable to your Google Analytics tracking ID, before pushing that file to your web server.