interacting.html

---
layout: page
title: Interacting with the Dalliance API.
---
If you retain a reference to the <code>Browser</code> object corresponding to your Dalliance
instance, you can call methods on this to interact with the genome browser and integrate it
more tightly with your own code.

<h5>setLocation([chr], start, end)</h5>

Call this to navigate to a specific genomic location.  If the specified location is close to the
existing location and the width of the requested region is equal to the currently-displayed region
(+/- ~0.1%) then the operation is handled as a scroll, otherwise Dalliance will reload data in the
new location.  If <code>chr</code> is <code>null</code> or <code>undefined</code>, the current
chromosome is used.

{% highlight javascript %}
function moveRight() {
    browser.setLocation(
        browser.chr,
        (browser.viewStart|0) + 1000,
        (browser.viewEnd|0) + 1000
    );
}
{% endhighlight %}

<h5>addTier(config)</h5>

Create a new browser tier using the specified <a href="config.html">configuration object</a>.

{% highlight javascript %}
browser.addTier({
    name: 'Repeats',
    desc: 'Repeat annotation from Ensembl 59', 
    bwgURI: 'http://www.biodalliance.org/datasets/repeats.bb',
    stylesheet_uri: 'http://www.biodalliance.org/stylesheets/bb-repeats.xml'
});
{% endhighlight %}

<h5>removeTier(config)</h5>

Remove the first browser tier whose configuration matches the specified configuration object.

{% highlight javascript %}
browser.removeTier({
    name: 'Repeats',
    desc: 'Repeat annotation from Ensembl 59', 
    bwgURI: 'http://www.biodalliance.org/datasets/repeats.bb',
    stylesheet_uri: 'http://www.biodalliance.org/stylesheets/bb-repeats.xml'
});
{% endhighlight %}

(This API may change in future to be better behaved when multiple tracks match the same configuration).

<h5>highlightRegion(chr, min, max)</h5>

Create a highlight over the specified genomic region.

<h5>clearHighlights()</h5>

Remove all the highlighted regions.

<h3>Event handlers</h3>

<h5>addViewListener(callback)</h5>

Called when the viewed region changes.  Parameters passed to the callback are:

<ul>
<li><code>chr</code>: current sequence name</li>
<li><code>min</code>: minimum visible position (rounded to int)</li>
<li><code>max</code>: maximim visible position (rounded to int)</li>
</ul>

{% highlight javascript %}
browser.addViewListener(function(chr, min, max) {
    var link = document.getElementById('enslink');
    link.href = 'http://www.ensembl.org/Homo_sapiens/Location/View?r=' + 
        chr + ':' + min + '-' + max;
});
{% endhighlight %}

<h5>addTierListener(callback)</h5>

Called when the set or order of tiers changes.

<h5>addFeatureListener(callback)</h5>

Called when the user clicks on a feature.  Parameters passed to the callback are:

<ul>
<li><code>event</code>: the DOM <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent"><code>MouseEvent</code></a> which triggered this callback.</li>
<li><code>feature</code>: the feature which the user clicked on.</li>
<li><code>hit</code>: an array of Feature and Group objects representing the clicked feature plus any parents.</li>
<li><code>tier</code>: the Dalliance tier in which the click occurred.</li>
</ul>

Note that if you want to display extra information when a feature is clicked, you may be better served by
the <a href="plugins.html#feature-info">Feature Info plugin</a> API.

<h5>addFeatureHoverListener(callback)</h5>

Called when the pointer hovers over a feature.  Probably never called on touch-screen devices.

The callback parameters are the same as for <code>addFeatureListener</code>.

<h5>addInitListener(callback)</h5>

Call on a newly-constructed <code>Browser</code> instance.  The callback is invoked when initializatin
is complete.