Client Customisation API

Warning

The functionality detailed in this page needs more attention, both in terms of testing and code development. We expect there to be some bugs and possible API changes. If you rely on this functionality, we recommend you pin your installation of Auspice to a specific version. Please get in touch with us if you are using these customisations so that we can work with you!

This page details the available options and format of the customisations available at (client) build time. They are contained in a JSON file supplied to Auspice via

auspice build --extend <JSON>

Note

The hot-reloading development functionality does not work for code which is included via this client customisation mechanism. Thus, while you can run auspice develop --extend <JSON> it will not update as you may expect!

Available Customisations

The following are definable as top-level keys of the JSON file. A useful reference may be the customisation JSON file used by nextstrain.org.

sidebarTheme allows modifications to the aesthetics of the sidebar. See below.
navbarComponent a (relative) path to a JS file exporting a React component to be rendered as the nav bar. See below.
splashComponent a (relative) path to a JS file exporting a React component to be rendered as the splash page. See below.
browserTitle The browser title for the page. Defaults to “auspice” if not defined.
finePrint String of Markdown to add to the “fine print” at the bottom of pages.
plausibleDataDomain plausible.io analytics (see below)
serverAddress Specify the address / prefix which the auspice client uses for API requests.
mapTiles Specify the address (and other information) for the tiles used to render the map.
enableDatasetEditor Set to true to turn on the ability to edit datasets and colors in the app.

Note

Please remember to make any modifications, including customisations described here, publicly available. See the previous page for more details.

Sidebar Theme

The appearence of the sidebar can be customised by specifing a theme in the config JSON used to build Auspice. This theme is then available (via styled-components) to the components rendered in the sidebar. It is also passed to the nav bar component (see below) as the theme prop.

For instance, here is the customisation used by nextstrain.org:

{
  "sidebarTheme": {
    "background": "#F2F2F2",
    "color": "#000",
    "sidebarBoxShadow": "rgba(0, 0, 0, 0.2)",
    "font-family": "Lato, Helvetica Neue, Helvetica, sans-serif",
    "selectedColor": "#5097BA",
    "unselectedColor": "#333",
    "alternateBackground": "#888"
  }
}

Properties	CSS string of	Description
selectedColor	color	Text color of selected text / button text
unselectedColor	color	Text color of unselected text / button text
color	color	Text color of all other text
unselectedBackground (deprecated)	color	Old key for `alternateBackground`
alternateBackground	color	Background color of some elements (unselected toggle, panel section borders)
font-family	font	Font used throughout the sidebar
background	color	Background color of the entire sidebar

Components

One way to extend Auspice is by replacing React components with your own custom components. These custom components will receive props defined here, which can be used to update the rendering of the component using the normal react lifecycle methods. Right now this is only available for the splash page and nav-bar components, whose interfaces are defined here.

Each component must be the default export of a javascript file which is specified in the (client) config JSON passed to Auspice at build time (auspice build or auspice develop).

Nav-bar Component

Build config:

{
  "navbarComponent": "<relative path to javascript file>"
}

Where the javascript file contains a default export of a React component.

React Props Available:

Prop	Type	Description
`narrativeTitle`	String
`sidebar`	Bool	Is it to be displayed in the sidebar?
`width`	Number	Width of the sidebar, in pixels
`theme`	Object	See above. Use this to style components.

Splash component

Define a custom splash page for Auspice. Please note that this is extremely expirimental and the interface is expected to change.

Build config:

{
  "splashComponent": "<relative path to javascript file>"
}

Where the javascript file contains a default export of a React component.

React Props available:

Prop	Type	Description
`isMobile`	Bool
`available`	Object	available datasets and narratives
`browserDimensions`	Object	Browser width & height
`dispatch`	function	access to redux’s dispatch mechanism
`errorMessage`	function	to do
`changePage`	function	to do

Specifying the API server address

By default, the client makes API requests (as detailed here) to “/charon/getAvailable”, “/charon/getDataset” etc. This is using the default server address of “/charon”. This can be changed by specifying serverAddress in the customisation JSON.

Note

If you specify a serverAddress on a different origin (protocol + domain + port) than Auspice, the server will need to send CORS headers to permit the requests from Auspice.

Custom Map tiles

Note

Auspice v3 introduced a breaking change to this interface. This page reflects the v3 API. Navigate to Auspice v2 docs for the raster-tile URL approach.

Background

Auspice uses Leaflet with MapLibre GL JS to render the map using vector tiles. By default, Auspice uses its own map-styles.json, a stylesheet originally based on OpenMapTiles’ positron theme.

The renderer is provider-agnostic: it simply renders whatever MapLibre style you give it, any provider that serves a MapLibre-compatible style (e.g. MapTiler, Stadia Maps, or a self-hosted style) should work.

If you wish to use Mapbox styles then you will need to transform the stylesheet as MapLibre doesn’t understand the proprietary mapbox:// protocol. We have a helper script transform-mapbox-style-json.js which will rewrite those references to their https://api.mapbox.com/... equivalents (and template the token as <ACCESS_TOKEN>); see the mapbox example customisation for an example of this.

Note

As tiles are fetched, Auspice rewrites any http:// requests to https://. This guards against mixed-content and CORS failures.

Customisation structure

{
  "mapTiles": {
    "style": "A MapLibre style JSON (inlined)",
    "accessToken": "(optional) access token for the tile provider",
    "attribution": "HTML-formatted attribution string to be displayed in the bottom-right-hand corner of the map",
    "mapboxWordmark": "(optional) should the Mapbox logo be displayed in the bottom-left of the map? (boolean)"
  }
}

If mapTiles is provided it fully replaces the default; specify every field you need (there is no merging with our defaults).

style: Either a URL string that resolves to a MapLibre style document, or the style document inline as a JSON object. The document declares everything the map needs — sources (tiles), sprites, fonts (glyphs), and layers — so in most cases this is the only thing you need to provide.
accessToken: Optional, and only relevant if your provider requires a key. Rather than embedding the key directly in the style, place the string <ACCESS_TOKEN> wherever the key value is required and supply the key here; it is substituted in at runtime. Because the placeholder is the value only, the surrounding query parameter comes from your provider’s own URLs (?access_token=<ACCESS_TOKEN> for Mapbox, ?key=<ACCESS_TOKEN> for MapTiler, etc.), so the same mechanism works across providers. Providers that don’t need a key can omit this field entirely.

Examples

Examples of map customisations are available in the Auspice repo:

Tracking Analytics

Auspice has in-built support for Plausible Analytics. To enable this you will need to provide the plausibleDataDomain in your extensions. The analytics are not included when running Auspice in development mode.