160d10a30597d7435c30409878e2ba11c3e7c660
mspeir
Wed Sep 9 14:19:40 2026 -0700
trackDb docs: stop the shared script from aborting on the pages without a search box, refs #38062
Two JavaScript faults on the trackDb doc pages, both of which trackDbHub.v3.html
had already avoided while the other pages drifted.
trackDbDoc.html, changes.html and trackDbHub.v0/v1/v2.html load /js/utils.js in
their head, and the hgMenubar include further down brings in the same file by a
different path, so it ran twice. utils.js declares mouseoverContainer with let
at top level, so the second run threw a redeclaration error. v3 does not load
utils.js in the head, and the menubar copy is in place well before anything
needs it, so drop the head copy from the other five.
documentLoad() then called addEventListener on the result of
getElementById("tdbSearch") with no null check, and only v3 has that input, so
the function threw partway through on the other four pages and never reached
its end. The search box and jump-to-top button do not exist on those pages, so
nothing visible was lost, but the exception aborted the rest of documentLoad
and would have swallowed anything added after it. Guard the two listeners.
All six pages now load with no console errors, checked in a browser.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
diff --git src/hg/htdocs/goldenPath/help/trackDb/changes.html src/hg/htdocs/goldenPath/help/trackDb/changes.html
index ab2646d648a..c753c837b11 100755
--- src/hg/htdocs/goldenPath/help/trackDb/changes.html
+++ src/hg/htdocs/goldenPath/help/trackDb/changes.html
@@ -1,386 +1,385 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1">
<META name="description" content="UCSC Track Database Definition Changes">
<META name="keywords" content="tracDb, tracks, UCSC, bioinformatics">
<TITLE>UCSC Track Database Definition History</TITLE>
<LINK REL="STYLESHEET" HREF="/style/HGStyle.css">
<LINK REL="STYLESHEET" HREF="trackDbDoc.css">
<script type="text/javascript" src="/js/jquery.js"></script>
<script type="text/javascript" src="/js/staticDoc.js"></script>
- <script type="text/javascript" src="/js/utils.js"></script>
<script type="text/javascript" src="trackDbDoc.js"></script>
</HEAD>
<BODY>
<A NAME="TOP"></A>
<!-- Format everthing inside this narrower "pageWidth" window -->
<div class="pageWidth">
<!--#include virtual="../../../cgi-bin/hgMenubar"-->
<!--Content Tables-->
<!--outer table is for border purposes-->
<div class="contentBorder">
<div class="lightBlueBar">
<div class="lightBlueBarTitle"> Track Database Definition Change History</div>
</div>
<!-- Finally to the content -->
<div class="borderGuard">
<DIV class="trackDbDoc_intro">
<H1>Track Database Definition</H1>
<p>This document summarizes the changes to the <a href="trackDbHub.html">UCSC Genome Browser Hub TrackDb specification</a>.<p>
<TABLE class="settingsTable" id="Common_Settings">
<tbody>
<tr valign="TOP">
<th width="100">Date</th>
<th width="15%">Track Types</th>
<th width="15%">Link to Doc</th>
<th>Change</th>
</tr>
<tr>
<td>2026-09-08</td>
<td>bigBed</td>
<td><a href="trackDbHub.html#detailsScript">detailsScript</a></td>
<td>New plot type <code>scatterPlot</code>, which draws a cloud of background points
from a JSON or TSV file named by <code>dataUrl</code> and marks the clicked item's own
coordinates on it. Background points can carry a category, which colors them and builds
a legend, and a label, which is shown on mouseover. Also new for every plot type: the
<code>exportFields</code> config key, listing further bigBed fields whose values are
passed to the module, and hub-relative resolution of any config key ending in
<code>Url</code>. Such a file is read server-side and must sit inside a connected
hub.</td>
</tr>
<tr>
<td>2026-09-06</td>
<td>bigNet</td>
<td><a href="trackDbHub.html#bigNet_-_Alignment_Nets">bigNet</a></td>
<td>New track type. <code>bigNet</code> holds an alignment net in a bigBed file, so a
track hub can show a real net instead of a net rendered as a maf. The type line is
<code>type bigNet targetDb chainTrack</code>, where <code>chainTrack</code> names the
<a href="/goldenPath/help/bigChain.html">bigChain</a> track in the same hub that holds
the alignments. See the <a href="/goldenPath/help/bigNet.html">bigNet format
description</a>.</td>
</tr>
<tr>
<td>2026-08-31</td>
<td>bigPsl, bigGenePred, bigBarChart, bigLolly</td>
<td><a href="trackDbHub.html#searchIndex">searchIndex</a>,
<a href="trackDbHub.html#searchTrix">searchTrix</a>,
<a href="trackDbHub.html#mouseOver">mouseOver</a>,
<a href="trackDbHub.html#mouseOverField">mouseOverField</a>,
<a href="trackDbHub.html#indelDoubleInsert">indelDoubleInsert</a>,
<a href="trackDbHub.html#indelQueryInsert">indelQueryInsert</a>,
<a href="trackDbHub.html#indelPolyA">indelPolyA</a></td>
<td>Documentation fix, continuing the "For Types" corrections below. Each of these
settings works on types its entry did not name. <code>searchIndex</code> gains
<code>bigPsl</code>, <code>bigGenePred</code> and <code>bigBarChart</code>, and
<code>searchTrix</code> gains <code>bigGenePred</code>; both are read on the
bigBed-backed search path, whatever the flavor. <code>mouseOver</code> and
<code>mouseOverField</code> gain <code>bigLolly</code>. The three
<code>indel*</code> settings named only <code>bam</code> in the library, though this
page has listed them under <code>bigPsl</code> for years; they are read for every
track that draws linked features, so <code>psl</code> and <code>bigPsl</code> are
named now. <code>searchIndex</code> and <code>searchTrix</code> also drop
<code>bed</code>, which never worked: a track in one of our own database tables
configures search through the <code>hgFindSpec</code> table instead. No browser
behavior changed.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>bigLolly</td>
<td><a href="trackDbHub.html#lollyNoStems">lollyNoStems</a></td>
<td>Renamed in the documentation, from <code>noStems</code>. The Browser has always
read <code>lollyNoStems</code>, so a track that set <code>noStems</code> drew its
stems as usual. <code>hubCheck</code> takes its list of valid settings from this
page, so it accepted the spelling that did nothing and rejected the one that works.
If your hub sets <code>noStems</code>, change it to <code>lollyNoStems</code>.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>all</td>
<td><a href="trackDbHub.html#type">type</a></td>
<td>The list of valid types on this page now shows only the types a hub can use.
It had been showing the full list, which includes types that only work for tracks
loaded into our own databases. The three hub types missing from the shorter list,
<code>bigGenePred</code>, <code>bigNarrowPeak</code> and <code>vcfPhasedTrio</code>,
have been added.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>all</td>
<td><a href="trackDbHub.html#canPack">canPack</a>,
<a href="trackDbHub.html#configureByPopup">configureByPopup</a>,
<a href="trackDbHub.html#origAssembly">origAssembly</a></td>
<td>Now listed on this page, and no longer marked as unavailable to hubs. The Browser
reads all three from a hub's trackDb the same way it reads them from ours, so the old
note was wrong. <code>canPack</code> is still marked deprecated: the track type
usually decides whether pack and squish are offered, so you rarely need to set it.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>bigMaf, bigGenePred</td>
<td><a href="trackDbHub.html#speciesGroups">speciesGroups</a>,
<a href="trackDbHub.html#speciesDefaultOff">speciesDefaultOff</a>,
<a href="trackDbHub.html#speciesCodonDefault">speciesCodonDefault</a>,
<a href="trackDbHub.html#itemFirstCharCase">itemFirstCharCase</a>,
<a href="trackDbHub.html#irows">irows</a>,
<a href="trackDbHub.html#intronGap">intronGap</a></td>
<td>Now listed on this page. A bigMaf track is drawn and configured by the same code
as a wigMaf track, so the five multiple-alignment settings have always worked on it,
but only <code>speciesOrder</code> was documented that way. <code>intronGap</code> is
read for every track type that draws linked features, bigGenePred included. Nothing
about their behavior changed.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>bigBed, bigGenePred, bigPsl, bigLolly</td>
<td><a href="trackDbHub.html#filterBy">filterBy</a></td>
<td>Now listed on this page, and no longer marked as unavailable to hubs. The
Browser applies <code>filterBy</code> to bigBed-backed tracks when it loads them, so
it has worked in hubs for some time. If you avoided it because of the old note, you
can use it now.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>bigBed, bigPsl</td>
<td><a href="trackDbHub.html#baseColorTickColor">baseColorTickColor</a></td>
<td>Now listed on this page, and no longer marked as unavailable to hubs. It has
always worked in hubs. The entry now also states the requirement that was missing:
the tick color is worked out from each item's own color, so the setting does nothing
unless the track sets <code>colorByStrand</code>. <code>itemRgb</code> does not
satisfy it.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>bigChain, bigMaf, bigBarChart, bigWig</td>
<td><a href="trackDbHub.html#chainColor">chainColor</a>,
<a href="trackDbHub.html#chainNormScoreAvailable">chainNormScoreAvailable</a>,
<a href="trackDbHub.html#pairwiseHeight">pairwiseHeight</a>,
<a href="trackDbHub.html#barChartMatrixUrl">barChartMatrixUrl</a>,
<a href="trackDbHub.html#mouseOverFunction">mouseOverFunction</a></td>
<td>Now listed on this page. All five have worked in hubs for years, but none had an
entry here, so <code>hubCheck</code> reported them as unrecognized settings.
Nothing about their behavior changed.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>bigBed, bigGenePred, bigPsl, bigChain, bigNarrowPeak, bigMaf, vcfTabix</td>
<td><a href="trackDbHub.html#spectrum">spectrum</a> and 25 others</td>
<td>Documentation fix: the "For Types" list was wrong for 26 settings, so the docs
named the wrong track types for settings that have always worked. Most named only the
older type and left out its <code>big*</code> counterpart, for example
<code>noScoreFilter</code> said <code>bed</code> while its own example uses
<code>type bigBed 6 +</code>, and the <code>hapCluster*</code> settings said
<code>vcf</code> and not <code>vcfTabix</code>. Six others said "all" for a setting
that only works on item tracks. No browser behavior changed.</td>
</tr>
<tr>
<td>2026-08-28</td>
<td>bigPsl</td>
<td><a href="trackDbHub.html#pslSequence">pslSequence</a></td>
<td>Marked deprecated. This setting has never done anything. The variable it
described was replaced by the
<a href="trackDbHub.html#baseColorUseSequence">baseColorUseSequence</a> family long
before the setting was listed here. Use <code>baseColorUseSequence</code> and
<a href="trackDbHub.html#baseColorDefault">baseColorDefault</a> instead:
<code>pslSequence all</code> is now <code>baseColorDefault itemBases</code>, and
<code>pslSequence different</code> is now <code>baseColorDefault diffBases</code>.
The entry is kept rather than deleted so that <code>hubCheck</code> tells you the
setting is deprecated, instead of reporting it as an unrecognized setting and
guessing at a typo.</td>
</tr>
<tr>
<td>2026-07-31</td>
<td>faceted composite</td>
<td><a href="trackDbHub.html#maxCheckboxes">maxCheckboxes</a></td>
<td>Documentation fix: this setting was previously listed here as
<code>maxCheckBoxes</code>, with a capital B. Setting names are case sensitive and the
browser has always read it as <code>maxCheckboxes</code>, so hubs that used the
capitalized spelling fell back to the default of 20 facet values. If your hub sets
<code>maxCheckBoxes</code>, change it to <code>maxCheckboxes</code>.</td>
</tr>
<tr>
<td>2026-07-08</td>
<td><b>genomes.txt setting</b></td>
<td><a href="trackDbHub.html#codonTable">codonTable</a></td>
<td>New <code>codonTable</code> genome-stanza setting (an assembly hub
<code>genomes.txt</code> setting, not a track setting) assigns NCBI genetic
codes to individual sequences for amino acid display, e.g.
<code>codonTable default=1 NC_017929.1=13</code>. Affects the base position
track three-frame translation, codon-colored tracks such as gene
predictions, and details pages. Sequences named chrM/chrMT still default to
the vertebrate mitochondrial code.</td>
</tr>
<tr>
<td>2026-06-02</td>
<td>bigBed, bigGenePred</td>
<td><a href="trackDbHub.html#colorFields">colorFields</a></td>
<td>New <code>colorFields</code> setting adds a <b>Color by:</b> dropdown to the
track controls page, letting users switch among multiple pre-computed color schemes
stored as extra bigBed fields containing <code>R,G,B</code> strings.
The special name <code>default="label"</code> renames the standard itemRgb option.
When a non-default scheme is selected, a <em>(Coloring by: label)</em> suffix
appears in the track long label.</td>
</tr>
<tr>
<td>2026-05-08</td>
<td>bed, bigBed</td>
<td><a href="trackDbHub.html#filterPriority">filterPriority</a> / <a href="trackDbHub.html#highlightPriority">highlightPriority</a></td>
<td>New <code>filterPriority.<fieldName></code> setting controls the
display order of filter controls on the track configuration page. A
companion <code>highlightPriority.<fieldName></code> setting orders
highlight controls.</td>
</tr>
<tr>
<td>2026-04-22</td>
<td>faceted composite tracks</td>
<td><a href="trackDbHub.html#subtrackUrls">subtrackUrls</a></td>
<td>An update for the subtrackUrls option for faceted composites, which
enables links out to other resources in the faceted table.</td>
</tr>
<tr>
<td>2026-04-10</td>
<td>vcf, vcfTabix, vcfPhasedTrio</td>
<td><a href="trackDbHub.html#sampleMetadataFile">sampleMetadataFile</a></td>
<td>Add per-sample metadata columns to the VCF genotype details table.
Points to a tab-separated file with a <code>#sample</code> header line;
columns are appended to the genotype table on the item details page.</td>
</tr>
<tr>
<td>2026-04-08</td>
<td>bigBed</td>
<td><a href="trackDbHub.html#detailsScript">detailsScript</a></td>
<td>Add custom JavaScript visualizations (e.g. histograms) to the item details page.
An ES6 module is loaded on demand and renders into the extra fields table.
First plot type: histogram, for logfmt-encoded allele frequency data.</td>
</tr>
<tr>
<td>2026-03-09</td>
<td>bigBed</td>
<td><a href="trackDbHub.html#faceted_composite">faceted composite</a></td>
<td>An alternate UI for composite tracks with a very large number of subtracks.</td>
</tr>
<tr>
<td>2026-01-12</td>
<td>bigBed</td>
<td><a href="trackDbHub.html#style">style</a></td>
<td>Activates the positional heatmap display mode for a track that meets the schema.</td>
</tr>
<tr>
<td>2026-01-11</td>
<td>hic</td>
<td><a href="trackDbHub.html#hicArcLimit">hicArcLimit</a></td>
<td>Limit the number of arcs displayed in a Hi-C plot, favoring those with the highest scores</td>
</tr>
<tr>
<td>2025-03-31</td>
<td>interact, bigInteract</td>
<td><a href="trackDbHub.html#detailBoxesEnabled">detailBoxesEnabled</a></td>
<td>Used to suppress the link/boxes in interact tracks that would go to a details page.</td>
</tr>
<tr>
<td>2025-03-06</td>
<td>hic</td>
<td><a href="trackDbHub.html#bigDataUrl">bigDataUrl</a></td>
<td>Added hic to the list of supported file types for bigDataUrl.</td>
</tr>
<tr>
<td>2024-06-11</td>
<td>bigBed, bigGenePred, bigChain, bigPsl</td>
<td><a href="trackDbHub.html#highlight">highlightValues.*</a></td>
<td>Allow user to highlight certain features in yellow, if they contain certain values in an extraField</td>
</tr>
<tr>
<td>2024-01-22</td>
<td>bigWig</td>
<td><a href="trackDbHub.html#setColorWith">setColorWith</a></td>
<td>Color a signal plot from a bigWig file by the ranges in a bigBed file</td>
</tr>
<tr>
<td>2023-11-08</td>
<td>bigBed, bigGenePred, bigChain, bigPsl</td>
<td><a href="../decorator.html">decorator.*</a></td>
<td>Semi-transparently overlay annotations, e.g. protein domains on transcripts, mutations on exons, or summits on chip-seq peaks</td>
</tr>
<tr>
<td>2023-10-16</td>
<td>bigGenePred, bigChain, bigPsl</td>
<td><a href="../decorator.html">mouseOver, mouseOverField</a></td>
<td>mouseOver works for all bigBed-based file formats</td>
</tr>
<tr>
<td>2023-06-27</td>
<td>all</td>
<td><a href="trackDbHub.html#maxItems">maxItems</a></td>
<td>Change: <tt>maxItems</tt>, increased default to 10,000, 10x more items can be shown.</td>
</tr>
<tr>
<td>2023-04-04</td>
<td>all</td>
<td><a href="trackDbHub.html#downloadUrl">downloadUrl</a></td>
<td>New: <tt>downloadUrl <fileType> <URL></tt><br>Shows a link where user can download a file. On the UCSC browser, the link is shown above the description page. Right now this is used for GFF files on gene tracks.</td>
</tr>
<tr>
<td>2022-09-30</td>
<td>bigBed, BAM</td>
<td><a href="trackDbHub.html#doWiggle">doWiggle</a></td>
<td>New: <tt>doWiggle on</tt><br>Instead of showing the features, show coverage of features, as a 'wiggle' (signal) style track. Can be switched off by the user on the track config page.</td>
</tr>
<tr>
<td>2022-09-22</td>
<td>bigGenePred</td>
<td><a href="trackDbHub.html#colorByStrand">colorByStrand</a></td>
<td>Change: <tt>colorByStrand</tt> can now be used by bigGenePred-type tracks.</td>
</tr>
<tr>
<td>2022-06-30</td>
<td>bigPsl, bigChain</td>
<td><a href="trackDbHub.html#otherTwoBitUrl">otherTwoBitUrl</a></td>
<td>New: <tt>otherTwoBitUrl <URL></tt><br>This statement allows one to store query sequences in a separate twoBit file rather than in the annotation file itself, which can reduce the size of the annotation file.</td>
</tr>
<tr>
<td>2022-05-14</td>
<td>bigWig</td>
<td><a href="trackDbHub.html#logo">logo</a></td>
<td>New: <tt>logo on</tt><br>Motif logo of the genome sequence, as a "dynseq" display, see <a href='../bigWig.html#Ex4'>the example</a>.</td>
</tr>
<tr>
<td>2022-05-11</td>
<td><b>genomes.txt setting</b></td>
<td><a href="../assemblyHubHelp.html#chromAuthority">chromAuthority</a></td>
<td>New <code>chromAuthority</code> genome-stanza setting (an assembly hub
<code>genomes.txt</code> setting, not a track setting) chooses which
<code>chromAlias</code> name column is displayed by default for the
assembly's sequences, e.g. <code>chromAuthority ucsc</code>.</td>
</tr>
<tr>
<td>2022-05-05</td>
<td>bigMaf, maf</td>
<td><a href="trackDbHub.html#logoMaf">logoMaf</a></td>
<td>New: <tt>logoMaf on</tt><br>Motif logo on MAF/bigMaf alignment tracks. Zooming in on alignment shows nucleotides scaled by phyloP conservation.</td>
</tr>
<tr>
<td>2019-05</td>
<td>all</td>
<td><a href="../hgTracksHelp.html#UseOneFile">useOneFile</a></td>
<td><tt>useOneFile on</tt><br>Adding the 'useOneFile on' line to the hub.txt section of a hub allows the contents of all three files to be referenced inside of one file.</td>
</tr>
</tbody>
</table>
</div>
</div>
</BODY></HTML>