JBrowse 1

JBrowse Subscribe/Publish events

There are two layers of events, ''internal'' ones used by JBrowse plugins and components to communicate among themselves, and ''external'' ones used by other software to communicate with JBrowse.

external  <->  controller  <->  views

External

Commands

/jbrowse/v1/cmd/*

Notifications

/jbrowse/v1/notify/*

Internal

Internal events are named for where they originate.

/jbrowse/v1/v: messages from views, mostly notifying other components of what logical commands the user is issuing through her actions with the view.

/jbrowse/v1/c: messages from controllers, such as requests to turn on certain tracks, highlight certain features, and so forth.

Milestone functions

The previous section covered the afterMilestone function for waiting on certain tasks to be finished during initialization

Other milestones include:

  • initPlugins - plugins loaded. note: plugins can be loaded before everything else is finished, so plugins may use these milestone functions in their own code
  • loadUserCSS - user CSS loaded
  • loadRefSeqs - reference sequence json or data is loaded
  • loadNames - names store loaded
  • initView - view initialized
  • loadConfig - configurations loaded
  • initTrackMetadata - track metadata loaded
  • createTrack - when track list finished initializing
  • completely initialized - all milestones passed. note the space in the milestone name

Publishing and Subscribing to JBrowse Events

JBrowse client events are implemented using the dojo/topic message bus from the Dojo library. Extensions can subscribe to particular events in order to be notified when certain UI changes happen (for example, highlighting a region generates an event, which can be latched onto with a callback that triggers a request for the server to BLAST that region against a database). In select cases, extensions can also publish events, as a way of forcing the UI into certain states or transitions (for example, events can be used in this way to force the browser to load a new track, in response to some other circumstance or notification).

When events are associated with tracks, the event names take the form /jbrowse/v1/{type}/tracks/{trackEvent}. The {type} is one of ‘v’, ‘c’, or ‘n’, corresponding to view events (requests from the user, handled by the browser); command events (which trigger actions in the UI, and are often generated by the browser in response to view events); or notification events (informing subscribers that something just happened). The {trackEvent} specifies the nature of the track event and is one of ‘new’, ‘delete’, ‘show’, ‘hide’, ‘pin’, ‘unpin’, ‘replace’, ‘redraw’, or ‘visibleChanged’.

When events are global, the event names take the form /jbrowse/v1/{type}/{globalEvent} where {type} is as above and {globalEvent} is one of ‘navigate’ or ‘globalHighlightChanged’.

The DebugEvents plugin logs events to the console, and can be used to monitor events as they are triggered by user interactions with the browser.

Note that you can also publish and subscribe to a JBrowse instance that is in an iframe. See http://gmod.org/wiki/JBrowse_FAQ#How_can_I_get_jbrowse_to_update_the_URL_of_a_parent_page_when_jbrowse_is_inside_of_an_iframe for an example

Examples of publish track events

The Browser.js object is passed to your plugin as args.browser, or is also a global variable window.JBrowse. Henceforth, referred to as 'browser' in the code below

Use the replace event to replace a track config with a new one. You can change the track name or any other config about the track with this, except the store class. This will be discussed further below

browser.publish('/jbrowse/v1/v/tracks/replace', [{ ...config json }]);

You can do operations like delete,hide,show,pin, and unpin tracks like this

browser.publish('/jbrowse/v1/v/tracks/delete', [{ label: 'trackId' }]);
browser.publish('/jbrowse/v1/v/tracks/hide', [{ label: 'trackId' }]);
browser.publish('/jbrowse/v1/v/tracks/show', [{ label: 'trackId' }]);
browser.publish('/jbrowse/v1/v/tracks/pin', [{ label: 'trackId' }]);
browser.publish('/jbrowse/v1/v/tracks/unpin', [{ label: 'trackId' }]);

Adding a new track is not so straightforward because it requires you to manually register the storeClass. The store, e.g. the data file, is registered separately from the track. Here is a code snippet that would add a BAM file to the browser dynamically

var storeName = JBrowse.addStoreConfig(null, {
  browser: JBrowse,
  type: "JBrowse/Store/SeqFeature/BAM",
  baseUrl: ".",
  urlTemplate: "sample_data/raw/volvox/volvox-sorted.bam",
});
JBrowse.publish("/jbrowse/v1/v/tracks/replace", [
  { label: "My track", store: storeName },
]);

You can run this code in the development console at http://jbrowse.org/code/JBrowse-1.16.9/?data=sample_data/json/volvox and see this work

Examples of subscribe events

See https://github.com/GMOD/jbrowse/blob/master/plugins/DebugEvents/js/main.js

← Automating screenshots of JBrowseSample configuration bash script →