Skip to content
This repository has been archived by the owner on Apr 3, 2021. It is now read-only.

Latest commit

 

History

History
159 lines (99 loc) · 5.42 KB

README.md

File metadata and controls

159 lines (99 loc) · 5.42 KB

Note: As of 2021, this tool has been deprecated and the repository is no longer being maintained.

Pinpoint Editor

Pinpoint Editor is a web app for quickly creating and editing Pinpoint maps.

Features:

  • Simple user interface allows maps to be created in seconds.
  • Flexible Angular app with Node backend.
  • Built-in support for uploading JSON data files to Amazon S3.

How to set up Pinpoint Editor

Pinpoint Editor requires:

  • A node.js server
  • A PostgresSQL database
  • NPM and Bower for installing dependencies
  • (optional) Amazon S3 to host data

Here's how to install it locally:

Note: If you have trouble setting up Pinpoint Editor, please open a ticket on GitHub.

  1. Install required software

    If on OS X, you can install all software using these commands:

     # Install Brew
     ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
    
     # Install NodeJS.
     brew install node
    
     # Install PostgreSQL.
     brew install postgresql
    
     # Install Bower.
     npm install bower
    
  2. Set up database

    Create a PostgresSQL database. You can name it anything you like.

     createdb pinpointDb
    

    Set DATABASE_URL environment variable.

     export DATABASE_URL='postgresql://localhost/pinpointDb'
    

    Run migration script to set up table and load examples.

     psql $DATABASE_URL < build/migrate.sql
    

    You may need to start the database server manually:

     pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start
    
  3. Install dependencies

     # Install server-side dependencies
     npm install
    
     # Install client-side dependencies
     bower install
    
  4. Configure settings

    Generate a new Google Maps API key by following these instructions and add it to config.json (under the googleMapsAPIKey property).

    Optional: To enable AWS S3 export, set these environment variables:

     export AWS_S3_KEY='XXXXXXXXXXXXXX'
     export AWS_S3_SECRET='XXXXXXXXXXXXXX'
     export AWS_BUCKET='XXXXXXXXXXXXXX'
    
  5. Run the server!

     node server.js
    

    You will then be able to access Pinpoint at http://localhost:3001.

Docker setup

If you have Docker installed you can run the Pinpoint editor by simply typing docker-compose up. You can then access Pinpoint at http://localhost:3001.

Architecture

On the server, Pinpoint uses the minimal Express framework for routing. Data is stored as JSON using PostgresSQL's native JSON data type, which can then be accessed via a simple API (see below for details). Data can then be exported to S3-hosted static JSON for production use.

On the client, Pinpoint is an Angular app made up of multiple custom directives. Key files are script.js and directives/map-detail.html. Dependencies are managed using Bower.

API routes

  • Get all maps GET - /api/maps
  • Get map by id GET - /api/maps/:id
  • Create map POST - /api/maps/
    • http request header must be Content-Type: application/json
    • http request body contains the entire data object for that record
    • returns HTTP/1.1 201 Created - {"id": id, "message": "Map created"}
  • Update map PUT - /api/maps/:id
    • http request header must be Content-Type: application/json
    • http request body contains the entire data object for that record
    • returns HTTP/1.1 200 OK - {"message": "Map updated"}

Configuration file

Various settings are controlled via config.json. See config-example.json for dummy values.

Editor interface options

  • googleMapsAPIKey: (required) Google maps API key (get one here)
  • title: Page title, e.g. The Example Journal Map Tool
  • greeting: Message to go beneath page title. HTML is allowed.
  • helpLink: URL of an external help page
  • previewLink: URL which, with the current map's slug on the end, links to a preview
  • liveLink: URL which, with the current map's slug on the end, links to the live production page for the current map
  • s3url: URL which, with the current map's slug (and ".json") on the end, links to the S3-hosted static JSON
  • geojsonStyles: Array
    • Object
      • class: css class for style (string) - eg. "dashed-clockwise"
      • name: descriptive name for style (string) - eg. "Dashed, animated clockwise"

Map setting options

These are used in all Pinpoint instances in the editor.

  • basemap: Leaflet tilelayer URL (string) - eg. "http://{s}.somedomain.com/blabla/{z}/{x}/{y}.png"
  • basemapCredit: Credit line for tilelayer - eg. "Leaflet | © Mapbox | © OpenSteetMap contributors"

Version history

v1.2.1 (27 March, 2017)

  • Bugfixes for editor interface

v1.2.0 (17 February, 2017)

  • New feature: basemap selection
  • Google maps API key controlled via config.json
  • Easier customisation of interface text via config.json
  • Add pagination to homepage

v1.1.0 (17 July, 2015)

  • Update bower.json to allow any 1.1.* versions of Pinpoint library
  • Add .bowerrc to fix bower_components location
  • Add helpful error message if server port is in use

v1.0.1

  • Update bower.json to allow any 1.0.* versions of Pinpoint library

v1.0.0

  • Initial release