JBrowse 2 · Linear Genome View examples

Session & drawer

Open on a session snapshot, hide the editing UI, or move widgets into a side drawer.

Open on a default session

A session is JBrowse’s runtime representation of “what’s open”: which views, which tracks, which display settings. defaultSession restores one on first paint. Each entry in view.tracks names a track config, and each display under it names its display config by configuration.

Display settings themselves do not go on those session display nodes. A session node is built by the display’s state model, while nearly every setting — height, color, colorBy — is a config slot, so a slot name written there is dropped exactly like a misspelling: the session loads, the track appears, and the setting silently does nothing. Put it on the track’s own displays entry, or use displaySnapshot on an init.tracks entry, which routes slots onto the display config for you. jbrowse validate reports the wrong side of this.

For most embeds the declarative init field is easier to author anyway. Reach for defaultSession when you’re round-tripping a session out of JBrowse Web.

The fastest way to get one is to build the view graphically in JBrowse Web, use File → Export session, and lift the view out of the download:

import sessionJson from './session.json'

const defaultSession = {
  name: 'My session',
  view: sessionJson.session.views[0],
}

The available fields come from the LinearGenomeView state model.

View source — 47 lines
import {
  JBrowseLinearGenomeView,
  useCreateViewState,
} from '@jbrowse/react-linear-genome-view2'

export default function DefaultSession() {
  const state = useCreateViewState({
    assembly: {
      name: 'volvox',
      uri: 'https://jbrowse.org/genomes/volvox/volvox.2bit',
    },
    tracks: [
      {
        type: 'FeatureTrack',
        trackId: 'volvox_gff3',
        name: 'Volvox genes',
        assemblyNames: ['volvox'],
        adapter: {
          type: 'Gff3TabixAdapter',
          uri: 'https://jbrowse.org/code/jb2/main/test_data/volvox/volvox.sort.gff3.gz',
        },
      },
      {
        type: 'AlignmentsTrack',
        trackId: 'volvox-long-reads-sv-bam',
        name: 'volvox-long reads with SV',
        assemblyNames: ['volvox'],
        adapter: {
          type: 'BamAdapter',
          uri: 'https://jbrowse.org/code/jb2/main/test_data/volvox/volvox-long-reads-sv.bam',
        },
      },
    ],
    defaultSession: {
      name: 'My session',
      view: {
        type: 'LinearGenomeView',
        init: {
          loc: 'ctgA:1105..1221',
          assembly: 'volvox',
          tracks: ['volvox-long-reads-sv-bam'],
        },
      },
    },
  })
  return <JBrowseLinearGenomeView viewState={state} />
}

Disable the add-track UI

disableAddTracks hides the + Add track button for a locked-down embed.

It also disables the on-the-fly track-creation features that go through that flow, such as sequence search and multi-wiggle tracks, and it empties the File menu for a host that asked for one with menuBar: Open track… and Open connection… are the same affordances by another route, so with both gone the bar has nothing left to hold and is not drawn.

Users can still toggle the tracks you provided on and off; they just can’t introduce new ones.

View source — 26 lines
import { LinearGenomeView } from '@jbrowse/react-linear-genome-view2'

// managed API: props are initial values, the component owns the engine
export default function DisableAddTrack() {
  return (
    <LinearGenomeView
      assembly={{
        name: 'volvox',
        uri: 'https://jbrowse.org/genomes/volvox/volvox.2bit',
      }}
      tracks={[
        {
          type: 'FeatureTrack',
          trackId: 'volvox_gff3',
          name: 'Volvox genes',
          assemblyNames: ['volvox'],
          adapter: {
            type: 'Gff3TabixAdapter',
            uri: 'https://jbrowse.org/code/jb2/main/test_data/volvox/volvox.sort.gff3.gz',
          },
        },
      ]}
      disableAddTracks
    />
  )
}

Widgets in a side drawer

Widgets — the hierarchical track selector, feature details — open in a resizable side drawer, the way JBrowse Web does it. It moves left or right via the ⋮ menu, minimizes and closes.

A drawer needs the view beside it to be tall against something, so an otherwise content-height view gets bounded while one is open: height on createViewState if you passed one, drawerViewHeight (default '100vh') otherwise. Both sides of that bound scroll — the drawer, and the tracks beside it, under a header that stays put. With the drawer on the left that is the JBrowse 1 arrangement: sidebar, header, scrolling tracks. Prefer height, which does the same without waiting for a drawer — see fitting the view in a fixed-height box.

menuBar is on here, which is the other thing this page shows: the app-shaped File bar above the view, off by default everywhere else. Its two items open a track or a connection, and both land in this same drawer.

