09f26ed9a7dcc52b03b4d3e5b2f97c5177cd9334
max
  Mon Sep 21 06:00:40 2026 -0700
Drop the ${hgsid} trackDb variable; add session ids to links in the browser instead

A description page's links can carry the session id without the page itself holding
one.  addHgsidToLinks() in utils.js walks the rendered page and appends hgsid to every
<a href> that stays on this host and points into the same cgi-bin directory: a relative
CGI link gets one, a static .html, a link to another host, a mailto and a plain #anchor
do not, and a link that already names a session is left alone.  hgc and hgTrackUi call
it through a new jsAddHgsidToLinks(), and hgTracks.js calls it on the track description
popup once the ajax content is in.  A link written with a literal $hgsid is rewritten
rather than skipped, so the description pages already deployed in the GenArk hubs work
again.

hVarSubst no longer knows about hgsid: it is out of the trackDb variable list, so
hVarSubstTrackDbHtml is a hub-only pass again and needs no cart, and hVarSubstWithCart
and webIncludeHelpFileSubst, which existed only to resolve it, are gone.  The variable
is taken out of the trackDb README and out of the twenty-odd description pages that
used it.

refs #38380

diff --git src/hg/makeDb/trackDb/README src/hg/makeDb/trackDb/README
index 66568dd11ef..32c80daf026 100644
--- src/hg/makeDb/trackDb/README
+++ src/hg/makeDb/trackDb/README
@@ -1,165 +1,168 @@
 This directory contains the track database for
 the UCSC human genome browser.  The program
 hgTrackDb converts the information here into
 a 'trackDb' table in the assembly's MySQL database.
 
 SEE ALSO: source tree file: src/product/README.trackDb
 	  for a general discussion of developing tracks.
 
           trackDb.ra documentation:
           http://genome.ucsc.edu/goldenPath/help/trackDb/trackDbDoc.html
 
 	  http://genome.ucsc.edu/admin/hgFindSpecHowTo.html
 	  for instructions on hgFindSpec.
 
 The bulk of the information about a track is
 contained in the trackDb.ra file.  Tracks are
 separated from each other in this file by
 a blank line.  Each line begins with an
 attribute name and is followed by attribute
 value separated by white space.
 
 The html text about a track is in separate
 files named xxx.html where xxx is a
 track name.  The contents of the HTML is subject
 to variable substitution as described below.
 Note that the html file in lower-level directories
 can override the html in higher-level directories
 without requiring an entry in trackDb.ra.
 
 There may be subdirectories for each organism such
 as 'mouse', and underneath these directories for
 each database, such as 'mm10'.  There are a trackDb.ra
 file and xxx.html files in these subdirectories.
 Track descriptions in the subdirectory will
 over-ride track descriptions in the parent directory.
 This allows you to customize a track for
 each version of the database.
 
 xxx.html files may include the contents of other files
 using this syntax:
 
 <!--#insert file="sharedText.html"-->
 
 where "sharedText.html" is a relative path, relative to
 the directory that contains the xxx.html file.
 This can also be made conditional on a database:
 
 <!-- #if (db==hg19) #insert file="human/hg19/specialNote.html" -->
 
 Variable substitution:
 
 The shortLabel and longLabel fields and the associated HTML files
 may have the following variables, which will be substituted:
      ${ORGANISM} - all upper case organism, like 'MOUSE'
      ${Organism} - initial capped organism, like 'Mouse'
      ${organism} - all lower case organism, like 'mouse'
      ${db} - database (like mm3, hg15, etc.)
      ${date} - freeze date of underlying assembly
      ${blurb} - If there is a blurb field in the .ra file this echos it.
      ${matrix} - content of the matrix and optional matrixHeader trackDb setting
                which will be converted to an HTML table. If there is no matrix
                setting, an empty string is substituted.
      ${chainMinScore} -  value that gets substituted into this statement on the
                chain or chainNet html page: 'Chains scoring below a minimum
                score of "${chainMinScore}" were discarded'.
      ${chainLinearGap} - value for the -linearGap matrix used with axtChain
                (e.g. loose, medium). Gets substituted into the chain or
                chainNet html page.
      ${downloadsServer} - the value of the hg.conf downloads.server variable, or
                          hgdownload.soe.ucsc.edu if not set.
      ${track} - the track's own name, as hgTrackUi's g= parameter needs it. For
                a hub track that includes the hub_<id>_ prefix.
      ${parentTrack} - the name of the container the track sits in, a superTrack
                or a composite, in the same form as ${track}. Views are skipped,
                since a view has no description page of its own. For a track that
                is not in a container this is the same as ${track}. Useful for
                linking a subtrack's description page back to its container, e.g.
                <a href="hgTrackUi?db=${db}&amp;g=${parentTrack}">.
