@gmod/jbrowse

<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Mouse clicks, menus, and popups · JBrowse</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="## Customizing parts of the 'View details' Pop-ups with callbacks"/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Mouse clicks, menus, and popups · JBrowse"/><meta property="og:type" content="website"/><meta property="og:url" content="https://jbrowse.org/index.html"/><meta property="og:description" content="## Customizing parts of the 'View details' Pop-ups with callbacks"/><meta name="twitter:card" content="summary"/><link rel="shortcut icon" href="/img/favicon.ico"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"/><link rel="alternate" type="application/atom+xml" href="https://jbrowse.org/blog/atom.xml" title="JBrowse Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://jbrowse.org/blog/feed.xml" title="JBrowse Blog RSS Feed"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><link rel="stylesheet" href="/css/main.css"/></head><body class="sideNavVisible separateOnPageNav"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/"><h2 class="headerTitle">JBrowse</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li class=""><a href="/blog" target="_self">Blog</a></li><li class="siteNavGroupActive"><a href="/docs/installation.html" target="_self">Documentation</a></li><li class=""><a href="/en/demos.html" target="_self">Demos</a></li><li class=""><a href="/en/developers.html" target="_self">Developers</a></li><li class=""><a href="/en/contact.html" target="_self">Contact</a></li><li class=""><a href="/en/references.html" target="_self">References</a></li><li class=""><a href="/en/help.html" target="_self">Help</a></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="container docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><i></i></div><h2><i>›</i><span>Advanced configuration</span></h2><div class="tocToggler" id="tocToggler"><i class="icon-toc"></i></div></div><div class="navGroups"><div class="navGroup"><h3 class="navGroupCategoryTitle">Tutorial</h3><ul><li class="navListItem"><a class="navItem" href="/docs/installation.html">Installation</a></li><li class="navListItem"><a class="navItem" href="/docs/tutorial.html">Indexed file formats tutorial</a></li><li class="navListItem"><a class="navItem" href="/docs/tutorial_classic.html">Classic quick-start guide</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Configuring tracks</h3><ul><li class="navListItem"><a class="navItem" href="/docs/reference_sequence.html">Reference sequence configuration</a></li><li class="navListItem"><a class="navItem" href="/docs/canvas_features.html">CanvasFeatures</a></li><li class="navListItem"><a class="navItem" href="/docs/html_features.html">HTMLFeatures</a></li><li class="navListItem"><a class="navItem" href="/docs/alignments.html">Alignments tracks</a></li><li class="navListItem"><a class="navItem" href="/docs/bigwig.html">Wiggle/BigWig Tracks</a></li><li class="navListItem"><a class="navItem" href="/docs/variants.html">VCF tracks</a></li><li class="navListItem"><a class="navItem" href="/docs/minimal.html">Minimal JBrowse configurations</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Advanced configuration</h3><ul><li class="navListItem"><a class="navItem" href="/docs/embedding.html">Embedding JBrowse</a></li><li class="navListItem navListItemActive"><a class="navItem" href="/docs/mouse_configs.html">Mouse clicks, menus, and popups</a></li><li class="navListItem"><a class="navItem" href="/docs/configuration_file_formats.html">Configuration File Formats</a></li><li class="navListItem"><a class="navItem" href="/docs/dataset_selector.html">Dataset Selector</a></li><li class="navListItem"><a class="navItem" href="/docs/track_selectors.html">Track Selectors</a></li><li class="navListItem"><a class="navItem" href="/docs/track_metadata.html">Track Metadata</a></li><li class="navListItem"><a class="navItem" href="/docs/global_options.html">Global configuration options</a></li><li class="navListItem"><a class="navItem" href="/docs/compression.html">Compressing JBrowse data</a></li><li class="navListItem"><a class="navItem" href="/docs/authentication.html">HTTP authentication for JBrowse</a></li><li class="navListItem"><a class="navItem" href="/docs/paired_reads.html">Paired read viewing</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Command line</h3><ul><li class="navListItem"><a class="navItem" href="/docs/flatfile-to-json.pl.html">flatfile-to-json.pl</a></li><li class="navListItem"><a class="navItem" href="/docs/remove-track.pl.html">remove-track.pl</a></li><li class="navListItem"><a class="navItem" href="/docs/ucsc-to-json.pl.html">ucsc-to-json.pl</a></li><li class="navListItem"><a class="navItem" href="/docs/generate-names.pl.html">generate-names.pl</a></li><li class="navListItem"><a class="navItem" href="/docs/prepare-refseqs.pl.html">prepare-refseqs.pl</a></li><li class="navListItem"><a class="navItem" href="/docs/biodb-to-json.pl.html">biodb-to-json.pl</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">JBrowse Desktop</h3><ul><li class="navListItem"><a class="navItem" href="/docs/jbrowse_desktop.html">JBrowse Desktop</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">FAQ</h3><ul><li class="navListItem"><a class="navItem" href="/docs/faq.html">JBrowse FAQ</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Other topics</h3><ul><li class="navListItem"><a class="navItem" href="/docs/url_strings.html">JBrowse URL parameters</a></li><li class="navListItem"><a class="navItem" href="/docs/image_tracks.html">Pre-rendered Image Tracks</a></li><li class="navListItem"><a class="navItem" href="/docs/feature_coverage.html">Feature Coverage Tracks</a></li><li class="navListItem"><a class="navItem" href="/docs/screenshots.html">Automating screenshots of JBrowse</a></li><li class="navListItem"><a class="navItem" href="/docs/events.html">JBrowse Subscribe/Publish events</a></li><li class="navListItem"><a class="navItem" href="/docs/perl_config.html">Sample configuration bash script</a></li><li class="navListItem"><a class="navItem" href="/docs/data_formats.html">JBrowse REST API and Data APIs</a></li><li class="navListItem"><a class="navItem" href="/docs/plugins.html">Installing and writing plugins</a></li><li class="navListItem"><a class="navItem" href="/docs/cors.html">Cross-origin resource sharing (CORS)</a></li><li class="navListItem"><a class="navItem" href="/docs/sparql.html">SPARQL configuration</a></li><li class="navListItem"><a class="navItem" href="/docs/data_export.html">Data export</a></li><li class="navListItem"><a class="navItem" href="/docs/usage_stats.html">Usage Statistics</a></li></ul></div></div></section></div><script> document.addEventListener('DOMContentLoaded', function() { createToggler('#navToggler', '#docsNav', 'docsSliderActive'); createToggler('#tocToggler', 'body', 'tocActive'); const headings = document.querySelector('.toc-headings'); headings && headings.addEventListener('click', function(event) { if (event.target.tagName === 'A') { document.body.classList.remove('tocActive'); } }, false); function createToggler(togglerSelector, targetSelector, className) { var toggler = document.querySelector(togglerSelector); var target = document.querySelector(targetSelector); 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">Mouse clicks, menus, and popups</h1></header><article><div><span><h2><a class="anchor" aria-hidden="true" id="customizing-parts-of-the-view-details-pop-ups-with-callbacks"></a><a href="#customizing-parts-of-the-view-details-pop-ups-with-callbacks" 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>Customizing parts of the 'View details' Pop-ups with callbacks</h2> <p>Starting in JBrowse version 1.11.3, the ability to customize parts of the 'View details' Pop-ups was added. This lets you specify functions that have the format fmtDetailValue_* or fmtDetailField_* to either change the value section of an attribute in the config, or the fieldname of an attribute in the config.</p> <p>Here is an example in tracks.conf format for formatting the "Name" field by adding a link to it:</p> <pre><code class="hljs">[tracks.mygff] key = My Gene Track storeClass = JBrowse/Store/SeqFeature/NCList<span class="hljs-built_in"> type </span>= FeatureTrack fmtDetailValue_Name = function(name) { return <span class="hljs-string">"<a href='http://www.example.com?featurename="</span>+name+<span class="hljs-string">"'>"</span>+name+<span class="hljs-string">"</a>"</span>; } </code></pre> <p>Note: It is also easy to specify these methods in trackList.json format.</p> <pre><code class="hljs">{ <span class="hljs-attr">"key"</span>: <span class="hljs-string">"My Gene Track"</span>, <span class="hljs-attr">"storeClass"</span> : <span class="hljs-string">"JBrowse/Store/SeqFeature/NCList"</span>, <span class="hljs-attr">"type"</span> : <span class="hljs-string">"FeatureTrack"</span>, <span class="hljs-attr">"label"</span>: <span class="hljs-string">"mygff"</span>, <span class="hljs-attr">"fmtDetailValue_Name"</span>: <span class="hljs-string">"function(name) { return '<a href=\"http://www.example.com?featurename='+name+'\">'+name+'</a>'; }"</span> } </code></pre> <p>Addendum: If the field has multiple values (e.g. multiple DBXrefs or GO terms), then the callback will receive an array as it's argument, and then you can also return an array which indicates that each element will be formatted inside its own <div>. In this case you will check that the input is an array, because it will also be called on the individual elements too. For example:</p> <pre><code class="hljs"> <span class="hljs-string">"fmtDetailValue_links"</span>: <span class="hljs-type"></span>"<span class="hljs-function"><span class="hljs-keyword">function</span></span>(links) { <span class="hljs-keyword">if</span>(<span class="hljs-keyword">Array</span>.isArray(links)) { <span class="hljs-keyword">return</span> links; } <span class="hljs-keyword">else</span> <span class="hljs-keyword">return</span> `<a href=\<span class="hljs-string">"${link}\">${link}</a>`; }"</span> </code></pre> <p>This shows that you could, in essence, pre-process the array if you wanted, but the same callback is then called on the individual elements, so you handle both these cases.</p> <h3><a class="anchor" aria-hidden="true" id="rendering-html-in-popups"></a><a href="#rendering-html-in-popups" 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>Rendering HTML in popups</h3> <p>If you are using the fmtDetailValue callbacks it is assumed that HTML can be returned. Otherwise if your data contains actual HTML that you want to render you must set <code>unsafePopup</code> on your track</p> <h3><a class="anchor" aria-hidden="true" id="additional-customizations-to-the-pop-up-boxes"></a><a href="#additional-customizations-to-the-pop-up-boxes" 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>Additional customizations to the pop-up boxes</h3> <p>In JBrowse 1.11.5, some additional customizations to the pop-up boxes were added.</p> <ol> <li>The ability to access the feature data was added to the callback signature of the fmtDetailValue_* functions. Example:</li> </ol> <pre><code class="hljs">fmtDetailValue_Name = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(name, feature)</span> </span>{ <span class="hljs-comment">/* only add links to the top-level feature */</span> <span class="hljs-keyword">if</span>(feature.get(<span class="hljs-string">'type'</span>)==<span class="hljs-string">'mRNA'</span>) { <span class="hljs-keyword">return</span> name + <span class="hljs-string">' [<a href=http://www.ncbi.nlm.nih.gov/gquery/?term='</span>+name+<span class="hljs-string">'>Search NCBI</a>]'</span>; } } </code></pre> <ol start="2"> <li><p>The ability to customize the 'About track' popups was added. These callbacks are named fmtMetaValue_* and fmtMetaField_*</p></li> <li><p>The ability to customize mouseover descriptions of the fieldnames was also added. These callbacks are named fmtDetailDescription_* and fmtMetaDescription_*</p></li> <li><p>The ability to remove a field from the popup was added. You can do this by returning null from a fmtDetailField_* and fmtMetaField_* callback;</p></li> <li><p>In 1.15.4 the ability to remove the sequence FASTA boxes from the View details popups was added by specifying hideSequenceBox: true to the config</p></li> </ol> <h1><a class="anchor" aria-hidden="true" id="customizing-left-click-behavior"></a><a href="#customizing-left-click-behavior" 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>Customizing Left-click Behavior</h1> <p>Beginning with JBrowse 1.5.0, the left-clicking behavior of feature tracks (both HTMLFeatures and CanvasFeatures) is highly configurable. To make something happen when left-clicking features on a track, add an onClick option to the feature track's configuration.</p> <p>In the example configuration below, left-clicks on features will open an embedded popup window showing the results of searching for that feature's name in NCBI's global search, and "search at NCBI" will show in a tooltip when the user hovers over a feature with the mouse:</p> <p>diff -git a/docs/site/configuration_guide.md b/docs/site/configuration_guide.md index 9f70239..c57b07a 100644 -- a/docs/site/configuration_guide.md +++ b/docs/site/configuration_guide.md @@ 13,331 +13,7 @@ Check out the new <a href="faq.html">JBrowse FAQ</a> page for more tips on setup and config</p> <p>Also see the <a href="jbrowse_desktop.html">JBrowse Desktop</a> guide here.</p> <h1><a class="anchor" aria-hidden="true" id="feature-tracks-htmlfeatures-and-canvasfeatures"></a><a href="#feature-tracks-htmlfeatures-and-canvasfeatures" 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>Feature Tracks (HTMLFeatures and CanvasFeatures)</h1> <p>Feature tracks can be used to visualize localized annotations on a sequence, such as gene models, transcript alignments, SNPs and so forth.</p> <h2><a class="anchor" aria-hidden="true" id="generic-track-configuration-options"></a><a href="#generic-track-configuration-options" 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>Generic Track Configuration Options</h2> <table> <thead> <tr><th>Option</th><th>Description</th></tr> </thead> <tbody> <tr><td><code>subfeatureDetailLevel</code></td><td>Set the level of detail of the View details box. If set to 1, only displays one level of subfeatures for example. Default: 0 which displays all subfeature levels. Added in 1.12.3</td></tr> </tbody> </table> <h2><a class="anchor" aria-hidden="true" id="customizing-parts-of-the-view-details-pop-ups-with-callbacks-1"></a><a href="#customizing-parts-of-the-view-details-pop-ups-with-callbacks-1" 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>Customizing parts of the 'View details' Pop-ups with callbacks</h2> <p>Starting in JBrowse version 1.11.3, the ability to customize parts of the 'View details' Pop-ups was added. This lets you specify functions that have the format fmtDetailValue_* or fmtDetailField_* to either change the value section of an attribute in the config, or the fieldname of an attribute in the config.</p> <p>Here is an example in tracks.conf format for formatting the "Name" field by adding a link to it:</p> <pre><code class="hljs">[tracks.mygff] key = My Gene Track storeClass = JBrowse/Store/SeqFeature/NCList<span class="hljs-built_in"> type </span>= FeatureTrack fmtDetailValue_Name = function(name) { return <span class="hljs-string">"<a href='http://www.example.com?featurename="</span>+name+<span class="hljs-string">"'>"</span>+name+<span class="hljs-string">"</a>"</span>; } </code></pre> <p>Note: It is also easy to specify these methods in trackList.json format.</p> <pre><code class="hljs">{ <span class="hljs-attr">"key"</span>: <span class="hljs-string">"My Gene Track"</span>, <span class="hljs-attr">"storeClass"</span> : <span class="hljs-string">"JBrowse/Store/SeqFeature/NCList"</span>, <span class="hljs-attr">"type"</span> : <span class="hljs-string">"FeatureTrack"</span>, <span class="hljs-attr">"label"</span>: <span class="hljs-string">"mygff"</span>, <span class="hljs-attr">"fmtDetailValue_Name"</span>: <span class="hljs-string">"function(name) { return '<a href=\"http://www.example.com?featurename='+name+'\">'+name+'</a>'; }"</span> } </code></pre> <p>Addendum: If the field has multiple values (e.g. multiple DBXrefs or GO terms), then the callback will receive an array as it's argument, and then you can also return an array which indicates that each element will be formatted inside its own <div>. In this case you will check that the input is an array, because it will also be called on the individual elements too. For example:</p> <pre><code class="hljs"> <span class="hljs-string">"fmtDetailValue_links"</span>: <span class="hljs-type"></span>"<span class="hljs-function"><span class="hljs-keyword">function</span></span>(links) { <span class="hljs-keyword">if</span>(<span class="hljs-keyword">Array</span>.isArray(links)) { <span class="hljs-keyword">return</span> links; } <span class="hljs-keyword">else</span> <span class="hljs-keyword">return</span> `<a href=\<span class="hljs-string">"${link}\">${link}</a>`; }"</span> </code></pre> <p>This shows that you could, in essence, pre-process the array if you wanted, but the same callback is then called on the individual elements, so you handle both these cases.</p> <h3><a class="anchor" aria-hidden="true" id="additional-customizations-to-the-pop-up-boxes-1"></a><a href="#additional-customizations-to-the-pop-up-boxes-1" 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>Additional customizations to the pop-up boxes</h3> <p>In JBrowse 1.11.5, some additional customizations to the pop-up boxes were added.</p> <ol> <li>The ability to access the feature data was added to the callback signature of the fmtDetailValue_* functions. Example:</li> </ol> <pre><code class="hljs">fmtDetailValue_Name = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(name, feature)</span> </span>{ <span class="hljs-comment">/* only add links to the top-level feature */</span> <span class="hljs-keyword">if</span>(feature.get(<span class="hljs-string">'type'</span>)==<span class="hljs-string">'mRNA'</span>) { <span class="hljs-keyword">return</span> name + <span class="hljs-string">' [<a href=http://www.ncbi.nlm.nih.gov/gquery/?term='</span>+name+<span class="hljs-string">'>Search NCBI</a>]'</span>; } } </code></pre> <ol start="2"> <li><p>The ability to customize the 'About track' popups was added. These callbacks are named fmtMetaValue_* and fmtMetaField_*</p></li> <li><p>The ability to customize mouseover descriptions of the fieldnames was also added. These callbacks are named fmtDetailDescription_* and fmtMetaDescription_*</p></li> <li><p>The ability to remove a field from the popup was added. You can do this by returning null from a fmtDetailField_* and fmtMetaField_* callback;</p></li> </ol> <h1><a class="anchor" aria-hidden="true" id="customizing-left-click-behavior-1"></a><a href="#customizing-left-click-behavior-1" 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>Customizing Left-click Behavior</h1> <p>Beginning with JBrowse 1.5.0, the left-clicking behavior of feature tracks (both HTMLFeatures and CanvasFeatures) is highly configurable. To make something happen when left-clicking features on a track, add an onClick option to the feature track's configuration.</p> <p>In the example configuration below, left-clicks on features will open an embedded popup window showing the results of searching for that feature's name in NCBI's global search, and "search at NCBI" will show in a tooltip when the user hovers over a feature with the mouse:</p> <pre><code class="hljs css languages- {.javascript}"> <span class="hljs-string">"tracks"</span>: [ { <span class="hljs-string">"label"</span> : <span class="hljs-string">"ReadingFrame"</span>, <span class="hljs-string">"category"</span> : <span class="hljs-string">"Genes"</span>, <span class="hljs-string">"class"</span> : <span class="hljs-string">"dblhelix"</span>, <span class="hljs-string">"key"</span> : <span class="hljs-string">"Frame usage"</span>, <span class="hljs-string">"onClick"</span> : { <span class="hljs-string">"label"</span>: <span class="hljs-string">"search at NCBI"</span>, <span class="hljs-string">"url"</span>: <span class="hljs-string">"http://www.ncbi.nlm.nih.gov/gquery/?term={name}"</span> } } ... </code></pre> <p>For details on all the options supported by <strong>onClick</strong>, see <a href="#click-configuration-options" title="wikilink">Click Configuration Options</a>.</p> <p>Note: the style→linkTemplate variable can also be used to specify a URL for left-click on features, but this is a legacy option.</p> <h1><a class="anchor" aria-hidden="true" id="customizing-mouse-over-behavior"></a><a href="#customizing-mouse-over-behavior" 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>Customizing Mouse-over behavior</h1> <p>The onClick→label attribute from the <a href="#customizing-left-click-behavior" title="wikilink">previous section</a> is used as the mouse-over description for features on the HTMLFeatures and CanvasFeatures tracks.</p> <p>In JBrowse 1.11.6, the onClick→label attribute was extended further to allow the mouse-over description to be customized using callbacks and template strings.</p> <p>Example for CanvasFeatures, allows full HTML tooltips if you set <code>unsafeMouseover</code>. Here the {name} template is automatically filled in with the feature info:</p> <pre><code class="hljs css languages- {.javascript}"> <span class="hljs-string">"onClick"</span>: { <span class="hljs-string">"label"</span> : "<<span class="hljs-type">div</span> style=<span class="hljs-symbol">'font</span>:normal <span class="hljs-number">12</span>px Univers,Helvetica,Arial,sans-serif'>Feature name: {name}</div><span class="hljs-string">", "</span>title<span class="hljs-string">" : "</span>{name} {<span class="hljs-keyword">type</span>}<span class="hljs-string">", "</span>action<span class="hljs-string">": "</span>defaultDialog<span class="hljs-string">" }, "</span>unsafeMouseover<span class="hljs-string">": true </span></code></pre> <p>Example for HTMLFeatures, which only allows plain text descriptions but can support newlines (essentially uses <div title="..."> for mouseover).</p> <pre><code class="hljs css languages- {.javascript}"> <span class="hljs-string">"onClick"</span>: { <span class="hljs-string">"label"</span>: <span class="hljs-string">"Feature name {name}\nFeature start {start}\nFeature end {end}"</span>, <span class="hljs-string">"title"</span> : "{<span class="hljs-type">name</span>} {<span class="hljs-keyword">type</span>}<span class="hljs-string">", "</span>action<span class="hljs-string">": "</span>defaultDialog<span class="hljs-string">" } </span></code></pre> <p>Example using a callback (for either HMTLFeatures or CanvasFeatures), using this.feature to access the feature details</p> <pre><code class="hljs css languages- {.javascript}"> <span class="hljs-string">"onClick"</span>: { <span class="hljs-string">"label"</span>: <span class="hljs-string">"function() { return '</span>Feature name: <span class="hljs-string">'+this.feature.get('</span>name'); }<span class="hljs-string">", "</span>title<span class="hljs-string">" : "</span>{name} {<span class="hljs-built_in">type</span>}<span class="hljs-string">", "</span>action<span class="hljs-string">": "</span>defaultDialog<span class="hljs-string">" } </span></code></pre> <p>Note: on CanvasFeatures, the action "defaultDialog" isn't necessary, but it is necessary for HTMLFeatures to keep the default dialog (as of writing, 1.11.6).</p> <p>Also note: The "label" which is used in the text for mouseover will be used for the title of any popup by default, so you might also specify a different title.</p> <p>Also also note: Your mouseover will crash if your features do not have an ID or name, even if you coded the mouseover to not use ID or name.</p> <h1><a class="anchor" aria-hidden="true" id="customizing-right-click-context-menus"></a><a href="#customizing-right-click-context-menus" 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>Customizing Right-click Context Menus</h1> <p>Feature tracks can be configured to display a context menu of options when a user right-clicks a feature item. Here is an example of a track configured with a multi-level right-click context menu:</p> <pre><code class="hljs"> { "feature" : [ "match" ], "track" : "Alignments", "category" : "Alignments", "class" : "feature4", "key" : "Example alignments", "hooks": { "modify": "function( track, feature, div ) { div.style.height = (Math.random()*10+8)+'px'; div.style.backgroundColor = ['green','blue','red','orange','purple'][Math.round(Math.random()*5)];}" }, "menuTemplate" : [ { "label" : "Item with submenu", # hello this is a comment "children" : [ { "label" : "Check gene on databases", "children" : [ { "label" : "Query trin for {name}", "iconClass" : "dijitIconBookmark", "action": "newWindow", "url" : "http://wiki.trin.org.au/{name}-{start}-{end}" }, { "label" : "Query example.com for {name}", "iconClass" : "dijitIconSearch", "url" : "http://example.com/{name}-{start}-{end}" } ] }, { "label" : "2nd child of demo" }, { "label" : "3rd child: this is a track" } ] }, { "label" : "Open example.com in an iframe popup", "title" : "The magnificent example.com (feature {name})", "iconClass" : "dijitIconDatabase", "action": "iframeDialog", "url" : "http://www.example.com?featurename={name}" }, { "label" : "Open popup with XHR HTML snippet (btw this is feature {name})", "title": "function(track,feature,div) { return 'Random XHR HTML '+Math.random()+' title!'; }", "iconClass" : "dijitIconDatabase", "action": "xhrDialog", "url" : "sample_data/test_snippet.html?featurename={name}:{start}-{end}" }, { "label" : "Open popup with content snippet (btw this is feature {name})", "title": "function(track,feature,div) { return 'Random content snippet '+Math.random()+' title!'; }", "iconClass" : "dijitIconDatabase", "action": "contentDialog", "content" : "function(track,feature,div) { return ' </code></pre> <p><h2>{name}</h2> This is some test content about feature {name}! This message brought to you by the number <span style="font-size: 300%">'+Math.round(Math.random()*100)+'</span>. }, { "label" : "function(track,feature,div) { return 'Run a JS callback '+Math.random()+' title!'; }", "iconClass" : "dijitIconDatabase", "action": "function( evt ){ alert('Hi there! Ran the callback on feature '+this.feature.get('name')); }" }, { "label": "Create a url with a callback", "action": "iframeDialog", "iconClass": "dijitIconDatabase", "title": "Create a url with a callback", "url": "function(track,feature) { return '<a href="http://www.example.com?refseq='+track.refSeq.name">http://www.example.com?refseq='+track.refSeq.name</a> +'&featurename='+feature.get('name')+'&start='+feature.get('start')+'&end='+feature.get('end'); }" }, ] }</p> <p>This configuration results in a context menu like the one pictured below. For details on what each of the options supported by menu items does, see <a href="#click-configuration-options" title="wikilink">Click Configuration Options</a>.</p> <p><img src="/docs/assets/config/800px-Jbrowse_rightclick.png" alt="800px|center|thumb|The context menu rendered from this example configuration."></p> <p>To add a separator, put the following item in your menuTemplate</p> <pre><code class="hljs">{ type: 'dijit/MenuSeparator' } </code></pre> <p>Note that you can keep the default right-click menu items in JBrowse by just setting "blank" placeholders in the menuTemplate.</p> <p>"menuTemplate" : [ {<br> "label" : "View details", },<br> {<br> "label" : "Highlight this gene", },<br> {<br> "label" : "Open example.com in an iframe popup", "title" : "The magnificent example.com (feature{name})", "iconClass" : "dijitIconDatabase", "action": "iframeDialog", "url" : "<a href="http://www.example.com?featurename=">http://www.example.com?featurename=</a>{name}" }<br> ]</p> <p>Alternatively, if you are using tracks.conf format, you can build a menuTemplate similar to the above configuration using the following:</p> <pre><code class="hljs">menuTemplate+=json:{"label": "View details"} menuTemplate+=json:{"label": "Highlight this gene"} menuTemplate+=json:{"label": "Open example.com in an iframe popup", "iconClass" : "dijitIconDatabase","action": "iframeDialog","url" : "http://www.example.com?featurename={name}"} </code></pre> <p>This results in a context menu like the one pictured below.</p> <p><img src="/docs/assets/config/600px-Menu-customization2.png" alt="600px|center|thumb|The context menu with default items included."></p> <p>Note: You'll note in the above that "placeholder" menu items are put in place to prevent the default "View details" from being overwritten. There are some caveats with regards to these placeholder items. You can't rearrange them or choose which ones you want. You can only overwrite them. Custom items will overwrite the default ones one-by-one.</p> <h2><a class="anchor" aria-hidden="true" id="click-configuration-options"></a><a href="#click-configuration-options" 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>Click Configuration Options</h2> <p>A click action (left-click on a feature or on an item in a context menu) can be configured to do nearly anything. It can be configured with a string JavaScript callback, like:</p> <p><code>"function( track, feature, featureDiv ) { alert('Run any JavaScript you want here!'); }"</code></p> <p>Or a structure containing options like:</p> <pre><code class="hljs"> { "iconClass" : "dijitIconDatabase", "action" : "iframeDialog", "url" : "http://www.ncbi.nlm.nih.gov/gquery/?term={name}", "label" : "Search for {name} at NCBI", "title" : "function(track,feature,div) { return 'Searching for '+feature.get('name')+' at NCBI'; }" // optional: "hideIframeDialogUrl": true } </code></pre> <p>The available options for a click action are:</p> <ul> <li><p>iconClass: Used only for click actions in context menus. Usually, you will want to specify one of the Dijit icon classes here. Although they are not well documented, a list of available icon classes can be seen at <a href="https://github.com/dojo/dijit/blob/1.7.2/icons/commonIcons.css">https://github.com/dojo/dijit/blob/1.7.2/icons/commonIcons.css</a>.</p></li> <li><p>action: Either a JavaScript function to run in response to the click (e.g. "function(){..}"), or one of the following special strings:</p></li> <li><p>"iframeDialog" - the default - causes the given <strong>url</strong> to be opened in a popup dialog box within JBrowse, in an <code>iframe</code> element. special note: setting the track config <code>hideIframeDialogUrl</code> hides the URL link in the dialog title</p></li> <li><p>"newWindow" - causes the given <strong>url</strong> to be opened in a new browser window.</p></li> <li><p>"navigateTo" - added in JBrowse 1.10.8, opens the given <strong>url</strong> in the same browser window, navigating the user away from JBrowse.</p></li> <li><p>"contentDialog" - causes the JavaScript string or callback set in the <strong>content</strong> option to be displayed in the dialog box.</p></li> <li><p>"defaultDialog" - Performs the normal popup action. See <a href="#customizing-mouse-over-behavior" title="wikilink">JBrowse_Configuration_Guide#Customizing_Mouse-over_behavior</a> for an example of when this is useful.</p></li> <li><p>"xhrDialog" - causes the given <strong>url</strong> to be opened in a popup dialog, containing the HTML fetched from the given <strong>url</strong> option. The difference between "iframeDialog" and "xhrDialog" is that an iframeDialog's URL should point to a complete web page, while an xhrDialog's URL should point to a URL on the same server (or that supports <a href="http://gmod.org/wiki/CORS">CORS</a>) that contains just a snippet of HTML (not a complete web page). For those familiar with GBrowse, the xhrDialog is similar to GBrowse popup balloons that use a <em>url:...</em> target, while the contentDialog is similar to a GBrowse popup balloon with a normal target. GBrowse does not have an equivalent of the iframeDialog.]</p></li> <li><p>"Javascript callback" - If you use a javascript callback for the action parameter, then the function signature will be function(clickEvent) { ... } and the clickEvent doesn't contain particularly useful info, but you can access the feature object using this.feature.get('name'); for example.</p></li> <li><p>content: string (interpolated with feature fields) or JS callback that returns either a string or (beginning in 1.10.0) a dojo/Deferred object that will resolve to a string. Used only by a contentDialog.</p></li> <li><p>url: URL used by newWindow, xhrDialog, or iframeDialog actions.</p></li> <li><p>label: descriptive label for the link. In a right-click context menu, this will be the text in the menu item. In a onClick section, it will be the mouse-over description too. See <a href="#customizing-mouse-over-behavior" title="wikilink">JBrowse_Configuration_Guide#Customizing_Mouse-over_behavior</a> for details on the mouse-over behavior.</p></li> <li><p>title: title used for the popup window</p></li> </ul> <h3><a class="anchor" aria-hidden="true" id="using-callbacks-to-customize-feature-tracks"></a><a href="#using-callbacks-to-customize-feature-tracks" 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>Using callbacks to customize feature tracks</h3> <p>JBrowse feature tracks, and individual JBrowse features, can be customized using JavaScript functions you write yourself. These functions are called every time a feature in a track is drawn, and allow you to customize virtually anything about the feature's display. What's more, all of the feature's data is accessible to your customization function, so you can even customize individual features' looks based on their data.</p> <p>As of JBrowse 1.3.0, feature callbacks are added by directly editing your trackList.json file with a text editor. Unfortunately, due to the limitations of the JSON format currently used for JBrowse configuration, the function must appear as a quoted (and JSON-escaped) string, on a single line. You may use the .conf format for the ability to specify functions that span multiple lines.</p> <p>Here is an example feature callback, in context in the trackList.json file, that can change a feature's <code>background</code> CSS property (which controls the feature's color) as a function of the feature's name. If the feature's name contains a number that is odd, it give the feature's HTML <code>div</code> element a red background. Otherwise, it gives it a blue background.</p> <pre><code class="hljs"> { "style" : { "className" : "feature2" }, "key" : "Example Features", "feature" : [ "remark" ], "urlTemplate" : "tracks/ExampleFeatures/{refseq}/trackData.json", "hooks": { "modify": "function( track, f, fdiv ) { var nums = f.get('name').match(/\\d+/); if( nums && nums[0] % 2 ) { fdiv.style.background = 'red'; } else { fdiv.style.background = 'blue'; } }" }, "compress" : 0, "label" : "ExampleFeatures", "type" : "FeatureTrack" }, </code></pre> </span></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="/docs/embedding.html">← Embedding JBrowse</a><a class="docs-next button" href="/docs/configuration_file_formats.html">Configuration File Formats →</a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#customizing-parts-of-the-view-details-pop-ups-with-callbacks">Customizing parts of the 'View details' Pop-ups with callbacks</a><ul class="toc-headings"><li><a href="#rendering-html-in-popups">Rendering HTML in popups</a></li><li><a href="#additional-customizations-to-the-pop-up-boxes">Additional customizations to the pop-up boxes</a></li></ul></li><li><a href="#generic-track-configuration-options">Generic Track Configuration Options</a></li><li><a href="#customizing-parts-of-the-view-details-pop-ups-with-callbacks-1">Customizing parts of the 'View details' Pop-ups with callbacks</a><ul class="toc-headings"><li><a href="#additional-customizations-to-the-pop-up-boxes-1">Additional customizations to the pop-up boxes</a></li></ul></li><li><a href="#click-configuration-options">Click Configuration Options</a><ul class="toc-headings"><li><a href="#using-callbacks-to-customize-feature-tracks">Using callbacks to customize feature tracks</a></li></ul></li></ul></nav></div><footer class="nav-footer" id="footer"><section class="sitemap"><div><h5>Docs</h5><a href="/blog">Blog</a><a href="/docs/tutorial.html">Getting Started</a></div><div><h5>Community</h5><a href="https://gitter.im/GMOD/jbrowse">Project Chat</a><a href="https://twitter.com/JBrowseGossip" target="_blank" rel="noreferrer noopener">Twitter</a></div><div><h5>More</h5><a href="https://github.com/GMOD/jbrowse">GitHub</a><a class="github-button" href="https://github.com/GMOD/jbrowse" data-icon="octicon-star" data-count-href="/GMOD/jbrowse/stargazers" data-show-count="true" data-count-aria-label="# stargazers on GitHub" aria-label="Star this project on GitHub">Star</a></div></section><section class="copyright">Copyright © 2019 Evolutionary Software Foundation</section></footer></div></body></html>