JavaScript library for creating beautifully simple maps in seconds
Clone or download

Readme.md

Pinpoint

A JavaScript library for creating beautifully simple maps in seconds, developed at The Wall Street Journal.

Features

  • Map settings are stored in a simple JSON format and can be generated using Pinpoint Editor.
  • Fully responsive with touch-friendly "click-to-activate" behaviour.
  • Powered by the awesome Leaflet.js.

Quickstart

Include:

In terms of HTML, just a single div is needed:

<div class="map-container"></div>

Then in your JavaScript file:

var options = {
    "element": ".map-container",
    "aspect-ratio": "wide",
    "dek": "",
    "hed": "The U.K.",
    "lat": 51.5049378,
    "lon": -0.0870377,
    "minimap": false,
    "zoom": 4,
    "markers": [
        {
            "lat": 51.5049378,
            "lon": -0.0870377,
            "text": "London"
        }
    ]
};
var map = new Pinpoint( options );

Options

Pinpoint accepts a JavaScript object for configuration.

option type default description
element string "#map-el" CSS selector for map parent element.
aspect-ratio string (required) The shape of the map: "wide" (3x2), "square" (1x1), or "tall" (5x6)
lat number (required) Latitude for map centre.
lon number (required) Longitude for map centre.
markers array (required) Array of markers/icons on map (see below for details).
zoom number (required) Initial zoom level of map.
hed string (blank) Headline for map (optional).
dek string (blank) Dek for map (optional).
note string (blank) Note to go below map (optional).
minimap boolean false Set to true to enables zoomed-out smaller map in corner.
minimap-zoom-offset number -5 Zoom level of minimap relative to main map zoom. Should always be below 0.
basemap string "http://{s}.tile.osm.org/{z}/{x}/{y}.png" Leaflet tile layer URL template (optional)
basemapCredit string "Leaflet | © OpenStreetMap contributors" Credit for tilelayer. Goes at bottom, below note. (optional)
creation boolean false Set to `true tot enables "creation mode" for use in admin tool.
dragend function undefined Anonymous function called on Leaflet dragend event (ie. when dragging/panning map).
zoomend function undefined Anonymous function called on Leaflet zoomend event (ie. when zooming).
markerdragend function undefined Anonymous function called on Leaflet marker dragend event (ie. when dragging a marker around the map). Only works when creation is true.

Marker options

Markers are stored as an array of objects.

option type default description
lat number (required) Latitude of point.
lon number (required) Longitude of point.
text string (blank) Text for marker callout.
icon string "square" Marker icon style: "circle", "square" or "none".
label string "callout" Marker label style: "callout" or "plain".
label-direction string "north" Marker label direction. Available directions varies between label styles.

Example configuration JSON

{
    "aspect-ratio": "wide",
    "dek": "",
    "hed": "The U.K.",
    "lat": 51.5049378,
    "lon": -0.0870377,
    "minimap": false,
    "minimap-zoom-offset": -5,
    "zoom": 4,
    "markers": [
        {
            "icon": "circle",
            "label": "plain",
            "label-direction": "north",
            "lat": 51.5049378,
            "lon": -0.0870377,
            "text": "London"
        },
        {
            "icon": "circle",
            "label": "plain",
            "label-direction": "north",
            "lat": 53.4779669,
            "lon": -2.0613722,
            "text": "Manchester"
        }
    ]
}

Public methods

  • .remove(): Reset map container to empty element.

Compiling dist folder

You must have npm and grunt installed.

  • npm install
  • grunt (this will also run tests)

Note that the images in src/img are not auto-compiled - if they're changed, the SVG code will need to be copied into pinpoint.js.

Customising styles

The look of the map and its markers is mostly controlled with CSS/SASS. These files can be found in src/scss:

  • main: Head and deck, scale line style
  • overlay: "Zoom/pan" icon
  • markers: Square, circle and plain/invisible marker styles
  • marker-label-callout: Callout label with north and south styles
  • marker-label-plain: Plain label with N, NE, E, SE, S, SW, W and NW styles
  • geojson: Styles for geojson objects

To change the map's basemap/tilelayer, use the basemap configuration variable. See above for more details.

Running tests

Tests are carried out with QUnit. To run tests, either open the HTML files in the test/ folder individually, or install NPM and Grunt (see above for details) and run grunt test.

Changelog

v1.1.1 (July 17, 2015)

  • Fixed marker position bug

v1.1.0 (July 17, 2015)

  • Removed jQuery dependency

v1.0.1 (July 9, 2015)

  • Fix bug when no head or deck
  • Throw useful error if Leaflet is missing
  • Add basic tests

v1.0.0

  • Initial release