Skip to main content

API

This guide will cover the API level documentation for methods and tools useful to developers looking to enhance JBrowse or write plugins.

You can add menus or add items to existing menus in several places.

In these different places, a MenuItem object defines the menu item's text, icon, action, and other attributes.

Types of MenuItems:

  • Normal: a standard menu item that performs an action when clicked
  • Checkbox: a menu item that has a checkbox
  • Radio: a menu item that has a radio button icon
  • Divider: a horizontal line (not clickable) that can be used to visually divide menus
  • SubHeader: text (not clickable) that can be used to visually label a section of a menu
  • SubMenu: contains menu items, for making nested menus
NameDescription
typeOptions are 'normal', 'radio', 'checkbox', 'subMenu', 'subHeader', or 'divider'. If not provided, defaults to 'normal', unless a subMenu attribute is present, in which case it defaults to 'subMenu'.
labelThe text for the menu item. Not applicable to 'divider', required for all others.
subLabelAdditional descriptive text for the menu item. Not applicable to 'divider' or 'subHeader', optional for all others.
iconAn icon for the menu item. Must be compatible with Material-UI's Icons. Not applicable to 'divider' or 'subHeader', optional for all others.
disabledWhether or not the menu item is disabled (meaning grayed out and not clickable). Not applicable to 'divider' or 'subHeader', optional for all others.
checkedWhether or not the checkbox or radio button are selected. Only applicable to 'radio' and 'checkbox'
onClickCallback of action to perform on click. Function signature is (session) => undefined. Required for 'normal', 'radio', and 'checkbox', not applicable to any others.
subMenuAn array of menu items. Applicable only to 'subMenu'.

As an example, the here is an array of MenuItems and the resulting menu:

;[
{
label: 'Normal menu item',
icon: AddIcon,
onClick: () => {},
},
{
label: 'Normal',
subLabel: 'with subLabel',
icon: AddIcon,
onClick: () => {},
},
{
label: 'Disabled menu item',
disabled: true,
icon: AddIcon,
onClick: () => {},
},
{
type: 'radio',
label: 'Radio checked',
checked: true,
onClick: () => {},
},
{
type: 'radio',
label: 'Radio unchecked',
checked: false,
onClick: () => {},
},
{
type: 'checkbox',
label: 'Checkbox checked',
checked: true,
onClick: () => {},
},
{
type: 'checkbox',
label: 'Checkbox unchecked',
checked: false,
onClick: () => {},
},
{ type: 'divider' },
{ type: 'subHeader', label: 'This is a subHeader' },
{
label: 'SubMenu',
subMenu: [
{
label: 'SubMenu item one',
onClick: () => {},
},
{
label: 'SubMenu item two',
onClick: () => {},
},
],
},
]
This screenshot shows all the various track menu options, generated by the code listing
Figure: This screenshot shows all the various track menu options, generated by the code listing

rootModel Menu API

Users can customize the top-level menu items using these functions that are available on the rootModel:

appendMenu

Add a top-level menu

Parameters
NameDescription
menuNameName of the menu to insert.
Return Value

The new length of the top-level menus array

insertMenu

Insert a top-level menu

Parameters
NameDescription
menuNameName of the menu to insert.
positionPosition to insert menu. If negative, counts from the end, e.g. insertMenu('My Menu', -1) will insert the menu as the second-to-last one.
Return Value

The new length of the top-level menus array

appendToMenu

Add a menu item to a top-level menu

Parameters
NameDescription
menuNameName of the top-level menu to append to.
menuItemMenu item to append.
Return Value

The new length of the menu

insertInMenu

Insert a menu item into a top-level menu

Parameters
NameDescription
menuNameName of the top-level menu to insert into.
menuItemMenu item to insert.
positionPosition to insert menu item. If negative, counts from the end, e.g. insertMenu('My Menu', -1) will insert the menu as the second-to-last one.
Return Value

The new length of the menu

appendToSubMenu

Add a menu item to a sub-menu

Parameters
NameDescription
menuPathPath to the sub-menu to add to, starting with the top-level menu (e.g. ['File', 'Insert']).
menuItemMenu item to append.
Return value

The new length of the sub-menu

insertInSubMenu

Insert a menu item into a sub-menu

Parameters
NameDescription
menuPathPath to the sub-menu to add to, starting with the top-level menu (e.g. ['File', 'Insert']).
menuItemMenu item to insert.
positionPosition to insert menu item. If negative, counts from the end, e.g. insertMenu('My Menu', -1) will insert the menu as the second-to-last one.
Return value

The new length of the sub-menu

Extension points

In the core codebase, we have the concept of extension points that users can call or add to.

