auspice
Version:
Web app for visualizing pathogen evolution
165 lines (158 loc) • 20 kB
HTML
<html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Client Customisation API · Auspice</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="> The functionality detailed in this page needs more attention, both in terms of testing and code development."/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Client Customisation API · Auspice"/><meta property="og:type" content="website"/><meta property="og:url" content="https://nextstrain.github.io/auspice/"/><meta property="og:description" content="> The functionality detailed in this page needs more attention, both in terms of testing and code development."/><meta property="og:image" content="https://nextstrain.github.io/auspice/img/icon.svg"/><meta name="twitter:card" content="summary"/><meta name="twitter:image" content="https://nextstrain.github.io/auspice/img/icon.svg"/><link rel="shortcut icon" href="/auspice/img/favicon.ico"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><script src="/auspice/js/scrollSpy.js"></script><link rel="stylesheet" href="/auspice/css/main.css"/><script src="/auspice/js/codetabs.js"></script></head><body class="sideNavVisible separateOnPageNav"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/auspice/"><img class="logo" src="/auspice/img/logo-light.svg" alt="Auspice"/><h2 class="headerTitleWithLogo">Auspice</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li class="siteNavGroupActive"><a href="/auspice/introduction/overview" target="_self">Docs</a></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><div class="hamburger-menu"><div class="line1"></div><div class="line2"></div><div class="line3"></div></div></div><h2><i>›</i><span>Customising Auspice</span></h2><div class="tocToggler" id="tocToggler"><i class="icon-toc"></i></div></div><div class="navGroups"><div class="navGroup"><h3 class="navGroupCategoryTitle">Introduction</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/introduction/overview">Overview</a></li><li class="navListItem"><a class="navItem" href="/auspice/introduction/install">Install Auspice</a></li><li class="navListItem"><a class="navItem" href="/auspice/introduction/how-to-run">How to Run Auspice</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Advanced Functionality</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/advanced-functionality/second-trees">Displaying mutliple trees</a></li><li class="navListItem"><a class="navItem" href="/auspice/advanced-functionality/misc">Miscellaneous</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Customising Auspice</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/customise-client/introduction">Customising Auspice</a></li><li class="navListItem navListItemActive"><a class="navItem" href="/auspice/customise-client/api">Client Customisation API</a></li><li class="navListItem"><a class="navItem" href="/auspice/customise-client/requests">Requests Made from the Client</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Using a Custom Server</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/server/introduction">Auspice servers</a></li><li class="navListItem"><a class="navItem" href="/auspice/server/api">Server API</a></li><li class="navListItem"><a class="navItem" href="/auspice/server/authentication">Authentication</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Narratives</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/narratives/introduction">Communicating Results Using Narratives</a></li><li class="navListItem"><a class="navItem" href="/auspice/narratives/how-to-write">Writing a Narrative</a></li><li class="navListItem"><a class="navItem" href="/auspice/narratives/create-pdf">Converting a narrative to PDF</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Release Notes</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/releases/changelog">Changelog</a></li><li class="navListItem"><a class="navItem" href="/auspice/releases/v2">Auspice Version 2.0</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Contributing</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/contributing/overview">Contributing to Auspice</a></li></ul></div></div></section></div><script>
var coll = document.getElementsByClassName('collapsible');
var checkActiveCategory = true;
for (var i = 0; i < coll.length; i++) {
var links = coll[i].nextElementSibling.getElementsByTagName('*');
if (checkActiveCategory){
for (var j = 0; j < links.length; j++) {
if (links[j].classList.contains('navListItemActive')){
coll[i].nextElementSibling.classList.toggle('hide');
coll[i].childNodes[1].classList.toggle('rotate');
checkActiveCategory = false;
break;
}
}
}
coll[i].addEventListener('click', function() {
var arrow = this.childNodes[1];
arrow.classList.toggle('rotate');
var content = this.nextElementSibling;
content.classList.toggle('hide');
});
}
document.addEventListener('DOMContentLoaded', function() {
createToggler('#navToggler', '#docsNav', 'docsSliderActive');
createToggler('#tocToggler', 'body', 'tocActive');
var headings = document.querySelector('.toc-headings');
headings && headings.addEventListener('click', function(event) {
var el = event.target;
while(el !== headings){
if (el.tagName === 'A') {
document.body.classList.remove('tocActive');
break;
} else{
el = el.parentNode;
}
}
}, false);
function createToggler(togglerSelector, targetSelector, className) {
var toggler = document.querySelector(togglerSelector);
var target = document.querySelector(targetSelector);
if (!toggler) {
return;
}
toggler.onclick = function(event) {
event.preventDefault();
target.classList.toggle(className);
};
}
});
</script></nav></div><div class="container mainContainer"><div class="wrapper"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle">Client Customisation API</h1></header><article><div><span><blockquote>
<p>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 <a href="mailto:hello@nextstrain.org">get in touch with us</a> if you are using these customisations so that we can work with you!</p>
</blockquote>
<p>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</p>
<pre><code class="hljs css language-bash">auspice build --extend <JSON>
</code></pre>
<p><em>Note that the hot-reloading development functionality does not work for code which is included via this client customisation mechanism.</em>
<em>Thus, while you can run <code>auspice develop --extend <JSON></code> it will not update as you may expect!</em></p>
<h2><a class="anchor" aria-hidden="true" id="available-customisations"></a><a href="#available-customisations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Available Customisations</h2>
<p>The following are definable as top-level keys of the JSON file.
A useful reference may be the <a href="https://github.com/nextstrain/nextstrain.org/blob/master/auspice/client/config.json">customisation JSON file</a> used by nextstrain.org.</p>
<ul>
<li><code>sidebarTheme</code> allows modifications to the aesthetics of the sidebar. See below.</li>
<li><code>navbarComponent</code> a (relative) path to a JS file exporting a React component to be rendered as the nav bar. See below.</li>
<li><code>browserTitle</code> The browser title for the page. Defaults to "auspice" if not defined.</li>
<li><code>googleAnalyticsKey</code> You can specify a Google Analytics key to enable (some) analytics functionality. More documentation to come.</li>
<li><code>serverAddress</code> Specify the address / prefix which the auspice client uses for API requests.</li>
</ul>
<blockquote>
<p>For customisation code which uses <a href="https://reactjs.org/">React</a> components, you must import these as <code>import React from "@libraries/react";</code> to ensure that the version of react is the same as what Auspice uses.</p>
</blockquote>
<hr>
<h2><a class="anchor" aria-hidden="true" id="sidebar-theme"></a><a href="#sidebar-theme" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Sidebar Theme</h2>
<p>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 <a href="https://www.styled-components.com/">styled-components</a>) to the components rendered in the sidebar.
It is also passed to the nav bar component (see below) as the <code>theme</code> prop.</p>
<p>For instance, here is the customisation used by nextstrain.org:</p>
<pre><code class="hljs css language-json">{
<span class="hljs-attr">"sidebarTheme"</span>: {
<span class="hljs-attr">"background"</span>: <span class="hljs-string">"#F2F2F2"</span>,
<span class="hljs-attr">"color"</span>: <span class="hljs-string">"#000"</span>,
<span class="hljs-attr">"sidebarBoxShadow"</span>: <span class="hljs-string">"rgba(0, 0, 0, 0.2)"</span>,
<span class="hljs-attr">"font-family"</span>: <span class="hljs-string">"Lato, Helvetica Neue, Helvetica, sans-serif"</span>,
<span class="hljs-attr">"selectedColor"</span>: <span class="hljs-string">"#5097BA"</span>,
<span class="hljs-attr">"unselectedColor"</span>: <span class="hljs-string">"#333"</span>
}
}
</code></pre>
<table>
<thead>
<tr><th>Properties</th><th>CSS string of</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>color</td><td>color</td><td>Text color</td></tr>
<tr><td>selectedColor</td><td>color</td><td>Text color of selected text / button text</td></tr>
<tr><td>unselectedColor</td><td>color</td><td>Text color of unselected text / button text</td></tr>
<tr><td>font-family</td><td>font</td><td>Inner shadow of the sidebar on the right hand side</td></tr>
<tr><td>background</td><td>color</td><td>Background color</td></tr>
</tbody>
</table>
<h1><a class="anchor" aria-hidden="true" id="components"></a><a href="#components" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Components</h1>
<p>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.</p>
<p>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 (<code>auspice build</code> or <code>auspice develop</code>).</p>
<h2><a class="anchor" aria-hidden="true" id="nav-bar-component"></a><a href="#nav-bar-component" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Nav-bar Component</h2>
<p><strong>Build config:</strong></p>
<pre><code class="hljs css language-json">{
<span class="hljs-attr">"navbarComponent"</span>: <span class="hljs-string">"<relative path to javascript file>"</span>
}
</code></pre>
<p>Where the javascript file contains a default export of a React component.</p>
<p><strong>React Props Available:</strong></p>
<table>
<thead>
<tr><th>Prop</th><th>Type</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><code>narrativeTitle</code></td><td>String</td><td></td></tr>
<tr><td><code>sidebar</code></td><td>Bool</td><td>Is it to be displayed in the sidebar?</td></tr>
<tr><td><code>theme</code></td><td>Object</td><td>See above. Use this to style components.</td></tr>
</tbody>
</table>
<h2><a class="anchor" aria-hidden="true" id="splash-component"></a><a href="#splash-component" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Splash component</h2>
<p>Define a custom splash page for Auspice. Please note that this is extremely expirimental and the interface is expected to change.</p>
<p><strong>Build config:</strong></p>
<pre><code class="hljs css language-json">{
<span class="hljs-attr">"splashComponent"</span>: <span class="hljs-string">"<relative path to javascript file>"</span>
}
</code></pre>
<p>Where the javascript file contains a default export of a React component.</p>
<p><strong>React Props available:</strong></p>
<table>
<thead>
<tr><th>Prop</th><th>Type</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><code>isMobile</code></td><td>Bool</td><td></td></tr>
<tr><td><code>available</code></td><td>Object</td><td>available datasets and narratives</td></tr>
<tr><td><code>browserDimensions</code></td><td>Object</td><td>Browser width & height</td></tr>
<tr><td><code>dispatch</code></td><td>function</td><td>access to redux's dispatch mechanism</td></tr>
<tr><td><code>errorMessage</code></td><td>function</td><td>to do</td></tr>
<tr><td><code>changePage</code></td><td>function</td><td>to do</td></tr>
</tbody>
</table>
<hr>
<h2><a class="anchor" aria-hidden="true" id="specifying-the-api-server-address"></a><a href="#specifying-the-api-server-address" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Specifying the API server address</h2>
<p>By default, the client makes API requests (<a href="/auspice/customise-client/requests">as detailed here</a>) to "/charon/getAvailable", "/charon/getDataset" etc.
This is using the default server address of "/charon".
This can be changed by specifying <code>serverAddress</code> in the customisation JSON.</p>
<blockquote>
<p>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!</p>
</blockquote>
</span></div></article></div><div class="docLastUpdate"><em>Last updated on 11/15/2019</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/auspice/customise-client/introduction"><span class="arrow-prev">← </span><span>Customising Auspice</span></a><a class="docs-next button" href="/auspice/customise-client/requests"><span>Requests Made from the Client</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#available-customisations">Available Customisations</a></li><li><a href="#sidebar-theme">Sidebar Theme</a></li><li><a href="#nav-bar-component">Nav-bar Component</a></li><li><a href="#splash-component">Splash component</a></li><li><a href="#specifying-the-api-server-address">Specifying the API server address</a></li></ul></nav></div><footer class="nav-footer" id="footer"><section class="sitemap"><div><a href="/auspice/"><img style="padding-left:20px" src="/auspice/img/logo-light.svg" alt="Auspice" width="66" height="58"/></a></div><div><h5>External Links</h5><a href="https://github.com/nextstrain/auspice">GitHub repo</a><a href="https://www.npmjs.com/package/auspice">NPM package</a><a href="https://nextstrain.org">Nextstrain</a></div><div><h5>Contact Us</h5><a href="mailto:hello@nextstrain.org">email</a><a href="https://twitter.com/hamesjadfield">twitter</a></div></section><section class="copyright">Website built by <a href="https://twitter.com/hamesjadfield">James Hadfield</a> using <a href="https://docusaurus.io">Docusaurus</a></section><section class="copyright">If you use auspice, please cite <a href="https://doi.org/10.1093/bioinformatics/bty407">Hadfield et al., 2018</a></section><section class="copyright">Copyright © 2014-2020 Richard Neher & Trevor Bedford</section></footer></div></body></html>