Customizing feature details

The track slot formatDetails takes jexl callbacks that return an object of fields to merge onto a feature: a new key adds a row, an existing key overrides it, and undefined/null hides it. formatAbout does the same for the About track dialog. For complex logic, register a jexl function in a small plugin.

{
  "type": "FeatureTrack",
  "trackId": "genes",
  "assemblyNames": ["volvox"],
  "name": "Genes",
  "formatDetails": {
    "feature": "jexl:{name:'<a href=https://google.com/?q='+feature.name+'>'+feature.name+'</a>',extrafield:'Field added with custom callback:' + feature.name,phase:undefined,type:undefined}"
  },
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  }
}

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "genes",
  "assemblyNames": ["volvox"],
  "name": "Genes",
  "formatDetails": {
    "feature": "jexl:{name:'\''<a href=https://google.com/?q='\''+feature.name+'\''>'\''+feature.name+'\''</a>'\'',extrafield:'\''Field added with custom callback:'\'' + feature.name,phase:undefined,type:undefined}"
  },
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  }
}'

{
  "type": "FeatureTrack",
  "trackId": "genes",
  "assemblyNames": ["volvox"],
  "name": "Genes",
  "formatDetails": {
    "feature": "jexl:{name:'<a href=https://google.com/?q='+feature.name+'>'+feature.name+'</a>',extrafield:'Field added with custom callback:' + feature.name,phase:undefined,type:undefined}"
  },
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  }
}

✕

Do it yourself

The steps behind the figure above, run against your own data.

1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “GFF3Tabix genes”.
3. Drag the bar at the bottom edge of the track to resize it.
4. Type your region of interest into the location box and press Enter.This figure is at ctgA:17200-23200.

In Desktop

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A17200-23200%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22gff3tabix_genes%22%2C%22height%22%3A300%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+customized_feature_details

Session spec

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:17200-23200",
      "tracks": [
        {
          "trackId": "gff3tabix_genes",
          "height": 300
        }
      ]
    }
  ]
}

Loaded against config: test_data/volvox/config.json

In a notebook

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

Copy

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:17200-23200",
            "tracks": [
                {
                    "trackId": "gff3tabix_genes",
                    "height": 300
                }
            ]
        }
    ],
)
app  # display the widget

With an agent

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:17200-23200",
      "tracks": [
        {
          "trackId": "gff3tabix_genes",
          "height": 300
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

The <a> markup is needed only because the link text differs from the URL; a value that is nothing but a URL is linked for you. The slots (feature, subfeatures, depth, maxDepth) are on the formatDetails config docs.

How the returned object is applied#

The callback's object is shallow-merged onto the feature, and the result drives the panel:

• A new key adds a row.
• An existing key replaces that row's value, core fields included: {type: undefined} removes the Type row, {name: ...} rewrites the Name row. length counts as one even though the panel computes it from start/end.
• undefined or null hides the row.
• A non-object return is an error. "jexl:feature.name" where "jexl:{name:feature.name}" was meant replaces the panel with a message naming the track.

The merged feature is what every part of the panel reads, the sequence panel and a plugin's extra panels included, and a saved session keeps the raw feature and re-runs the callbacks on load, so editing a track's formatDetails reshapes an open panel in place.

What a callback can see#

• feature is the clicked feature, or in subfeatures the subfeature being formatted.
• track is the track's config, so one session-wide callback can link out per assembly: "jexl:{ncbi:'https://www.ncbi.nlm.nih.gov/gene/?term='+feature.name+'+'+track.assemblyNames[0]}".
• In subfeatures, parent is the feature this one sits in and depth how far down, 1 for a gene's transcript and 2 for the transcript's exon, so a transcript row can carry its gene's name: "jexl:{gene:parent.name}".

Values are HTML, and bare URLs become links#

Every value passes through an HTML sanitizer, so <b>, <a> and <table> render as markup, and a value that is not recognizable HTML is escaped (a VCF <TRA> allele still reads as <TRA>). A value that is just a URL becomes a link on its own; the cookbook's details recipe links a gene to NCBI that way.

Static fields, depth and maxDepth#

Only a string starting with jexl: is evaluated, so a field that is the same on every feature is written as a plain object. A GFF3 gene nests three levels deep (gene, mRNA, then exon and CDS), and two slots bound how far the panel goes:

• depth bounds the subfeatures callback. At 1 it reformats only the transcript rows.
• maxDepth bounds the panel. At 1 it shows the transcript cards but not the exon and CDS cards inside them, formatted or not.

{
  "type": "FeatureTrack",
  "trackId": "genes_transcripts_only",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  },
  "formatDetails": {
    "feature": {
      "Source": "GENCODE v44",
      "Contact": "helpdesk@example.org",
      "phase": null
    },
    "subfeatures": "jexl:{Transcript:feature.name, phase:undefined}",
    "depth": 1,
    "maxDepth": 1
  }
}

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "genes_transcripts_only",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  },
  "formatDetails": {
    "feature": {
      "Source": "GENCODE v44",
      "Contact": "helpdesk@example.org",
      "phase": null
    },
    "subfeatures": "jexl:{Transcript:feature.name, phase:undefined}",
    "depth": 1,
    "maxDepth": 1
  }
}'