The API is

// extra props are optional, can pass an extra context object your extension point receives
pluginManager.evaluateExtensionPoint(extensionPointName, args, props)

There is also an async method:

// extra props are optional, can pass an extra context object your extension point receives
pluginManager.evaluateAsyncExtensionPoint(extensionPointName, args, props)

Users can additionally add to extension points, so that when they are evaluated, it runs a chain of callbacks that are registered to that extension point:

pluginManager.addToExtensionPoint(extensionPointName, callback => newArgs)

The newArgs returned by your callback are passed on as the args to the next in the chain.

Here are the extension points in the core codebase:

Core-extendPluggableElement

args:

  • pluggableElement:PluggableElement - this

type: synchronous

used to add extra functionality to e.g state tree models, for example, extra right-click context menus. your callback will receive every pluggable element registered to the system

https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/dotplot-view/src/extensionPoints.ts#L9-L43

Core-guessAdapterForLocation

type: synchronous

used to infer an adapter type given a location type from the "Add track" workflow. you will receive a callback asking if you can provide an adapter config given a location object

https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/gff3/src/index.ts#L27-L53

Core-guessTrackTypeForLocation

type: synchronous

used to infer a track type given a location type from the "Add track workflow"

example https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/alignments/src/index.ts#L108-L118

Core-extendSession

type: synchronous

used to extend the session model itself with new features

  • session: AbstractSessionModel - instance of the session model to extend

TrackSelector-multiTrackMenuItems

type: synchronous

used to add new menu items to the "shopping cart" in the header of the hierarchical track menu when tracks are added to the selection

example https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/wiggle/src/CreateMultiWiggleExtension/index.ts#L10-L67

LaunchView-LinearGenomeView

type: async

launches a linear genome view given parameters. it is not common to extend this extension point, but you can use it as an example to create a LaunchView type for your own view

  • session: AbstractSessionModel - instance of the session which you can call actions on
  • assembly: string - assembly name
  • loc: string - a locstring
  • tracks: string[] - array of trackIds

https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/linear-genome-view/src/index.ts#L131-L189

LaunchView-CircularView

type: async

similar to LaunchView-LinearGenomeView, this is not common to extend, but you can use it as an example to create a LaunchView type for your own view

  • session: AbstractSessionModel - instance of the session which you can call actions on
  • assembly: string - assembly name
  • tracks: string[] - array of trackIds

https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/circular-view/src/index.ts#L30-L66

LaunchView-SvInspectorView

type: async

launches a sv inspector with given parameters. it is not common to extend this extension point, but you can use it as an example to create a LaunchView type for your own view

  • session: AbstractSessionModel - instance of the session which you can call actions on
  • assembly: string - assembly name
  • uri: string - a url to load
  • fileType?: string - type of file referred to by locstring (VCF|CSV|BEDPE, etc)

https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/sv-inspector/src/index.ts#L21-L61

LaunchView-SpreadsheetView

type: async

launches a sv inspector with given parameters. it is not common to extend this extension point, but you can use it as an example to create a LaunchView type for your own view

  • session: AbstractSessionModel - instance of the session which you can call actions on
  • assembly: string - assembly name
  • uri: string - a url to load
  • fileType?: string - type of file referred to by locstring (VCF|CSV|BEDPE, etc)

https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/spreadsheet-view/src/index.ts#L26-L59

LaunchView-DotplotView

type: async

launches a dotplot with given parameters. it is not common to extend this extension point, but you can use it as an example to create a LaunchView type for your own view

  • session: AbstractSessionModel - instance of the session which you can call actions on
  • views: { loc: string; assembly: string; tracks?: string[] }[] - view params for vertical and horizontal
  • tracks: string[] - trackIds to turn on

https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/dotplot-view/src/LaunchDotplotView.ts#L7-L46

LaunchView-DotplotView

type: async

launches a linear synteny view with given parameters. it is not common to extend this extension point, but you can use it as an example to create a LaunchView type for your own view

  • session: AbstractSessionModel - instance of the session which you can call actions on
  • views: { loc: string; assembly: string; tracks?: string[] }[] - view params for vertical and horizontal
  • tracks: string[] - trackIds to turn on

https://github.com/GMOD/jbrowse-components/blob/6ceeac51f8bcecfc3b0a99e23f2277a6e5a7662e/plugins/linear-comparative-view/src/LaunchLinearSyntenyView.ts#L9-L68

Extension point footnote

Users that want to add further extension points can do so. The naming system, "Core-" just refers to the fact that these extension points are from our core codebase. Plugin developers may choose their own prefix to avoid collisions.