One of the main reason for adding a map is to highlight features, and the easiest way to do that is using markers on the map. If you use a single marker it will be used as the centre point for the map. If you use multiple markers, the map will be scaled and centred automatically to accommodate all markers.
Markers locations can be specified either as a latitude, longitude pair or as an OS 6, 8 or 10 figure grid reference. OS grid references must include the two letter prefix, not just the numbers.
There are two different ways to add markers to the map
Markers defined in the shortcode
Use the markers shortcode attribute to define your marker(s). As a minimum you need to define the marker location, either as an OS grid reference or a latitude,longitude pair. If you are adding multiple markers you need to separate them using the | character (bottom left corner of the UK keyboard). For example markers="SH6099054380|SH6564658285"
In addition to the location you can also specify the marker colour and some text to go in a popup which opens when the marker is clicked. You can also specify a layer for the marker if you are using layers, but you won’t need that in most cases. Location is the only mandatory item. You can add the other options using the appropriate leading character, and they must be in this order:
- Location
- $layer
- !colour
- ;description
Simple markers example
In this example I’ve added two markers. The first location is for Snowdon, and I’ve added popup text preceded by ; The second location is Glyder Fach, and I’ve specified a green marker (preceded by !) and some text for the popup.
[osmap markers="SH6099054380;Snowdon|SH6564658285!green;Glyder Fach"]
Marker Colours
The default marker is a mid blue colour. You can also select one of nine specific colour names – if you try anything else you will get the default blue marker. Valid colours are: red, orange, yellow, green, blue, violet, gold, grey, black.
Also available are numbered markers in the range 1-30, and letter markers from A-Z. You select these using the color attribute too, even though they aren’t colours.
Using HTML in the description
The popup text is usually plain text, but it can be HTML if you prefer. HTML is difficult to add to a shortcode reliably, particularly using the WordPress block editor, and I recommend using marker files instead. The main pitfall is that HTML often requires quotes, and the shortcode itself requires quotes, so there is an inherent conflict.
Using a Marker File
Defining markers in the shortcode works for a few simple markers, but is hard work when you have a lot of markers. A much easier method is to use a separate marker file to define them. You can create the file using a simple text editor (e.g. Windows Notepad) and upload the file to your WordPress media library. You then refer to the text file in your shortcode using the markerfile attribute with the URL of the text file.[osmap markerfile="https://example.com/wp-content/uploads/my-markers.txt"] or[osmap markerfile="https://example.com/wp-content/uploads/my-markers.json"]
Two forms of marker file are supported. For new files we recommend the JSON format as it is more easily extended in future. JSON files must use a .json file extension so that the plugin can distinguish which format is in use.
Original format marker files
You can create simple marker files using the exact same format as is used directly in the shortcode. Each marker is on a separate line in the file.
SH6099054380;Snowdon
SH6564658285!red;Glyder Fach
SH705546!green;Carnedd Moel Siabod
JSON format marker files
JSON (Javascript Object Notation) is a universal data format where the information is identified using keys and values. This makes it easier to add new features in future without inventing more obscure ways of separating the various parts. JSON files do have to follow some specific rules, but they are fairly straightforward. The JSON equivalent of the simple file looks like this:
[
{ "location": "SH6099054380", "desc": "Snowdon" },
{ "location": "SH6564658285", "desc": "Glyder Fach", "color": "red" },
{ "location": "SH705546", "desc": "Carnedd Moel Siabod", "color": "green" }
]
Both keys and values must be in double quotes. You can safely use single quotes within a value. Key and value are separated by : and there is a comma between each key-value pair, but no trailing comma.
The keys supported by the plugin are
"location"
"layer""
"color"
"desc"
If other keys are present they will be ignored when generating the map, although other plugins or filters may use the extra data.
There are many online sites which will validate your JSON files and some will compress them by removing all unnecessary spaces and line breaks, e.g. Code Beautify. There are also sites which will convert CSV data from a spreadsheet to JSON, using the first line as the key values, e.g. Convert CSV.
Adding a Marker List
If you wish to add a list of markers below the map, you can do this by adding marker_link="auto" to the map shortcode. This will generate a list using the marker ‘desc’ field. Each item will be turned into a link which, when clicked, centres the map on that marker and opens the marker popup.
If you set marker_zoom=7 then the map will be automatically zoomed in on the marker too with that zoom level.
The display will use your default list style but you can customise this by adding a CSS class and applying custom CSS. Use class="my-class-name" to add your class name.
Marker list example
This example shows the summits of the Welsh 3000s challenge. The default styling displays the list in as many columns as the display width permits.
[osmap height=600 markerfile="https://skirridsystems.co.uk/wp-content/uploads/welsh-3000s.json" marker_link="auto" marker_zoom=6 class="marker-list"]
- Snowdon - Yr Wyddfa
- Crib y Ddysgl
- Carnedd Llewelyn
- Carnedd Dafydd
- Glyder Fawr
- Glyder Fach
- Pen yr Ole Wen
- Foel Grach
- Castell y Gwynt
- Yr Elen
- Y Garn
- Foel-fras
- Carnedd Gwenllian
- Elidir Fawr
- Crib Goch
- Tryfan
Additional Shortcode for Markers
Marker Jump Links
It is sometimes useful to be able to insert a link to a marker within descriptive text below the map. As with the marker list, clicking on the link will scroll to the map, centred on that marker, and optionally zoom in on the marker. There are several attributes, but for most of them you can use the default values.
[osmap_link map=1 marker=2 zoom=7 label="view on map"]
map=1 sets the map to link to. By default this will be the last map you inserted, so if your text is below the map you will not need this.
marker=2 sets the marker to jump to. When you insert a map the default value is set to 1 and it increments each time you use the shortcode.
zoom=7 sets the zoom level when the marker is centred. The default is either 0 (no zoom) or if you set marker_zoom in the map shortcode it will use that value.
label="view on map" sets the text to be converted into a link. The default is “view on map”, but when you use the shortcode the value is saved for next use.
In order for the centring and zooming to work you need to set marker_link="link" in the main map shortcode. You can use both this link style and the auto-generated list if you wish by using both values separated by a comma: marker_link="auto,link"
Marker link example
[osmap markers="SH6099054380!red;Snowdon|SH6564658285;Glyder Fach" marker_link=link marker_zoom=8]
[osmap_link label="Snowdon"] [osmap_link label="Glyder Fach"]
Wales is home to some of the finest mountain scenery in Britain, and the highest of all these is Snowdon, with its famous Alpine-style railway on the one side and the glorious scrambling route up Crib Goch on the other.
On the other side of the Llanberis pass you can find Glyder Fach, its shattered summit rocks forming Castell y Gwynt (castle of the wind).
Marker Images
If you want to add a legend below your map referring to the markers, you may want to include an image of the marker so your readers can see which one you mean. There’s a shortcode for that which you can embed in your text.
[osmap_marker color=red]
The colours, numbers and letters supported are the same as for the map markers.
Summit of Snowdon (default) Glyder Fach (red marker) First point of interest (number 1) Access point ‘A’ (letter A)