Plugins

More than 40 third-party plugins are available that extend or change JBrowse's functionality. For a list of them, see https://gmod.github.io/jbrowse-registry/.

Installing Plugins

Plugins can be manually copied into the JBrowse `plugins` directory. For example, if you had a plugin called MyAwesomePlugin, you would install it by copying it into the JBrowse-1.x.x/plugins/MyAwesomePlugin directory.

Note: Beginning in JBrowse 1.13.0, you need to use the `*-dev.zip` build of JBrowse if you use any plugins beyond the default ones, and any time you add or change a plugin, you must re-run setup.sh to build the plugin's code into JBrowse.

Also note that plugins that are installed are not necessarily activated for every configuration in a JBrowse installation, they are just available.

Activating Plugins

To activate a plugin, add a plugins configuration variable in your jbrowse_conf.json file in the top-level JBrowse directory, and add an entry telling JBrowse the names of the plugins to load.

Example:

  // array of strings (will look in JBrowse-1.x.x/plugins/MyAwesomePlugin)
  "plugins": [ 'MyAwesomePlugin' ]

or in the text .conf format:

plugins =
    + MyAwesomePlugin
    + PubAnnotation

Writing JBrowse Plugins

The JBrowse plugin system allows users to write their own JavaScript classes and AMD modules to extend JBrowse in nearly any way imaginable. Just a few things that can be done by plugins:

Add new data store adapters to allow JBrowse to read data from existing web services.
Add new track classes for custom track displays and behavior (WebApollo is one well-known plugin that does this).
Add (or remove) options in the JBrowse dropdown menus.
Add new types of track selectors.

Also see this FAQ entry http://gmod.org/wiki/JBrowse_FAQ#How_do_I_create_a_plugin.3F and http://gmod.org/wiki/JBrowse_FAQ#What_is_a_plugin_useful_for.3F

Plugin Components

For an example plugin named MyPlugin, all of its files should be located in plugins/MyPlugin in the main JBrowse directory. There are no restrictions on what a plugin directory may contain.

A plugin is required to have a plugins/MyPlugin/js/main.js file, which is an AMD module that returns a JavaScript "class" that inherits from the JBrowse/Plugin class. JBrowse will create one instance of this class, which will persist during the entire time JBrowse is running. This class's constructor function is the entry point for your plugin's JavaScript code.

If a plugin contains custom CSS rules, it can optionally have a plugins/MyPlugin/css/main.css file as well, which JBrowse will load asynchronously. If your plugin code needs to know when the CSS is finished loading, the cssLoaded property of the plugin object contains a Dojo Deferred that is resolved when the CSS load is complete. Multiple CSS files can be loaded using @import statements in the main.css.

JBrowse also defines an AMD namespace that maps to your plugin's js directory, which your plugin code (and JBrowse itself) can use to load additional AMD modules and JavaScript classes. For example, our MyPlugin example could have a data-store adaptor in the file plugins/MyPlugin/js/Store/SeqFeature/FooBaseServices.js, which would be loaded with the module name "MyPlugin/Store/SeqFeature/FooBaseServices".

Example `main.js`

Here is an example plugin main.js, implemented using the Dojo declare class system.

define([
           'dojo/_base/declare',
           'JBrowse/Plugin'
       ],
       function(
           declare,
           JBrowsePlugin
       ) {

return declare( JBrowsePlugin,
{
    constructor: function( args ) {
        var browser = this.browser;

        /* do anything you need to initialize your plugin here */
    }
});

});

Example plugin directory contents

plugins/MyPlugin/js
- plugins/MyPlugin/js/main.js
- plugins/MyPlugin/js/MyPlugin.profile.js
plugins/MyPlugin/css
- plugins/MyPlugin/css/main.css
plugins/MyPlugin/img
- plugins/MyPlugin/img/myimage.png

The bin/new-plugin.pl will initialize a directory structure for you, e.g. run

bin/new-plugin.pl MyPlugin

Distributing plugins via npm

Distributing a plugin via npm JBrowse 1.13.0 and higher can also use plugins that are distributed via npm. To distribute your plugin on npmjs.org, you just need to add a package.json file to the top-level directory of your plugin, and your plugin's npm package name must end in '-jbrowse-plugin'. Note that the plugin is named "my-jbrowse-plugin" on npm, and includes a "jbrowsePlugin"

Here is an example package.json file for MyPlugin:

{
  "name": "my-jbrowse-plugin",
  "version": "1.0.0",
  "description": "JBrowse client plugin for adding amazing things",
  "main": "js/main.js",
  "author": "Josephina Example",
  "license": "SEE LICENSE FILE IN LICENSE.md",
  "dependencies": {
  },
  "devDependencies": {
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/josephina/myplugin.git"
  },
  "keywords": [
    "genome",
    "jbrowse"
  ],
  "bugs": {
    "url": "https://github.com/josephina/myplugin/issues"
  },
  "homepage": "https://github.com/josephina/myplugin#readme",
  "jbrowsePlugin": {
    "name": "MyPlugin"
  }
}

Other useful classes

Implementers of plugins can extend different parts of JBrowse. Three track lists are currently implemented: JBrowse/View/TrackList/Simple, JBrowse/View/TrackList/Hierarchical, and JBrowse/View/TrackList/Faceted.

The Hierarchical and Faceted track lists use the track metadata store (JBrowse/Store/TrackMetaData), which is instantiated and kept by the Browser object, for access to track metadata (defined as specified in the “Data Sources” section). In particular, the category used by the hierarchical track selector is a piece of track metadata called “category”.

The JBrowse/GenomeView class manages the main genome view, where the tracks are displayed (see Figure 1). It manages showing and hiding tracks, reordering them, scrolling and zooming, and so forth.

Track objects query data from a feature store, and draw it in the GenomeView pane. The implementations are in JBrowse/View/Track/ for which the base class is JBrowse/View/Track/BlockBased.

CanvasFeatures tracks use various glyph subclasses, locatable in the JBrowse/View/FeatureGlyph/ directory and inheriting from the base class JBrowse/View/FeatureGlyph.