Difference between revisions of "GBrowse Popup Balloons"

From GMOD
Jump to: navigation, search
(Linking back to GBrowse: Buug)
m (Text replace - "<perl>" to "<syntaxhighlight lang="perl">")
Line 30: Line 30:
 
== Linking back to GBrowse ==
 
== Linking back to GBrowse ==
 
It is often useful to include links in a popup balloon that change the view in GBrowse. Use a callback to get the desired coordinates for the new view.  Example:
 
It is often useful to include links in a popup balloon that change the view in GBrowse. Use a callback to get the desired coordinates for the new view.  Example:
<perl>
+
<syntaxhighlight lang="perl">
 
balloon hover = sub  {
 
balloon hover = sub  {
 
       my $feature = shift;
 
       my $feature = shift;
Line 423: Line 423:
 
with at least one white space character.
 
with at least one white space character.
  
<perl>
+
<syntaxhighlight lang="perl">
 
# A generic function to display a table of all attribute values
 
# A generic function to display a table of all attribute values
 
# for a feature object
 
# for a feature object

Revision as of 20:05, 8 October 2012

Balloon.png

Using Balloons

GBrowse can display popup balloons when the user hovers over or clicks on a feature. The balloons can display arbitrary HTML, either provided in the config file, or fetched remotely via a URL. You can use this feature to create multiple choice menus when the user clicks on the feature, to pop up images on mouse hovers, or even to create little embedded query forms. See http://mckay.cshl.edu/balloons2.html for examples.

In the config file for the database you wish to modify, set ``balloon tips to a true value:

     [GENERAL]
     ...
     balloon tips = 1

Then add ``balloon hover and/or ``balloon click options to the track stanzas that you wish to add buttons to. You can also place these options in [TRACK DEFAULTS] to create a default balloon.

``balloon hover specifies HTML or a URL that will be displayed when the user hovers over a feature. ``balloon click specifies HTML or a URL that will appear when the user clicks on a feature. The HTML can contain images, formatted text, and even controls. Examples:

 balloon hover = <h2>Gene $name</h2>
 balloon click = <h2>Gene $name</h2>
       <a href='<a href="http://www.google.com/search?q=">http://www.google.com/search?q=</a>$name'>Search Google</a><br>
       <a href='<a href="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=pubmed&term=">http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=pubmed&term=</a>$name'>Search NCBI</a><br>

Linking back to GBrowse

It is often useful to include links in a popup balloon that change the view in GBrowse. Use a callback to get the desired coordinates for the new view. Example:

balloon hover = sub   {
      my $feature = shift;
      my $box_content = "";
      if ($feature->strand > 0){
            $box_content .= "<b>Zoom in:</b>&nbsp;<a class=ggbmenu_link href=?q=NC_010473:"
               .($feature->start-25)."..".($feature->start+24)."&enable=DNA target=_self>".$feature->name." N-terminus</a><br>";
     }else{
            $box_content .= "<b>Zoom in:</b>&nbsp;<a class=ggbmenu_link href=?q=NC_010473:"
               .($feature->end-25)."..".($feature->end+24)."&enable=DNA target=_self>".$feature->name." N-terminus</a><br>";
     }
      return $box_content;
 }
</perl>
Note that <tt>&enable=DNA</tt> turns on the DNA track when following the link, while preserving other track settings.
 
=Customizing Balloons=
<p>GBrowse supports multiple balloons with different shapes, sizes,
background images and timing properties. There is one built-in
balloon, named "balloon", which should meet most peoples'
needs. However, you can configure any number of custom balloons.</p>
<p>To declare two new balloons, create a "custom balloons" option in the [GENERAL]
section:</p>
<code><pre>
 custom balloons = [blue_balloon]
                  images   =  /gbrowse/images/blue_balloons
                  maxWidth = 300
                  shadow   = 0
 
                  [wide_balloon]
                  maxWidth = 800
</pre></code>
 
<p>This creates two new balloons. The first, named "blue_balloon" will
look for its images and icons at the local URL
/gbrowse/images/blue_balloons. It will have a maximum width of 300
pixels, and will cast no shadow. The second, named "wide_balloon"
takes all the defaults for the default balloon, including the location
of its images in the directory /gbrowse/images/balloons, except that
it has a maximum width of 800 pixels. The various balloon options are
described well at http://www.gmod.org/wiki/index.php/Popup_Balloons.</p>
<p>To use the blue balloon rather than the standard one, format the
"balloon hover" and/or "balloon click" options like this:</p>
<pre>
 balloon click = [blue_balloon] /cgi-bin/get_gene_data?gene=$name</pre>
<p>The [blue_balloon] keyword tells gbrowse to use the blue balloon for
clicks on these features. The standard balloon is called "balloon",
and so the following two options are equivalent:</p>
<pre>
 balloon click = /cgi-bin/get_gene_data?gene=$name
 balloon click = [balloon] /cgi-bin/get_gene_data?gene=$name</pre>
<p>The images for custom balloons reside in the default location of
/gbrowse/images/balloons, unless indicated otherwise using the
``images'' config option.  To use custom balloon images, point "images"
to a a web-accessible directory in your document tree which contains
the seven PNG images described in the [http://www.gmod.org/wiki/index.php/Popup_Balloons#Notes_on_balloon_images documentation].
</p>
<p>
These images must be named as listed below:
</p>
<pre>
 balloon.png     down_right.png  up_right.png
 balloon_ie.png  down_left.png   up_left.png
 close.png
</pre>
 
<p>Tips for creating these images can be found [http://www.gmod.org/wiki/index.php/Popup_Balloons#Customization here]</p>
 
==Using AJAX and remote content==
<p>Alternatively, you can populate the balloon using data from an HTML
page or dynamic CGI script running on the same server as GBrowse. This
uses AJAX; it can often speed up page loading by reducing the amount
of text that must be downloaded by the client. To dynamically load
the balloon contents from the server, use a balloon hover or balloon
click option like this:</p>
<pre>
 balloon click = /cgi-bin/get_gene_data?gene=$name</pre>
<p>In this case, when the user clicks on the feature, it creates a
balloon whose content contains the HTML returned by the CGI script
``get_gene_data''. GBrowse knows that this is a URL rather than the
contents of the balloon by looking for the leading slash. However, to
reduce ambiguity, we recommend that you prefix the URL with ``url:'' as
so:</p>
<pre>
 balloon click = url:/cgi-bin/get_gene_data?gene=$name</pre>
<p>This also allows you to refer to relative URLs:</p>
<pre>
 balloon click = url:../../get_gene_data?gene=$name</pre>
<p>It is also possible to fill the balloon with content from a remote
source.  Simply specify a full URL beginning with ``http:'' ``https:'' or
``ftp:''</p>
<pre>
 balloon hover = <a href="http://www.wormbase.org/db/get?name=">http://www.wormbase.org/db/get?name=</a>$name;class=gene</pre>
<p>Note that the balloon library uses an internal &lt;iframe&gt; to populate
the balloon with the content of external URLs. This means that
vertical and horizontal scrollbars will appear if the content is too
large to be contained within the balloon. If the formatting does not
look right, you can design a custom balloon of the proper size as
described in the next section.</p>
<p>The usual option value substitution rules ($name, $start, etc) work
with balloons, as do callbacks. GBrowse will automatically escapes
single (') and double (``) quotes in the values returned by the
''balloon hover`` and ''balloon click`` options so that you don't have to
worry about them messing up the HTML.</p>
<p>You might also wish to specify ``titles are balloons'' in the [GENERAL]
section:</p>
<pre>
 [GENERAL]
 titles are balloons = 1</pre>
<p>This will generate balloons on all mouse hover events, using the
content that would otherwise have been placed in the built-in browser tooltip.</p>
<p>There is a limited amount of balloon customization that you can
perform within the [track] section. If you wish the balloon to be
sticky (require the user to press the close button) even if it is a
hover balloon, then place this option in the [track section]:</p>
<pre>
 balloon sticky = 1</pre>
<p>Setting ``balloon sticky'' to 0 will have the effect of making balloons
disappear as soon as the mouse leaves them, even if it was created by
a mouse click event.</p>
<p>If you are displaying content from a remote web or FTP server and you
do not like the height of the balloon, you can adjust the height with
the ``balloon height'' option:</p>
<pre>
 balloon height = 400
</pre>
==Using GBrowse_details as an AJAX Request Handler for Popup Balloons==
'''How to make low-impact changes to existing code to provide a built-in ajax handler for Gbrowse popup ballons (or other applications'''
 
===Examples===
* A balloon hover with contents generated using an AJAX call to gbrowse_details and the '''''params''''' callback shown below
[[Image:sample1b.png]]
 
 
 
* A sticky balloon with contents generated from gbrowse-details (via an &lt;iframe&gt; element) and the '''''default''''' callback shown below.
[[Image:sample2b.png]]
 
===Changes to gbrowse_details===
 
* A new CGI parameter to invoke the AJAX-handling behavior
 my $rmt   = param('remote');
 
 
* A response is triggered after the feature(s) are defined but before '''''PrintTop''''' is called.
 if (defined $rmt) {
   print header,start_html;
   print remote_content($rmt,$features[0]);
   print end_html;
   exit 0;
 }'''
 
* The '''''remote_content''''' subroutine will get the text or coderef. It will return the text or execute the callback with user-defined arguments
 # do something for popup balloons
 sub remote_content {
   my $key = shift; # the key for the text or code-ref in the gbrowse config file
   my $feat = shift;
   my $contents = $CONFIG->config->code_setting('TOOLTIPS',$key) or die "$key is empty";
   my $coderef = (ref $contents||&#39;&#39;) eq 'CODE';
   return $contents unless $coderef;
   # paranoia?
   die "Error: $key is not a CODE-REF" if ref $contents && !$coderef;
   # args are user-defined
   my %args = (feature => $feat) if $feat;
   for my $arg (param()) {
     my @vals = param($arg);
     my $val  = @vals > 1 ? \@vals : $vals[0];
     $args{$arg} = $val;
   }
   return $contents->(\%args);
 }
 
===Changes To Configuration File===
* A new section [TOOLTIPS] that has all the named text sections or callbacks you need to access through gbrowse_details
**'''NOTE:''' This section must be placed at the end of the [GENERAL] section.
[[Image:callbacks]]
 
 
* The [ORF] configuration stanza used to generate the images above.  The relevant section is highlighted
[[Image:orf_stanza]]
 
=Popups in Gbrowse 2.0=
The upcoming release of GBrowse 2.0 will have some changes to popup balloons.  <br>
Some key differences are:
 
===Tooltip Styles===
* There are four tooltip styles offered by default.
* The way they are used in GBrowse has not been changed substantially.
* You can select a particular style of balloon by calling it by name
eg
 balloon hover = [GPlain] This is my message
 
====GBubble and GFade====
This is the original popup balloon from GBrowse 1.69.  It has a couple of new behaviors, including an opacity setting (the example shown has opacity set to 90%) and fades up to the full opacity setting rather than abruptly appearing.
 
* GBubble the the default balloon style, so the [GBubble] name is optional.
 
[[Image:GBubble.png|border]]
 
Example configuration
<pre style="width:70%"><nowiki>
balloon hover = [GBubble] I am 'GBubble', the <i>classic</i> GBrowse popup balloon!
</nowiki></pre>
 
* GFade is identical to GBubble except that it fades into view rather than just popping up.  This is accomplished by starting out transparent and gradually increasing the opacity over a span of 1200 msec.
 
====GPlain====
The GPlain style is a plainer style of balloon tooltip but still offers fully HTML formatted contents, opacity, etc.  The default configuration has opacity set to 85% and cursor tracking enabled, so the tooltip will follow the mouse until you mouseout from the text or image the tooltip is attached to.
 
[[Image:GPlain.png|border]]
 
Example configuration
<pre style="width:70%"><nowiki>
balloon hover = [GPlain] I am 'GPlain', I am less fancy!
</nowiki></pre>
 
====GBox====
GBox is a formatted box.  It can have fixed dimensions or resize dynamically (actually, this is true of all balloon tooltips).
* For sticky boxes, if the contents are too big, scrollbars will appear.
* The GBox style is used for the inline track configuration (called by clicking "?" in the titlebar for each track).
* You can also use is anywhere else in Gbrowse using the '[GBox]' name.
 
An example track configuration box
<br>
[[Image:GBox.png|border|The '''''GBox''' style]]
 
 
An example showing a box resized to stay onscreen, despite a small window.
<br>
[[Image:RidiculouslySmallWindow.png|border|This is too small]]
 
 
Example configuration:
 
<pre style="width:70%"><nowiki>
balloon hover = [GBox] I am a box.
</nowiki></pre>
 
===Changing the global default balloon style===
 
The balloon style used by default is 'GBubble'.  This can be changed using the 'balloon style' option in either GBrowse.conf or in the configuration file for individual data sources.
 
<pre>
# use GBubble as the default balloon style
balloon style = GBubble
</pre>
 
===Configuring Default Tooltip Styles===
Default balloon style options are configured in the file balloon.config.js, which comes with the distribution.  Many display options are configurable, see [[Popup_Balloons#Customization]] for details.
 
below is the default configuration applied to all balloon styles balloon.config.js
 
<pre style="width:70%"><nowiki>
  ////////////////////////////////////////////////////////////////
  // The default "base" config applied to all balloon objects.  //
  // See http://gmod.org/wiki/Popup_Balloons#Customization for  //
  // details about config options                               //
  //                                                            //
  // values can be overriden in custom config cases (see below) //
  ////////////////////////////////////////////////////////////////
  if (!balloon.configured) {                                    //
    balloon.fontColor          = 'black';                       //
    balloon.fontFamily         = 'Arial, sans-serif';           //
    balloon.fontSize           = '12pt';                        //
    balloon.minWidth           = 100;                           //
    balloon.maxWidth           = 400;                           //
    balloon.delayTime          = 750;                           //
    balloon.vOffset            = 10;                            //
    balloon.hOffset            = 10;                            //
    balloon.stem               = true;                          //
    balloon.balloonImage       = 'balloon.png';                 //
    balloon.upLeftStem         = 'up_left.png';                 //
    balloon.downLeftStem       = 'down_left.png';               //
    balloon.upRightStem        = 'up_right.png';                //
    balloon.downRightStem      = 'down_right.png';              //
    balloon.closeButton        = 'close.png';                   //
    balloon.closeButtonWidth   = 16;                            //
    balloon.allowAJAX          = true;                          //
    balloon.allowIframes       = true;                          //
    balloon.configured         = true;                          //
    balloon.trackCursor        = true;                          //
  }                                                             //
  ////////////////////////////////////////////////////////////////
</nowiki></pre>
 
 
 
Below is the syntax for default configuration for the three styles above in balloon.config.js
 
<pre style="width:70%"><nowiki>
 
  ////////////////////////////////////////////////////////////////
  // Custom configuration options -- Add a case below for your  //
  // config set (GBrowse defaults: GBox, GPlain and GBubble)    //
  ////////////////////////////////////////////////////////////////
  switch(set) {
 
    // A formatted box (no background image)
    case('GBox') :
      balloon.bgColor     = 'lightgoldenrodyellow';
      balloon.borderStyle = '2px solid gray';
      balloon.padding     = 5;
      balloon.shadow      = 0;
      balloon.stem        = false;
      balloon.opacity     = 90;
      break;
 
    // A simple balloon
    case('GPlain') :
      balloon.padding     = 5;
      balloon.shadow      = 0;
      balloon.stemHeight  = 15;
      balloon.stemOverlap = 1;
      balloon.opacity     = 85;
      break;
 
    // The original cartoon bubble
    case('GBubble') :
      balloon.ieImage     = 'balloon_ie.png';
      balloon.shadow      = 20;
      balloon.padding     = 10;
      balloon.stemHeight  = 32;
      balloon.stemOverlap = 3;
      balloon.vOffset     = 1;
      balloon.hOffset     = 1;
      balloon.opacity     = 85;
      break;
 
    // The cartoon bubble with a fade-in effect
    case('GFade') :
      balloon.ieImage     = 'balloon_ie.png';
      balloon.shadow      = 20;
      balloon.padding     = 10;
      balloon.stemHeight  = 32;
      balloon.stemOverlap = 3;
      balloon.vOffset     = 1;
      balloon.hOffset     = 1;
      balloon.opacity     = 85;
      balloon.allowFade   = true;
      balloon.trackCursor = false;
      break;
  }
</nowiki></pre>
 
===Other differences===
====Cursor Tracking====
* By default, the position of non-sticky balloons (or boxes) will follow the mouse cursor until it leaves the text or image that triggered the balloon tooltip.
 
* This option can be disabled via balloon.config.js
 
  balloon.trackCursor = false;
 
====overflow and Scrollbars====
* When the size of the balloon contents exceeds the balloon (or box) size, two new behaviors have been introduced:
# for sticky tooltips, scrollbars will appear.
# for non-sticky tooltips, excess contents will be clipped (hidden).  Note this will not usually happen unless the size of the balloons has been explicitly constrained.  Reasonable care must be taken here, as popup balloons are not mean to contain contents exceeding 500-600px width and height in any case.
 
====Both height and width can be constrained====
Height and width arguments are supported.  In cases where the balloon contents are smaller than the specified dimensions, the balloon or box will shrink to fit.  However, oversize contents will trigger clipping for non-sticky balloons and scrollbars for sticky balloons
 
====Tooltips will not go off-screen====
Tooltips will automatically resize to stay inside the visible window.  Again, reasonable limits apply.
 
===GBox for GBrowse 1.7===
Most of the new tooltip feayures described above are specific to GBrowse 2.  The following is a recipe to add a GBox-style tooltips to Gbrowse 1.7.
 
[[Image:GBoxretro.png|right|border]]
 
1) Add the image [http://gmod.org/w/images/2/2b/Box.png Box.png] to /var/www/html/gbrowse/images/balloons (or wherever you have installed the gbrowse images on your web server).
 
 
2) Add the following text to the top of you GBrowse configuration file.  It must be in the [GENERAL] section.
 
<pre style="width:50%">
custom balloons = [GBox]
                  balloonImage  = Box.png
                  stem          = 0
                  vOffset       = 20
                  hOffset       = 20
                  padding       = 1
                  shadow        = 0
 
</pre>
 
 
3) Add this function to the top of your configuration file (in the
[GENERAL] section).  This is a generic function to display all feature
attributes in a formatted table. It is not strictly necessary to use a
function like this, as you can put whatever you want in the tooltip.
Be sure to get rid of any cut and paste artifacts like line wrapping,
each new line of the code (including the closing brace) must start
with at least one white space character.
 
<syntaxhighlight lang="perl">
# A generic function to display a table of all attribute values
# for a feature object
init_code =
 sub tooltip {
    my $f = shift;
    my $name = $f->name;
    my @tags = $f->all_tags;
    my $chr = $f->seq_id;
    $chr .= ':' . $f->start . '..' . $f->end;
    my $retval = qq([GBox] <table>);
    $retval   .= qq(<tr><th style="color:white;background:blue;margin:-2px" colspan=2>$name ($chr)</th></tr>);
 
    for my $tag (sort @tags) {
      my ($val) = $f->get_tag_values($tag);
      $retval .= qq(<tr valign=TO><td><b>$tag</b></td><td>$val</td>);
    }
 
    return $retval . "</table>";
  }
 
</perl>
 
4) Add the balloon tooltip option to the configuration stanza for your track(s)
 balloon hover = sub {tooltip(shift)}
 
The above example passes the feature object to the tooltips function you added to the init_code section.  More simply, you could just do:
 
balloon hover = [GBox] Whatever text you want goes here....
balloon click   = [GBox] Whatevr sticky text ...
 
[[Category:AJAX]]
[[Category:GBrowse]]
[[Category:Javascript]]
[[Category:Needs Editing]]
[[Category:HOWTO]]