Auspice fork from github of https://github.com/urbanslug/auspice
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

151 lines
6.7 KiB

  1. # Client Customisation API
  2. > The functionality detailed in this page needs more attention, both in terms of testing and code development.
  3. We expect there to be some bugs and possible API changes.
  4. If you rely on this functionality, we recommend you pin your installation of Auspice to a specific version.
  5. Please [get in touch with us](mailto:hello@nextstrain.org) if you are using these customisations so that we can work with you!
  6. This page details the available options and format of the customisations available at (client) build time.
  7. They are contained in a JSON file supplied to Auspice via
  8. ```bash
  9. auspice build --extend <JSON>
  10. ```
  11. *Note that the hot-reloading development functionality does not work for code which is included via this client customisation mechanism.*
  12. *Thus, while you can run `auspice develop --extend <JSON>` it will not update as you may expect!*
  13. ## Available Customisations
  14. The following are definable as top-level keys of the JSON file.
  15. A useful reference may be the [customisation JSON file](https://github.com/nextstrain/nextstrain.org/blob/master/auspice-client/customisations/config.json) used by nextstrain.org.
  16. * `sidebarTheme` allows modifications to the aesthetics of the sidebar. See below.
  17. * `navbarComponent` a (relative) path to a JS file exporting a React component to be rendered as the nav bar. See below.
  18. * `browserTitle` The browser title for the page. Defaults to "auspice" if not defined.
  19. * `googleAnalyticsKey` You can specify a Google Analytics key to enable (some) analytics functionality. More documentation to come.
  20. * `serverAddress` Specify the address / prefix which the auspice client uses for API requests.
  21. * `mapTiles` Specify the address (and other information) for the tiles used to render the map.
  22. > Please remember to make any modifications, including customisations described here, publicly available. See [the previous page](./index.rst) for more details.
  23. ---
  24. ### Sidebar Theme
  25. The appearence of the sidebar can be customised by specifing a theme in the config JSON used to build Auspice.
  26. This theme is then available (via [styled-components](https://www.styled-components.com/)) to the components rendered in the sidebar.
  27. It is also passed to the nav bar component (see below) as the `theme` prop.
  28. For instance, here is the customisation used by nextstrain.org:
  29. ```json
  30. {
  31. "sidebarTheme": {
  32. "background": "#F2F2F2",
  33. "color": "#000",
  34. "sidebarBoxShadow": "rgba(0, 0, 0, 0.2)",
  35. "font-family": "Lato, Helvetica Neue, Helvetica, sans-serif",
  36. "selectedColor": "#5097BA",
  37. "unselectedColor": "#333"
  38. }
  39. }
  40. ```
  41. | Properties | CSS string of | Description |
  42. | ------------- |--------------- | ------ |
  43. | color | color | Text color |
  44. | selectedColor | color | Text color of selected text / button text |
  45. | unselectedColor | color | Text color of unselected text / button text |
  46. | font-family | font | Inner shadow of the sidebar on the right hand side |
  47. | background | color | Background color |
  48. ## Components
  49. One way to extend Auspice is by replacing React components with your own custom components.
  50. 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.
  51. Right now this is only available for the splash page and nav-bar components, whose interfaces are defined here.
  52. 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`).
  53. ### Nav-bar Component
  54. **Build config:**
  55. ```json
  56. {
  57. "navbarComponent": "<relative path to javascript file>"
  58. }
  59. ```
  60. Where the javascript file contains a default export of a React component.
  61. **React Props Available:**
  62. | Prop | Type | Description |
  63. | ----------- |--------- | ------ |
  64. | `narrativeTitle` | String | |
  65. | `sidebar ` | Bool | Is it to be displayed in the sidebar? |
  66. | `width ` | Number | Width of the sidebar, in pixels |
  67. | `theme ` | Object | See above. Use this to style components. |
  68. ### Splash component
  69. Define a custom splash page for Auspice. Please note that this is extremely expirimental and the interface is expected to change.
  70. **Build config:**
  71. ```json
  72. {
  73. "splashComponent": "<relative path to javascript file>"
  74. }
  75. ```
  76. Where the javascript file contains a default export of a React component.
  77. **React Props available:**
  78. | Prop | Type | Description |
  79. | ----------- |--------- | ------ |
  80. | `isMobile` | Bool | |
  81. | `available` | Object | available datasets and narratives |
  82. | `browserDimensions` | Object | Browser width & height |
  83. | `dispatch` | function | access to redux's dispatch mechanism |
  84. | `errorMessage` | function | to do |
  85. | `changePage` | function | to do |
  86. ---
  87. ### Specifying the API server address
  88. By default, the client makes API requests ([as detailed here](requests.md)) to "/charon/getAvailable", "/charon/getDataset" etc.
  89. This is using the default server address of "/charon".
  90. This can be changed by specifying `serverAddress` in the customisation JSON.
  91. > Note that currently you can't specify a different domain due to CORS headers.
  92. This may well be a simple fix -- please get in touch if you can help here!
  93. ---
  94. ### Custom Map tiles
  95. Auspice uses [Leaflet](https://leafletjs.com/) to render the map, which requires access to a tile set in order to render the geography.
  96. By default, auspice uses [Mapbox](https://www.mapbox.com/) for these tiles, and we make these available for local use of auspice.
  97. If you are distributing your own version of auspice (i.e. not running it locally) you must set an appropriate API address here so that the map can fetch suitable tiles.
  98. ```json
  99. {
  100. "mapTiles": {
  101. "api": "API address for Leaflet to fetch map tiles",
  102. "attribution": "HTML-formatted attribution string to be displayed in bottom-right-hand corner of map",
  103. "mapboxWordmark": "(optional) should the Mapbox logo be displayed in the bottom-left of the map? (boolean)"
  104. }
  105. }
  106. ```
  107. For some examples of other tile sets you may use, see the [OpenStreetMap wiki](https://wiki.openstreetmap.org/wiki/Tile_servers), and please remember to adhere to the licenses and terms of use for each tile server.
  108. The API address contains parameters as specified by the [Leaflet API](https://docs.mapbox.com/api/overview/).