init.tracklist opens the track selector on load. Prefer it to calling activateTrackSelector on the built engine: init opens the drawer and waits for the view to be resized around it before navigating, so the region is framed at the width it ends up drawn at. Clicking a feature opens its BaseFeatureWidget there too — see customizing feature details. Widgets are session actions: session.addWidget(type, id, initialState) then session.showWidget(widget).

View source — 45 lines
import {
  JBrowseLinearGenomeView,
  useCreateViewState,
} from '@jbrowse/react-linear-genome-view2'

export default function WithDrawerWidget() {
  const state = useCreateViewState({
    assembly: {
      name: 'volvox',
      uri: 'https://jbrowse.org/genomes/volvox/volvox.2bit',
    },
    tracks: [
      {
        type: 'FeatureTrack',
        trackId: 'volvox_gff3',
        name: 'Volvox genes',
        assemblyNames: ['volvox'],
        adapter: {
          type: 'Gff3TabixAdapter',
          uri: 'https://jbrowse.org/code/jb2/main/test_data/volvox/volvox.sort.gff3.gz',
        },
      },
    ],
    // a drawer needs the view beside it to be tall against something, and
    // `height` is that. Spelled out here because this is the page about the
    // drawer; with no height at all the view is bounded to '100vh' while a
    // drawer is open and content-height otherwise
    height: '100vh',
    // the app-shaped File menu, off unless a host asks for it. Its two items
    // open a track or a connection -- into the drawer, like every other widget
    menuBar: true,
    init: {
      loc: 'ctgA:1105..1221',
      tracks: ['volvox_gff3'],
      // open the hierarchical track selector in the drawer on first paint.
      // Declaring it rather than calling activateTrackSelector() on the built
      // engine is what gets the ordering right: init opens the drawer and waits
      // for the view to be resized around it *before* navigating, so the region
      // is framed at the width it will actually be drawn at. Clicking a feature
      // opens its details widget in the same drawer.
      tracklist: true,
    },
  })
  return <JBrowseLinearGenomeView viewState={state} />
}

Fitting the view in a fixed-height box

height takes any CSS height and bounds the component itself — all of it, so a menuBar row comes out of the total and the view takes the rest. Without it the view draws at content height and the page grows as tracks are added — right for a document, wrong for a panel.

Bounded, the view keeps its chrome in place and scrolls only the tracks: the title bar, the navigation bar, the overview scalebar and the coordinate ruler pin to the top of the box, the way JBrowse Web pins them and the way JBrowse 1 always did. Put the track selector in a drawer on the left and that is the whole JBrowse 1 arrangement — sidebar, header, scrolling tracks.

A host box with a height of its own still bounds the view, and this is where it differs: the box scrolls the whole component, chrome included, so the ruler leaves the top along with the first track and no CSS you write outside can pin it. The prop is what puts the scroll region inside the view, which is what gives the header something to stay behind.

drawerViewHeight is the older spelling of the prop, applying only while a drawer widget is open — it existed because a drawer needs the view beside it to be tall against something, and there was no height that always was. It bounds the view the same way while it applies, headers pinned and all. Pass height instead; drawerViewHeight is honored only when height is absent.

View source — 55 lines
import { LinearGenomeView } from '@jbrowse/react-linear-genome-view2'

export default function FixedHeight() {
  return (
    <LinearGenomeView
      height="400px"
      assembly={{
        name: 'volvox',
        uri: 'https://jbrowse.org/genomes/volvox/volvox.2bit',
      }}
      tracks={[
        {
          type: 'FeatureTrack',
          trackId: 'volvox_gff3',
          name: 'Volvox genes',
          assemblyNames: ['volvox'],
          adapter: {
            type: 'Gff3TabixAdapter',
            uri: 'https://jbrowse.org/code/jb2/main/test_data/volvox/volvox.sort.gff3.gz',
          },
        },
        {
          type: 'QuantitativeTrack',
          trackId: 'volvox_microarray',
          name: 'Microarray (BigWig)',
          assemblyNames: ['volvox'],
          adapter: {
            type: 'BigWigAdapter',
            uri: 'https://jbrowse.org/code/jb2/main/test_data/volvox/volvox_microarray.bw',
          },
          displayDefaults: { height: 150 },
        },
        {
          type: 'AlignmentsTrack',
          trackId: 'volvox-long-reads-sv-bam',
          name: 'volvox-long reads with SV',
          assemblyNames: ['volvox'],
          adapter: {
            type: 'BamAdapter',
            uri: 'https://jbrowse.org/code/jb2/main/test_data/volvox/volvox-long-reads-sv.bam',
          },
          displayDefaults: { height: 200 },
        },
      ]}
      init={{
        loc: 'ctgA:1..50,000',
        tracks: [
          'volvox_gff3',
          'volvox_microarray',
          'volvox-long-reads-sv-bam',
        ],
      }}
    />
  )
}