Using the BRC Atlas Library

Create a map from a div tag

The simplest way to use the brcatlas library to put a map in a web page is use a div tag with data attributes to display a prepared CSV file.

First include the required Javascript libraries and CSS in the page. We need the BRC Atlas JS libary, the associated CSS and the D3 library which is an external external dependency of the BRC Atlas library. In this example they are all included from CDNs.

    <script src="https://d3js.org/d3.v7.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/dist/brcatlas.umd.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/biologicalrecordscentre/brc-atlas/dist/brcatlas.umd.css"></script>

Now you can create a map like this:

      <div id="ex1" class="brcatlas" data-csv="example-hectads-1.csv"></div>

This is what you see:

The div should include a unique id, the class brcaltas and, if you want to display some data, the data-csv attribute pointing to a correctly formatted CSV file (see below). This normally this CSV file would sit somewhere on your website's server.

The CSV file should have the column headers shown in the table below.

gr	shape	colour	opacity	size
HU58	circle	red	1	1
J33	square	#5eeb34	0.8	0.9
WA50	triangle-up	green	0.5	0.7
SC37	triangle-up	green	1	1
SE68	triangle-down	green	1	1
SD64	diamond	green	1	1

The order of the columns is not important. Note the following:

Grid references in the CSV must all be of the same precision (in the example above they are all hectads (10x10 km), but include mixed British, Irish and Channel Island references).
The remaining columns define the appearance of each individual dot in terms of shape, colour, size and opacity.
Shape can be either 'circle', 'square', 'triangle-up', 'triangle-down' or 'diamond'.
Colour is either a string specifying a web colour, e.g. 'red', or a hex code starting with the '#' symbol.
Opacity is a number between 0 and 1 where 1 is maximum opacity and 0 minimum.
Scale is a number between 0 and 1 which can be used to adjust the size of the displayed symbol between it's maximum (1) and minimum (0).

You can also display CSV files containing either tetrads (2x2 km) or monads (1x1 km). If you do this, you must include the 'data-precision' attribute and set it to either 2000 for tetrads or '1000' for monads.

On the static map there is an options symbol at the bottom-right of the map that, when clicked, invokes a dialog where the user can change the appearance of the map by selecting a view with or without 'insets' for the Northern Isles and Channel Islands. You can remove this symbol by specifying 'data-opts="false"'. You can also specify which of the four display options you want to initialise the map with by specifying the 'data-trans' option. You can set it to one of the following options:

BI1: No insets
BI2: Channel Islands inset
BI3: Northern Isle inset (Channel Islands not shown)
BI4: Northern Isle and Channel Islands inset

      <div 
    id="ex2" 
    class="brcatlas" 
    data-csv="example-hectads-1.csv"
    data-opts="false"
    data-trans="BI4"
></div>

The default map is a 'static', map of the type shown above, but you can also create a slippy (Leaflet) map by specifying 'data-slippy="true"'.

<div 
    id="ex3" 
    class="brcatlas" 
    data-csv="example-hectads-1.csv"
    data-slippy="true"
></div>

Note that to create the slippy map, you will need to include the Leaflet libraries:

      <script src="https://unpkg.com/leaflet@1.7.1/dist/leaflet.js"></script>
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.7.1/dist/leaflet.css"></script>

Change the size of the map with the 'data-height' and 'data-width' attributes. Note that for static map, width is calculated automatically from the height, so you only need to specify height for that type of map.

<div 
    id="ex4" 
    class="brcatlas" 
    data-csv="example-hectads-1.csv"
    data-slippy="true"
    data-width="700"
    data-height="400"
></div>

You can also specify a legend to be displayed on the map. Obviously this should reflect the colours, shapes, opacity etc that you used for the dots in the CSV (though it doesn't in the example below).

      <div 
    id="ex5" 
    class="brcatlas" 
    data-csv="example-hectads-1.csv"
    data-height="500"
    data-trans="BI4"
    data-legend="true"
    data-legend-title="This is my legend"
    data-legend-lines="Blah; circle; red | Blah blah; circle; magenta | Blah blah blah; circle; green"
    data-legend-x="10"
    data-legend-y="10"
    data-legend-scale="0.8"
    data-legend-opacity="0.8"
></div>

The 'data-legend' must be set to 'true' to display any sort of legend. Use 'data-legend-title' to specify a title for the legend. Use 'data-legend-lines' to specify the individual lines in legend. Each line should be separated with the '|' (pipe) character. Then each line consists of a string of the format 'caption; shape; colour'. Shape and colour use the same values as can be used in the CSV file (see above). The 'data-legend-x' and 'data-legend-y' attributes can be used to specify and offset from the left and top margins of the map. The attribute 'data-legend-scale' specifies a number between 0 and 1 used to scale the entire lagend - useful if it is too big for the map. The attribute 'data-legend-opacity' should be set to a value between 0 and 1 which specifies and the overall opacity of the legend.