peripleo

Peripleo Configuration Guide

This Guide assumes that you have already installed Peripleo, as outlined in the Installation Guide. It also assumed that you have created a compatible dataset, perhaps using Locolligo as outlined here.

This is an example of the basic minimum configuration settings required in peripleo.config.json:

{
  "initial_bounds": [-7.9, 49.5, 2.2, 59.4],
  "map_style": "./map-style-OSM.json",
  "data": [
    {
      "format": "LINKED_PLACES",
      "src": "./data/VisitPlus-UK.lp.json"
    }
  ]
}

And that’s it!

Sharing your Map

Peripleo updates the URL in your browser’s search bar automatically whenever you change the visualisation mode, facet selection, or move the map, so you can simply copy the URL to share a particular map view. Note, however, that the updated URL is not visible if your map is embedded (see below).

Initial View

By default, Peripleo will open a map with preset bounds (described above), with plain markers and without any facet(s) selected. You can change this default behaviour by adding parameters to the URL following the model:

https://your-url/#/zoom/longitude/latitude/mode=*points clusters heatmap+facet=type*

For example:

     https://britishlibrary.github.io/peripleo-lanc/leifuss/#/8.16/-3.3969/50.6397/mode=points+facet=type

If you wish to set only the visualisation mode or facet selection, replace zoom/longitude/latitude with ?/?/?. You cannot set only zoom, longitude, or latitude: you must provide values either for all three parameters or for none.

Embedding your Map

Maps made using Peripleo can be embedded in other web sites, wikis, and blogs. For example:

Advanced Configuration

Alternative Map Styles

Instead of the default Open Street Map basemap, you could use one from MapTiler, but you will need to read the documentation and get your own unique key. Alternatively, you might omit the map style altogether and use a tile baselayer instead: see below.

Example using the MapTiler Outdoor style:

"map_style": "https://api.maptiler.com/maps/outdoor/style.json?key=fc1c65e016c119b81e46c113b5cf8ebf8275b3b7"

You can also use tiles from the Consortium of Ancient World Mappers with this line:

"map_style": "./map-style-CAWM.json",

Baselayers

You can add any number of baselayers to your map, which might be GeoJSON (points, lines, or shapes) or raster tiles. All three types are combined in the example below (each enclosed in curly brackets and separated by commas):

"layers": [
  { 
    "name": "Rivers & Canals", 
    "type": "geojson",
    "src": "./layers/waterways.geojson", 
    "color": "#5555ff" 
  },
  {
    "name": "A Google-Maps-style XYZ tile layer",
    "type": "raster",
    "tiles": [
      "https://www.example-tileserver.com/tiles/{z}/{x}/{y}.png"
    ],
    "tileSize": 256,
    "attribution": "Example tiles",
    "minzoom": 0,
    "maxzoom": 22
  }
]

Additional Datasets

To combine multiple datasets on your map, simply add them to the data array like this:

"data": [
    {
      "name": "VisitPlus",
      "format": "LINKED_PLACES",
      "src": "./data/VisitPlus-UK.lp.json",
      "attribution": "VisitPlus © <a href=\"https://britishlibrary.github.io/locating-a-national-collection/\" target=\"_blank\"><i>Locating a National Collection</i> Partners & Contributors</a>"
    },
    {
      "name": "VisitMinus",
      "format": "LINKED_PLACES",
      "src": "./data/VisitMinus.lp.json",
      "attribution": "VisitMinus © Fictitious Entity"
    }
]

Link Icons

You can assign link icons to prettify external links in your dataset like this:

"link_icons": [
    { "pattern": "maps.google.com",  "img": "./logos/maps.google.com.png", "label": "Google Maps" },
    { "pattern": "www.geograph.org.uk", "img": "./logos/geograph.org.png", "label": "Geograph" },
    { "pattern": "en.wikipedia.org", "img": "./logos/en.wikipedia.org.png", "label": "Wikipedia" },
    { "pattern": "www.wikidata.org", "img": null, "label": "Wikidata" },
    { "pattern": "example.org/bad", "img": null, "label": "Bad Example" },
    { "pattern": "example.org/excellent", "img": "./logos/excellent.org.png", "label": "Excellent Example" },
    { "pattern": "example.org", "img": null, "label": "Terrible Example" },
    { "pattern": "www.geonames.org", "img": null, "label": "GeoNames" },
    { "pattern": "sws.geonames.org", "img": null, "label": "GeoNames" }
]

Facets

A facets array is used to specify filtering of the loaded datasets. If omitted, default facetting will be implemented based on dataset names, feature.properties.type values (or all values in each feature.types array), and the presence of an image link.

  "facets": [
    { "name": "custodian", "path": ["relations", "label"] },
    { "name": "organisation", "path": ["properties", "organisation"] },
    { "name": "art type", "path": ["properties", "artworkType"] }
  ]

Peripleo supports multi-value aggregation as well as paths with list structures, so if you set path: [ 'types', 'label' ], Peripleo will be able to aggregate from any the following four data feature structures:

{
  "types": {
    "label": "My Custom Type #1"
  }
}

{
  "types": [
    { "label": "My Custom Type #1" },
    { "label": "My Custom Type #2" }
  ]
}

{
  "types": {
    "label": [ "My Custom Type #1", "My Custom Type #2" ]
  }
}

{
  "types": [
    { "label": [ "My Custom Type #1", "My Custom Type #2" ] },
    { "label": [ "My Custom Type #3", "My Custom Type #4" ] }
  ]
}