{
  "type": "FeatureTrack",
  "trackId": "genes_transcripts_only",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  },
  "formatDetails": {
    "feature": {
      "Source": "GENCODE v44",
      "Contact": "helpdesk@example.org",
      "phase": null
    },
    "subfeatures": "jexl:{Transcript:feature.name, phase:undefined}",
    "depth": 1,
    "maxDepth": 1
  }
}

Session-wide formatDetails#

The feature, subfeatures, depth and maxDepth slots also exist under configuration.formatDetails, applied to every track:

{
  "configuration": {
    "formatDetails": {
      "feature": "jexl:{Assembly:'hg19', score:undefined}",
      "subfeatures": "jexl:{Assembly:'hg19'}",
      "maxDepth": 2
    }
  }
}

Where a track sets the same slot, feature and subfeatures objects are merged (the track's keys over the session's) and depth/maxDepth override (the track's value wins).

Complex logic goes in a jexl function#

Register a function from a small plugin, as the no-build plugin tutorial shows, and call it from the slot: "feature": "jexl:{name:formatName(feature)}". The function can return a whole object (many attributes relabeled at once) or one value (a dbxref turned into a link).

The feature a formatDetails callback receives is a plain object read from the serialized session, so use property access (feature.start); feature.get('start') fails here. See property access vs get().

The About track dialog#

formatAbout reshapes the "About track" dialog the same way, on the track or session-wide as configuration.formatAbout. The callback's variable is config, the track's own configuration:

{
  "type": "FeatureTrack",
  "trackId": "genes",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  },
  "formatAbout": {
    "hideUris": true,
    "config": "jexl:{Source:'GENCODE v44',adapter:undefined}"
  }
}

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "genes",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  },
  "formatAbout": {
    "hideUris": true,
    "config": "jexl:{Source:'\''GENCODE v44'\'',adapter:undefined}"
  }
}'

{
  "type": "FeatureTrack",
  "trackId": "genes",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "volvox.sort.gff3.gz"
  },
  "formatAbout": {
    "hideUris": true,
    "config": "jexl:{Source:'GENCODE v44',adapter:undefined}"
  }
}

• hideUris drops every file location from the dialog only; config.json still carries them. A session-wide true cannot be turned back on by a track.
• config merges over the config shown, exactly as formatDetails.feature does.

Adding a panel or replacing the widget#

To add a section of your own or replace the widget wholesale, a plugin uses two extension points:

• Core-extraFeaturePanel appends a React component below the built-in sections
• Core-replaceWidget wraps or replaces the whole feature-details widget

See also#

• Using jexl callbacks
• Customizing feature colors
• Extension points