Menus

TL;DR: three surfaces, three mechanisms. The app menu bar takes contributions from a plugin's configure(), guarded by isAbstractMenuManager; a track menu and a right-click menu are the display model's trackMenuItems() and contextMenuItems(), captured from the super method where the display is defined and added to with addDisplayMenuItems from anywhere else. All three carry the same MenuItem[].

Adding a top-level menu#

JBrowse Web, Desktop and React App define File, Add and Tools. The menus plugin adds Help with appendToMenu, which creates the menu when it is absent. The embeddable single-view components have no menu bar at all, so guard with isAbstractMenuManager.

Contribute from configure: the spreadsheet-view plugin registers its view type in install and offers the way to open one in configure.

export default class SpreadsheetViewPlugin extends Plugin {
  name = 'SpreadsheetViewPlugin'

  install(pluginManager: PluginManager) {
    SpreadsheetViewF(pluginManager)
    LaunchSpreadsheetViewF(pluginManager)
  }

  configure(pluginManager: PluginManager) {
    const { rootModel } = pluginManager
    // configure also runs in the web worker, which has no rootModel — the
    // guard is what keeps a menu contribution from throwing there
    if (isAbstractMenuManager(rootModel)) {
      rootModel.appendToMenu('Add', {
        label: 'Spreadsheet view',
        icon: ViewComfyIcon,
        onClick: (session: AbstractViewContainer) => {
          session.addView('SpreadsheetView', {})
        },
      })
    }
  }
}

Adding track menu items#

A track's menu is self.displays.flatMap(d => d.trackMenuItems()), so a display contributes by redefining trackMenuItems. It is a method, not a getter, so capture the super version first — the same super-capture pattern as any extended MST view. This is the shape for a display's own menu, built where the display is defined; to add to one belonging to another plugin, use addDisplayMenuItems below.

.views(self => {
  const { trackMenuItems: superTrackMenuItems } = self
  return {
    /**
     * #method
     */
    trackMenuItems() {
      return [
        ...superTrackMenuItems(),
        ...buildMafTrackMenuItems(self),
        ...mafLaunchMenuItems({
          session: getSession(self),
          model: self,
          view: getContainingView(self) as LinearGenomeViewModel,
        }),
      ]
    },
  }
})

Adding track context-menu items#

Right-clicking a linear track opens contextMenuItems, which can vary by whether the click hit a feature and by which one.

✕

Do it yourselfIn DesktopSession specIn a notebookWith an agent

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 CRAM file (.cram + .crai).This figure uses “volvox-sv (cram)”.
3. Type your region of interest into the location box and press Enter.This figure is at ctgA:1500-2000.

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%3A1500-2000%22%2C%22tracks%22%3A%5B%22volvox_sv_cram%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+linear_align_ctx_menu

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

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1500-2000",
      "tracks": [
        "volvox_sv_cram"
      ]
    }
  ]
}

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

Copy

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1500-2000",
)

view.add_track({
    "type": "AlignmentsTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "CramAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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:1500-2000",
      "tracks": [
        "volvox_sv_cram"
      ]
    }
  ]
}
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.

To add items to a menu on a display you do not own, use addDisplayMenuItems (addViewMenuItems for a view):

• Resolves the display type by name, and appends what your callback returns to what is already there.
• An array of names contributes the same items to several types from one call. Your callback is then handed the union of their models, so it may only use a menu they all have — a menu only one of them has is a compile error rather than a self[menu] that is undefined on the rest.
• group collects several plugins' entries into one submenu. Without it, each contribution becomes its own top-level row.
• undefined from the callback adds nothing, which is how an item scoped to some state opts out.

export default function DotplotReadVsRefMenuItem(pluginManager: PluginManager) {
  addDisplayMenuItems(pluginManager, 'LinearAlignmentsDisplay', {
    menu: 'contextMenuItems',
    group: LAUNCH_LABEL,
    // Offered from the read id, which the hit test carries, so the item is
    // there when the menu opens rather than a fetch later; the feature it needs
    // is resolved in the onClick (normally already in hand, since the fetch
    // rebuilds this menu).
    items: self => {
      const featureId = self.contextMenuFeatureId
      const feature = self.contextMenuFeature
      const track = getContainingTrack(self)
      return featureId === undefined
        ? undefined
        : {
            label: 'Dotplot of read vs ref',
            icon: AddIcon,
            onClick: () => {
              withContextMenuFeature(self, featureId, feature, feat => {
                queueReadVsRefDialog({
                  node: self,
                  track,
                  feature: feat,
                  onSubmit: launchDotplotReadVsRef,
                })
              })
            },
          }
    },
  })
}

MenuItem#

MenuItem is a discriminated union. Every menu-producing view returns MenuItem[].

Every variant except divider and subHeader also takes these:

Clicking a row dismisses the menu unless it is a checkbox or radio, which are settings and stay open. staysOpenOnClick is that rule, exported so a test can assert the behavior.

Builders#

Build rows with these. Import them from @jbrowse/core/ui/menuItems, a React-free entry, so a state model or plugin menuItems module does not pull the Material UI barrel into every host that installs the plugin.

Prefer the plural promotableRadioItems for a whole radio group: it takes the pin as a factory over the option's value, so a group cannot end up one pin short.

Root model menu API#

Called from configure(), guarded by isAbstractMenuManager. A contribution is recorded and merged in each time the menu opens, so none of these return anything and one that throws costs your item rather than the app. A negative position counts from the end.

See also#

• Extension points
• Custom track and display types
• Pluggable elements