Furthermore, you can add a condition that Peripleo will look for while aggregating results. So if you have facets configured like this…

"facets": [
  { "name": "method", "path": ["relations", "label"], "condition": [ "relationType", "aat:300138082" ] }
]

… then in the following example Peripleo will include the first match, but not the second:

{
  "types": [
    { "relationType": "aat:300138082", "label": "techniques (processes)" },
    { "relationType": "wd:Q3249551", "label": "process" }
  ]
}

And finally, facetting on dataset names and on all kinds of type (whether feature.properties.type values or values in a feature.types array) can be implemented with single words:

"facets": [
  "dataset",
  "type"
]

Custom Welcome Screen

You can add a custom welcome message to the loading screen via the welcome_message config argument. The value of welcome_message must point to the (relative or absolute) URL of a markdown file. If a custom welcome message is configured, Peripleo will not automatically switch to the map interface as soon as the data is loaded. Instead, an Ok confirmation button will be displayed after loading is complete. The map interface will open after the user hits Ok.

Example:

"welcome_message": "welcome.md"

In the above example, a file named welcome.md must be located on your webserver, in the same folder as the config file.

Dataset Metadata

It is possible to include metadata about each dataset specifically, inside the data file directly. If metadata is present in the datafile(s), Peripleo will compile an attribution list for all datafiles that include metadata, and provide a link to this list in the loading screen. In this case, the loading screen will not close automatically, but display an Ok confirmation button. (Exactly like when a custom welcome message is configured.)

To insert dataset metadata into a Linked Places file, add an indexing field at the top level element.

"indexing": {
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "name": "My Dataset",
  "description": "My dataset of geo-located collection objects.",
  "license": "https://creativecommons.org/licenses/by/4.0/",
  "identifier": "https://www.example.com/datasets/my-dataset"
}

Peripleo uses the name, description and license fields to compile the attribution list; and the identifier field to render a source link for each dataset.

Disabling the ‘My Location’ Button

Per default, Peripleo will show a ‘My Location’ button. Clicking this button will zoom the map to the users’ current location, as reported by the browser via the Geolocation API. (On mobile devices, the button will make use of the GPS device.)

You can disable this feature, and hide the button by adding the following line to the config file:

"disableMyLocation": true

Enabling Google Analytics Tracking

Per default, Peripleo will not perform any user activity tracking. Should you wish to track anonymized interactions, you can enable Peripleo’s built-in support for Google Analytics v4. To do so, simply add your Google Analytics v4 tracking code to the config file:

"ga_id": "G-XXXXXXXXXX"

If ga_id is present in the config, Peripleo will send events for the following user activities:

IMPORTANT: Although Google Analytics v4 no longer uses 3rd party tracking cookies, it still uses first party cookies for tracking. This means that, depending on your legislation, you may have to add a cookie consent popup to your host index.html page. Peripleo does not include a built-in cookie consent popup. If you are setting up Peripleo with Google Analytics enabled, it is up to you to include a consent popup on your site.

Advanced Example

A fully-featured peripleo.config.json file might look like this:

{
  "initial_bounds": [-7.9, 49.5, 2.2, 59.4],
  "map_style": "./map-style-OSM.json",
  "layers": [
    { 
      "name": "Rivers & Canals", 
      "type": "geojson",
      "src": "./layers/waterways.geojson", 
      "color": "#5555ff" 
    },
    {
      "name": "A Google-Maps-style XYZ tile layer",
      "type": "raster",
      "tiles": [
        "https://www.example-tileserver.com/tiles/{z}/{x}/{y}.png"
      ],
      "tileSize": 256,
      "attribution": "Example tiles",
      "minzoom": 0,
      "maxzoom": 22
    }
  ],
  "data": [
    {
      "name": "VisitPlus",
      "format": "LINKED_PLACES",
      "src": "./data/VisitPlus-UK.lp.json",
      "attribution": "VisitPlus © <a href=\"https://britishlibrary.github.io/locating-a-national-collection/\" target=\"_blank\"><i>Locating a National Collection</i> Partners & Contributors</a>"
    },
    {
      "name": "VisitMinus",
      "format": "LINKED_PLACES",
      "src": "./data/VisitMinus.lp.json",
      "attribution": "VisitMinus © Fictitious Entity"
    }
  ],
  "facets": [
    { "name": "method", "path": ["relations", "label"], "condition": [ "relationType", "aat:300138082" ] },
    { "name": "organisation", "path": ["properties", "organisation"] },
    { "name": "art type", "path": ["properties", "artworkType"] },
    "dataset",
    "type"
  ],
  "link_icons": [
    { "pattern": "maps.google.com",  "img": "./logos/maps.google.com.png", "label": "Google Maps" },
    { "pattern": "www.geograph.org.uk", "img": "./logos/geograph.org.png", "label": "Geograph" },
    { "pattern": "en.wikipedia.org", "img": "./logos/en.wikipedia.org.png", "label": "Wikipedia" },
    { "pattern": "www.wikidata.org", "img": null, "label": "Wikidata" },
    { "pattern": "example.org/bad", "img": null, "label": "Bad Example" },
    { "pattern": "example.org/excellent", "img": "./logos/excellent.org.png", "label": "Excellent Example" },
    { "pattern": "example.org", "img": null, "label": "Terrible Example" },
    { "pattern": "www.geonames.org", "img": null, "label": "GeoNames" },
    { "pattern": "sws.geonames.org", "img": null, "label": "GeoNames" }
  ]
}
This site is open source. Improve this page.