@nucleome/nb-dispatch

nb-dispatch is a multi-channel, cross-tab, and cross-domain event dispatcher for Nucleome Browser.

Once you install the Chrome web browser extension Nucleome Bridge, nb-dispatch will use Nucleome Bridge to dispatch event messages between browser tabs across multiple domains, otherwise, it will use the web browser's BroadCast channel API to send event messages between tabs within the same domain.

Users can create custom web applications using nb-dispatch to connect any custom web applications with Nucleome Browser.

Installing

1. Use npm to install nb-dispatch, and import it in JavaScript.

import {dispatch} from "@nucleome/nb-dispatch";

2. To use nb-dispatch in any webpage, add nb-dispatch using the following script.

<script src="https://unpkg.com/@nucleome/nb-dispatch"></script>
<script>
var c = nb.dispatch("update","brush");
c.connect(function(status){
    //add your code callback.
});
</script>

Quick Start

The following scripts create a event-dispatch hub, register two operations (i.e., update and brush), and check connection status.

var c = nb.dispatch("update","brush")
var callback = function(status){
  console.log(status)
}
c.connect(callback)

The following scripts show how to monitor events in other connected panels or web applications.

//receive messages from nucleome bridge or BroadCast dispatch channel.
c.on("update",function(d){
  //Add your code (e.g., if a user navigates to these genome coordinates in other panel, respond accordingly )
})
c.on("update.anything",function(d){
  //similar to “update” but register multiple listeners as d3-dispatch
  //Add your other code (e.g., if a user navigates to these genome coordinates in other panel, respond accordingly )
})
c.on("brush",function(d){
  //Add your code  (e.g., if a user brushes these genome coordinates in other panel, respond accordingly )
})

The following scripts show how to emit event messages to other connected panels or web applications. Note that genomic coordinates follow 0-index format.

var regions = [{genome:"hg38",chr:"chr1",start:1,end:10000, color: "#336289" },{genome:"hg38",chr:"chr2",start:1,end:1000}]
// navigate to specific regions
c.call("update",this,regions)
// highlgith some regions
c.call("brush",this,regions)

Test your code using CodePen or JSFiddle

To further allow users to visualize new data types in Nucleome Browser or link other web applications with our platform, Nucleome Bridge allows user to test their code in Codepen and JSFiddle. Here is a collection of examples in Codepen and a collection of examples in JSfiddle showing how to connect to Nucleome Browser for customized purposes.

Connect any web applications with Nucleome Bridge

Nucleome Bridge also supports synchronized operations with UCSC Genome Browser and WashU EpiGenome Browser.

Due to the web safety reasons, we only allow certain websites to connect with Nucleome Browser, which is specified in the Nucleome Bridge manifest.json file. Besides the aforementioned websites, any local websites, such as *://127.0.0.1:*/* and https://bl.ocks.org/* are allowed to connect to Nucleome Browser. We also have some demos in bl.ocks.org, here is the link. You can view the full list (whitelist) of allowed websites here

If you want to add your website to the whitelist, Please contact us.

Communication code specification

Currently, we use the following rules to represent navigation or highlight of genomic coordinates syntax.

event name: update and brush.
pass data: regions = [region... ]
           region format {genome:string,chr:string,start:int,end:int, color:color}
           color is optional

Start and end are defined the same as bed format.

API Reference

nb-dispatch has the same initialization method and the same function interface such as "on" and "call" as d3-dispatch.

# nb.dispatch(types…) <>

Creates a new dispatch for the specified event types. Each type is a string, such as "update" or "brush".

# dispatch.on(typenames[, callback])

Adds, removes, or gets the callback for the specified typenames. If a callback function is specified, it is registered for the specified (fully-qualified) typenames. If a callback was already registered for the given typenames, the existing callback is removed before the new callback is added.

A specified typename is a string, such as start or end.foo. The type may be optionally followed by a period (.) and a name; the optional name allows multiple callbacks to be registered to receive events of the same type, such as update.foo and update.bar. To specify multiple typenames, separate typenames with spaces, such as update brush or update.foo brush.bar.

To remove a callback with update.foo, say dispatch.on("update.foo", null).

# dispatch.call(type[, that[, arguments…]])

Like function.call, invoke each registered callback for a specified type, passing the callback the specified arguments, with that as the this context.

The following scripts are nb-dispatch functions for communication across channels which are different from d3-dispatch.

# dispatch.connect(callback)

Connect Nucleome Bridge or BroadCast Channel

# dispatch.disconnect()

Disconnect Nucleome Bridge or BroadCast Channel

# dispatch.status()

Check the status of connected channel ( dispatch.status().connection is one of "Extension","None","Channel" )

# dispatch.chanId(channelName)

Set an id of connecting channel. Use this before the connect method. If there are no arguments, get the current channel id. The default channel id is "cnbChan01"