BRC Atlas library

The BRC Atlas library is a Javascript library for providing both easy and flexible APIs for creating static and slippy maps for atlas projects. In fact there are two libraries packaged in one project - one for British atlas mapping (brcatlas.umd.js) and one for European atlas mapping (brcatlas_e.umd.js).

Installing

You can get the javscript amd css builds from the GitHub repo or include them in code directly from a CDN, e.g:

<script src="https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/dist/brcatlas.umd.js"></script>

or a minified version generated by the CDN:

<script src="https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/dist/brcatlas.umd.min.js"></script>

You will also need to inlcude the associated CSS, e.g:

<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/dist/brcatlas.umd.css">

or a minified version generated by the CDN:

<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/dist/brcatlas.umd.min.css">

The CDN also exposes some geojson assets. These are used internally by the mapping libraries, but can be used independently. They include:

• An outline map of Britain, Ireland and the Channel islands. These polygons are at a coarse scale - suitable for using with the static map. (https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/assets/GB-I-CI-27700-reduced.geojson).
• British & Irish 100 km grid lines. These lines are at a coarse scale - suitable for using with the static map. (https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/assets/GB-I-grid-27700-reduced.geojson).
• Brtish & Irish country boudaries. These lines are at a coarse scale - suitable for using with the static map. (https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/assets/GB-I-countries-27700-reduced.geojson).
• Brtish & Irish vice county boundaries. These polygons are at a coarse scale - suitable for using with the static map. (https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/assets/GB-I-vcs-27700-reduced.geojson).
• A range of geojson country and vice county boundary outlines in the folders https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/assets/country and https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/assets/vc. These are defined at a number of scales suitable for different zoom levels on the slippy map. For more information, see README for country assets and README for vice county assets.

API documentation and code examples

For details of the API, view the JSDoc API documentation.

There are also a number of working examples.

Notes for developers

Installing to development environment

This project is configured as a Node project. To install and run it in a local development environment you will first need to install Node and the Node Package Manager (npm) on your computer. Then clone the repository from GitHub and in the root project folder run npm install. That will install all the Node package dependencies into a folder called ‘node_modules’. Note that this large folder should not be committed to the repository - hece a line in the root .gitignore folder to exclude it.

Assets

There are a number of geojson files in the assets folder. These are loaded by the code when needed. In the development environment, it will often be the case that these assets need to be loaded from the local environment but in the live environment, they need to be loaded from the CDN. You can edit the code in src/constants.hs & src_e/e_constants.js, as indicated by inline comments, to make sure the assets are being loaded correctly.

Documentation

The package uses JSDoc to produce the API documentation. JSDoc is not included in the package dependendies since developers normally install it globally in their development environment.

Two libraries in one package

There are two libraries in this package:

• dist/brcatlas.umd.js - for atlas mapping in Britain and Ireland
• dist/brcatlas_e.umd.js - for atlas mapping over Europe

Although these libraries are bundled here in the same package, they are essentially different projects without any interdependendies.

Typical build & publish workflow

• npm audit --omit=dev (look for any important vulnerabilities)
• npm run lint
• npm run docs
• Update the version number in package.json
• Ensure that src/constants.hs & src_e/e_constants.js are set up correctly (i.e. for production - not development)
• npm run build (after package update so that correct version is printed to console by library)
• Update docs/Readme (if required, e.g. to link new examples)
• Git add any new files, e.g. git add *
• Git commit all changes, e.g. git commit -a
• Git tag <version>, e.g. git tag 1.2.1. Tag must match version number in package (to ensure that version can be used to target it in CDN)
• Git push origin <version>, e.g. git push origin 1.2.1 (pushes the tag commit)
• git push (pushes to master branch)
• Run the following links to purge the jsdelivr CDN caches
  • https://purge.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas@latest/dist/brcatlas.umd.js
  • https://purge.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas@latest/dist/brcatlas.umd.css

Rollup

Rollup is used to build the transpiled library javascript assets for this package. Rollup is often preferred over webpack or other bundling tools for packaging libraries. The following javascript assets are produced by this rollup configuration:

• brcatlas.umd.js: this is the browser-friendly javascript for the Britain & Ireland atlas library which can be used from browsers (supports a couple of different export formats).
• brcatlas.umd.min.js: same as previous but minified.
• brcatlas.umd.min.js.map: this is a javascript map file. It can be used alonside the minified file to help with debugging.
• brcatlas.umd.css: consolidated CSS file containing all project CSS for the Britain & Ireland atlas library.
• brcatlas_e.umd.js: this is the browser-friendly javascript for the European atlas library which can be used from browsers (supports a couple of different export formats).
• brcatlas_e.umd.min.js: same as previous but minified.
• brcatlas_e.umd.min.js.map: this is a javascript map file. It can be used alonside the minified file to help with debugging.
• brcatlas_e.umd.css: consolidated CSS file containing all project CSS for the European atlas library.

The following rollup plugins are used in the build:

• @rollup/plugin-node-resolve: this allows rollup to resolve references to node libraries (in node_modules).
• @rollup/plugin-commonjs: this allows rollup to convert CommonJS modules to ES6.
• @rollup/plugin-babel: this is what allows rollup to transpile ES6/7 code to ES5 (for the browser packaging). This plugin has dependencies on ‘@babel/core’ and ‘@babel/preset-env’ which are included in the project’s node package.
• rollup-plugin-terser: this is used to produce the minified file.
• rollup-plugin-css: for rolling up CSS into a single file.
• rollup-plugin-json: for importing package JSON.

Other files in project

The following files are in the root folder:

• README.md: this readme file.
• index.js: the entry point for the rollup build.
• package.json: the Node package file for this project.
• package-lock.json: the Node package lock file for this project.
• _config.yml: used by GitHub pages to configure github pages
• .eslintrc.json: configures ESLint. These some stuff in here that’s necessary to get jest and eslint to play nicely together.
• babel.config.js: the configuration in here seems to necessary to get Jest to work properly with ES2015 modules.
• rollup.config.js: rollup configuration.
• .gitignore: a Git file to exclude certain files/folders from the repository.