A Leaflet-based mapping application, built with NodeJS, Grunt, jQuery and SASS

Demonstration

Authors:

• Ray Walker
• Iris Maertens
• Remy Bertot

This application is intended to be re-used for multiple Greenpeace maps, initially for displaying shipping information, but ultimately for any page where a map can better display information.

It has been designed to be mobile-ready and responsive, as well as infinitely configurable.
Nearly every visual element can be currently be easily adjusted via JSON, and in upcoming versions will be configured via a web form and upload scripts.

To develop or build the application, firstly you'll need to install git and then clone the repository to a local folder with git clone https://github.com/greenpeace/p3_ship-map

Next, ensure you have NodeJS installed, and from the root directory of the newly cloned repository run npm install

This will download and install all development dependencies.

Since the application relies on many external libraries, the Bower package manager is used to either update or lock versions.

bower install will download all and save into /bower_components/ all the third party packages which are used by the front-end application.

From there run grunt copy:bowerJS and grunt copy:bowerCSS, which will copy the required files to the relevant sections of the /src folder, ready for further processing by Grunt in development

To check for updates and download the latest versions at any time, use bower update

• /.sassrc.json: This contains image dimensions for the popups and icons displayed on the map. The values here are used when Grunticon generates PNGs from SVG, as well as in the SASS variables.scss configuration file. edit these values to suit
• /src : Contains the raw source files to be edited, make changes here
• /src/css: Don't edit these CSS files, these are automatically generated by SASS from the /src/scss folder
• /src/scss: This contains the source SCSS files, make changes here
• /src/img: Source images. Note that the subfolder structure is important
• /src/img/features: Images for map popups go in here, making sure the names of the files match the names in the source Excel spreadsheet.
• /src/img/icon: Images for the map main icons go in here, in both legend (used in sidemenu and edge markers) and map sizes
• /src/xlsx: Source Excel spreadsheets containing feature information
• /app: Grunt places processed files in here. This folder is deleted and rebuilt automatically when a full grunt build is run. The files in this folder are processed but only partially optimised. Since minification is the slowest task, nothing is minified during the standard development workflow, and being un-obfuscated code this also makes for easier debugging.
• /dist: Minified and fully optimised, these are the files to be served to end-users.
• /test: The testing JSON, held here until an API is developed to serve responses based on query parameters

grunt watch is a multitask which monitors changes in the /src/ directory and executes tasks relevant to the changed files.

For example, if you edit a Javascript file while Grunt is watching, it will:

• check code quality with jshint and warn if it finds any errors
• concatenate the contents of the leaflet and plugins folders, and
• copy those files to the /app/ folder

The default task grunt will do almost everything you require to build the application from source:

• Parse excel, generate output JSON
• Parse the /.sassrc.json file and update SASS accordingly
• Compile SCSS files to CSS
• Optimise SVG files, convert them to standard and retina-ready PNG files
• Create CSS classes with the images as backgrounds
• Concatenate CSS files to one style.css, plus six more for either data-PNG, data-SVG or url formats for standard and retina-ready displays
• Checks and concatenates javascript
• Builds a custom Modernizr script
• Copies all output to the /app/ folder

not included in grunt watch, must be run separately

grunt modernizr

Grunt-modernizr is used to scan references to Modernizr tests in all source JS and SCSS files, it will then download a custom-built Modernizr with only the requisite tests and methods.

Custom tests may be added to the /src/js/vendor/modernizr/tests/ folder and they will be automatically incorporated.

not included in grunt watch, must be run separately

grunt svg

• Reads /src/img/ for .svg files
• Removes width and height (see Intrinsic SVG Sizing)
• Optimises the SVG files by removing unnecessary information using grunt-svgmin
• Uses Grunticon to convert SVG to PNG in standard and retina-ready sizes, based on size information in /.sassrc.json
• Creates three different background image class stylesheets: both SVG and PNG data-uri format, as well as plain URL. The main application javascript detects browsercapabilities on initalisation using Modernizr and loads the optimal stylesheet.
• Copies the output to /app/img/

not included in grunt watch, must be run separately

grunt buildjson

• Reads json from all excel files in /src/xlsx
• Converts each file to JSON, supports multiple sheets, saves output to /test/json/$filename
• Parses the JSON into map-ready data
• Converts twitter @usernames and #hashtags to links
• Converts text links to clickable links using html-linkify
• Adds image path information and '.jpg' suffix
• (@todo - a smarter way of handling images, since they might be gif, jpeg, png etc

• Finalise the JSON generation Currently while the buildjson script expects existing ship information in the output JSON, as there is nowhere the provided Excel spreadsheet which identifies the name of the ship, without which no human-readable ship identifiers can be generated. An extremely simple form could accomplish this. Input ship name, uploading the spreadsheet, uploading images, choose colours, and then the grunt tasks can do the rest.

• Geolocation for centering the map on load Leaflet supports geolocation natively, but the implementation is clumsy - if the geolocation fails then it defaults to showing the whole world. A combination of default map center & zoom combined with Modernizr.geolocation check might smooth the UX here. Can specify geolocation disabled in JSON response.

• Mobile browser popup layouts Iris has provided additional layouts for popups on low-width screens

• Mobile browser testing and fixes The application is designed from the ground up to be responsive, however media-queries for small browser sizes have not yet been implemented.

• Implement an image manipulation library: The source images need to be adjusted to suit the small file size

• Modal lightbox for viewing images in popups at a larger size

• Conversion to webp images for supported browsers

• Internet Explorer and rare browser testing

• Select an alternate tileset. Cloudmade is shutting down services from 1st May 2014, so an alternate arrangement is required.

• Implement Leaflet.textpath path decoration, eg name of the ship, direction indicators