=============== NB-dispatch API =============== Overview ======== The Nucleome Browser uses the nb-dispatch library as a hierarchical event dispatcher to enable communication cross-panel or cross-domain. The nb-dispatch is inherited from d3-dispatch, meaning that nb-dispatch has the same initialize method and the same function interface on and call as d3-dispatch. In Nucleome Browser, nb-dispatch will use the Nucleome Bridge to dispatch events between tabs from different domains if chrome browser extension Nucleome Bridge is installed, otherwise, it will use the web browser's Broadcast Channel API to dispatch events between tabs within the same domain. Users can use `nb-dispatch `_ to connect their customized webs to Nucleome Browser and other supported data portals (e.g., the UCSC Genome Browser and the WashU EpiGenome Browser). It is worth noting that the Nucleome Bridge browser extension is required to communicate with the UCSC Genome Browser and the WashU Epigenome Browser. Once a website is connected, navigation or highlight operations on the Nucleome Browser can dispatch to customized websites or \textit{vice versa}. Other websites that are allowed to connect via Nucleome Bridge are listed in the manifest.json file (white list of websites) of the Nucleome Bridge. Currently, a whitelist of websites hosted in these two domains is automatically supported by Nucleome Bridge is shown below. - `*://*.openmicroscopy.org/*`, - `*://epigenomegateway.wustl.edu/*`, - `*://*.4dnucleome.org/*`, - `*://*/*`, - `*://localhost:*/*`, - `https://docs.google.com/*`, - `https://*.googleusercontent.com/*`, - `*://bl.ocks.org/*`, - `*://*.slack.com/*`, - `*://codepen.io/*`, - `*://cdpn.io/*`, - `*://jsfiddle.net/*`, - `*://fiddle.jshell.net/*`, - `*://*.allencell.org/*`, - `*://allencell.org/*` Users can host their website on GitHub Gist and use `https://bl.ocks.org `_ to visualize it. Read more from `https://bl.ocks.org/-/about `_. A few demos of usage of the nb-dispatch is shown at `https://bl.ocks.org/nb1page `_. Please contact us if you want to add your website to the allow-list of websites in Nucleome Bridge. Installation ============ If you use NPM, install nb-dispatch via ``npm install@nucleome/nb-dispatch``. You can also load it on your webpage. .. code-block:: html A minimal example ================= Below is a minimal example showing the usage of the nb-dispatch library. The live version can be accessed from this `minimal example link `_. Basically, in this example, we show how to control the Nucleome Browser to go to a genomic region or highlight multiple regions (Part I). We also show how to monitor operations on Nucleome Browser via nb-dispatch. Note that this example requires the Nucleome Bridge browser extension. .. code-block:: html An exmaple of nb-dispatch

This is a minimal example showing how to create a customized website to communicate with Nucleome Browser using nb-dispatch

Open Nucleome Browser

Part I: Control Nucleome Browser

Click the following buttons to goto centain genomic region or highligh multiple regions

Part II: Monitor the operations of Nucleome Browser

Navigate or highlight regions on Nucleome Browser and show the current genomic region or highlighted regions below

Current genomic region
Current highlighted region
API reference ============= The nb-dispatch is built based on d3-dispatch. It has the same initialize method and the same function interface on and call as d3-dispatch. Below are specific features provided by nb-dispatch that are different from d3-dispatch. - **nb.dispatch** *(types)*: Create new nb-dispatch event object for specific event types. Here, each type should be a string such as ``update`` and ``brush``. Event type ``update`` indicates navigating to the current genomic region. Event type ``brush`` indicates highlight certain genomic regions. Example of usage: .. code-block:: javascript var c = nb.dispatch("update","brush") c.connect(function(){ console.log(c.status()) c.disconnect() } - **nb.dispatch.call** *(type[, that[, arguments...]])*: Invoke each callback for a specific type (update or brush). Arguments are a list of genomic regions each of which has a format of {genome:string, chr:string, start:int, end:int, color:color}. Note that the position of start and end is 0-base. Color is only effective for the brush type. .. code-block:: javascript var navigate = function(){ chan.call("update",this,[{chr:"chr1",start:0,end:10000000}]) } var highlight = function() { chan.call("brush",this,[{ chr:"chr1",start:0,end:1000000,color:"red" },{ chr:"chr1",start:2000000,end:3000000,color:"orange" }]) } - **nb.dispatch.connect** *(callback)*: Connect to event-dispatch hub via the HMTL BroadCast Channel or Nucleome Bridge extension - **nb.dispatch.disconnect** *()*: Disconnect from the HMTL BroadCast Channel or Nucleome Bridge extension - **nb.dispatch.status** *()*: Check out the status of current connected channel. The output is one of ``Extension``, ``Channel``, or ``None`` - **nb.dispatch.chanId** *(channelName)*: Set the channel ID before connect to it. If there are no arguments, it will return the current channel ID. The default channel ID is ``cnbChan0```