Auspice

Auspice

  • Docs

›Customising Auspice

Introduction

  • Overview
  • Install Auspice
  • How to Run Auspice

Advanced Functionality

  • Displaying multiple trees
  • View Settings
  • Adding extra metadata via CSV/TSV
  • Miscellaneous

Customising Auspice

  • Customising Auspice
  • Client Customisation API
  • Requests Made from the Client

Using a Custom Server

  • Auspice servers
  • Server API
  • Authentication

Narratives

  • Communicating Results Using Narratives
  • Writing a Narrative
  • Converting a narrative to PDF

Release Notes

  • Changelog
  • Auspice Version 2.0

Contributing

  • Contributing to Auspice

Client Customisation API

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 that 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.
  • browserTitle The browser title for the page. Defaults to "auspice" if not defined.
  • googleAnalyticsKey You can specify a Google Analytics key to enable (some) analytics functionality. More documentation to come.
  • serverAddress Specify the address / prefix which the auspice client uses for API requests.

For customisation code which uses React components, you must import these as import React from "@libraries/react"; to ensure that the version of react is the same as what Auspice uses.


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"
  }
}
PropertiesCSS string ofDescription
colorcolorText color
selectedColorcolorText color of selected text / button text
unselectedColorcolorText color of unselected text / button text
font-familyfontInner shadow of the sidebar on the right hand side
backgroundcolorBackground color

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:

PropTypeDescription
narrativeTitleString
sidebarBoolIs it to be displayed in the sidebar?
widthNumberWidth of the sidebar, in pixels
themeObjectSee 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:

PropTypeDescription
isMobileBool
availableObjectavailable datasets and narratives
browserDimensionsObjectBrowser width & height
dispatchfunctionaccess to redux's dispatch mechanism
errorMessagefunctionto do
changePagefunctionto 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 that currently you can't specify a different domain due to CORS headers. This may well be a simple fix -- please get in touch if you can help here!

Last updated on 1/28/2020
← Customising AuspiceRequests Made from the Client →
  • Available Customisations
  • Sidebar Theme
  • Nav-bar Component
  • Splash component
  • Specifying the API server address
Auspice
External Links
GitHub repoNPM packageNextstrain
Contact Us
emailtwitter
Website built by James Hadfield using Docusaurus
If you use auspice, please cite Hadfield et al., 2018
Copyright © 2014-2020 Richard Neher & Trevor Bedford