-     ${hgsid} - the current session id, in a native trackDb description page
-               only. hgTrackDb has no cart when it loads trackDb, so it leaves
-               the reference alone and hgc and hgTrackUi resolve it when they
-               render the page. It is not available in a hub's description
-               page: a hub is written by someone else, its html is only lightly
-               sanitized, and a session id in a hub page could be sent to the
-               hub's own server by something as ordinary as an <img> tag.
-               A session id is enough on its own to read and write that cart.
+
+There is no variable for the session id, in a native page or a hub's. A
+description page does not need one: a link in it that stays on this server has
+the session id added by JavaScript in the browser, addHgsidToLinks() in
+utils.js, so <a href="hgTrackUi?db=${db}&amp;g=${parentTrack}"> keeps the
+reader in their own session. Substituting a session id into the page itself
+would put it somewhere it can leak, since a description page is often written
+by someone else and its html is only lightly sanitized: an <img> tag pointing
+at an outside address is enough to send the id to that server, and a session id
+alone is enough to read and write that cart.
+
 In addition, if there is an otherDb field set in the .ra file, these
 variables are available:
      ${o_ORGANISM} - all upper case other organism, like 'MOUSE'
      ${o_Organism} - initial capped other organism, like 'Mouse'
      ${o_organism} - all lower case other organism, like 'mouse'
      ${o_db} - other database (like mm3, hg15, etc.)
      ${o_date} - freeze date of underlying other assembly
 
 Any other ra fields may be referenced as a variable.
 
 Always write the braces.  The bare form $name also works, terminated by a
 character other than [0-9A-Za-Z_], and older pages use it, but do not write it
 in anything new and do not document it.  Inside braces any character is allowed
 up to the closing brace, so ${name} leaves room for structured variable names
 later, something $name cannot express.  It also settles what happens when a
 reference is followed by a letter: ${db}Something is unambiguous, $dbSomething
 is read as one long name.  A literal $ is represented as $$.
 
 Here are some details on how to load various track types into the database
 tables:
 
 - type bedGraph [column]
 In this case, the data table is a bed type of table loaded
 with hgLoadBed.  The [column] specified is a numeric column of data
 in the table to be used for the graphing value.  The default column
 to graph would be column five, the 'score'.  All graphing options as
 described in 'type wig' apply to this type of track.
 
 - type bigBed <fieldCount> <extraInfo>
 This uses a binary indexed file rather than a database table.  It is, other than
 substituting "bigBed" for "bed" in the type line, the same as the "type bed".
 
 The database loading procedure for the table is:
  hgBbiDbLink hg18 itemRgbBbTest /gbdb/hg18/bbi/itemRgb.hg18.bb
 The file name given should be a full path name that can be accessed
 by the Apache WEB server.  Or, the file name can also be a
 valid URL to the bb file.
 This loader is equivalent to:
  hgsql hg18 -e 'drop table if exists itemRgbBbTest;
   create table itemRgbBbTest (fileName varchar(255) not null);
   insert into itemRgbBbTest values
   ("/gbdb/hg18/bbi/itemRgb.hg18.bb");'
 
 - type bigWig [lower] [upper]
 This uses a binary indexed file rather than a database table.  It is, other
 than substituting "bigWig" for "wig" in the type line, the same as the
 "type wig".  
 
 The database loading procedure is:
  hgBbiDbLink hg19 myLocalBigWig /gbdb/hg19/bbi/myLocalBigWig.bw
 The file name given should be a full path name that can be accessed
 by the Apache WEB server.  Or, the file name can also be a
 valid URL to the bw file.
 This loader is equivalent to:
  hgsql hg19 -e 'drop table if exists myLocalBigWig; \
   create table myLocalBigWig (fileName varchar(255) not null); \
   insert into myLocalBigWig values
   ("/gbdb/hg19/bbi/myLocalBigWig.bw");'
 
 - type pgSnp
 This type is used for the display of variants (for example, personal genome
 variants).  It will display stacked boxes showing the proportion of reads
 supporting each allele when frequency is available (in case of 2 alleles
 only).  Also the details page will use the UCSC genes to compute any amino
 acid changes.  
 
 The track can be loaded using hgLoadBed and the -sqlTable 
 option (see pgSnp.sql for the format).
 
 
 After editing a track definition here, run ./loadTracks
 which invokes hgTrackDb to bring it into the MySQL database.
 To update your personal copy (on hgwdev-userName) do
     make update
 to do it on genome-test do
     make alpha
 You can also restrict a track to alpha, beta, or public
 by using the release field.