GMOD

Popup Balloons

Sample ballon.png

balloon.js is a javascript class for balloon tooltips, otherwise known as popup balloons, bubble tooltips, rollover tooltips, etc. It is maintained by Sheldon McKay, a scientist at the DNA Learning center, Cold Spring Harbor Laboratory.

balloon.js is generic and should work in most web sites.

Contents

Example Implementations

Example 1: See the balloons in action: balloons2.html

Availability

Installation

Required components

Download all of the above: tarball or zip archive

Put the required files on your web server

document_root/js

NOTE: document root is the root folder for your web server. It will vary by system architecture. Depending on your web server, this may be:

Linux:
/var/www/html
/var/www/htdocs
/etc/apache2

Windows (why would you use windows?):
C:/Program Files/Apache Software Foundation/Apache2.2/htdocs

Max OS X:
/Library/WebServer/Documents

etc...

document_root/images/balloons

Specify the location of the javascript libraries

via HTML:

 <head>
 <script type="text/javascript" src="js/balloon.config.js"></script>
 <script type="text/javascript" src="js/balloon.js"></script>
 <script type="text/javascript" src="js/box.js"></script>
 <script type="text/javascript" src="js/prototype.js"></script>
 </head>

NOTE: you can also add this code to the <body> section instead of the page header.

Initialize balloon object(s)

 <script type="text/javascript">
   // white balloon, with default configuration
   var whiteBalloon    = new Balloon;

   // Stemless blue balloon, with custom image
   var blueBalloon  = new Balloon;
   blueBalloon.balloonTextSize  = '90%';
   blueBalloon.images           = '/images/balloons';
   blueBalloon.balloonImage     = 'blue_balloon.png';
   blueBalloon.vOffset          = 15;
   blueBalloon.shadow           = 0;
   blueBalloon.stem             = false; // no stems, just the body

   // Plain box with no fancy balloon images
   var plainBox         = new Box();
   plainBox.bgColor     = 'ivory';
   plainBox.borderStyle = '2px solid blue';

 </script>

Notes on balloon images

How it works

Howitworks.png

Note on simpler popups

Where to get the balloon images

Default images

Design your own images

How they are used

The stem: This part of the image is the top or bottom (depending on whether the balloon is facing up or down) that has the triangle. It is overlaid on top of the balloon background image. The connector is a fixed-size image.

For example, a bottom-left stem:

The body: This image is used as the background for the balloon. The image is much larger and the actual balloon size (1020px *1020px). Each of the four corners of the balloon has its own identical background image. The top corner contains the contents of the balloon and the amount of the background image that is visible is adjusted with the balloon size. The other corners and right and bottom edges of the balloon are created by making only a small portion of their respective background images visible. Te size of the balloon is dynamic in both the vertical and horizontal dimensions. However, maximum and minimum widths for the balloon can be specified as follows:

balloon.minWidth = 150;
balloon.maxWidth = 600;

and the balloon width can be constrained at run-time by adding a fourth argument to the showToolip method call:

onmouseover=balloon.showTooltip(event,'message...',null,300)

Note: Internet Explorer

The balloon body image is in PNG format with alpha channels. This file format is required for the semi-transparent shadow. Older versions of internet explorer do not support this feature (support was added to version 7). In the default configuration, an alternative image without a shadow if substituted is IE version < 7 is detected.

balloon.ieImage = 'balloon_ie.png;

Balloon image locations

If you have saved the balloon images in a location other than the default relative URL ‘/images/balloons’, you need to tell the balloon object about it or your popups will not have the balloon image.
There are two ways to do this:

1) Set the variable balloon.images to the relative url for balloon images. If you use this method, specify the relative URL only once with the instance variable balloon.images. Individual image name should not have the path. For example:

<script type="text/javascript">
  my balloon = new Balloon;
  balloon.images = '/myImages/myBalloons';
  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';
</script>

  1. Use an explicit URL for each balloon image. Note balloon.images must be reset to ‘null’ in this case.

    <script type="text/javascript">
  my balloon = new Balloon;
  balloon.images = null;
  balloon.balloonImage  = '/myImages/myBalloons/balloon.png';
  balloon.upLeftStem    = '/myImages/myBalloons/up_left.png';
  balloon.downLeftStem  = '/myImages/myBalloons/down_left.png';
  balloon.upRightStem   = '/myImages/myBalloons/up_right.png';
  balloon.downRightStem = '/myImages/myBalloons/down_right.png';
  balloon.closeButton   = '/myImages/myBalloons/close.png';
</script>

NOTE: the two methods above are mutually exclusive.

Balloon image properties

Options.png

Note: The padding is not only the distance of the text from the balloon outline, it also defines the width of the right and bottom corners of the dynamically rendered balloon image. Setting the padding to a value less than the radius of the corners (10px is the default) will obscure the balloon corners.

For example, setting the padding to 2px with the default balloon images will cause the effect below because the image corner radius is 10px:

Padding defect.png

Online balloon image generator

Below is an example of the input form that can be used to experiment with different balloon options.

The actual script is at http://mckay.cshl.edu/balloon

Sample output. The program will draw either a sample of what the final product will look like or all of the necessary image components.

| | | :-: |

| The actual script is at http://mckay.cshl.edu/balloon |

The CGI script will also generate the necessary javascript code to use the custom balloon images on a web page:

The actual script is at http://mckay.cshl.edu/balloon

Configuration

This section describes javascript configuration. To configure balloon tooltips in GBrowse, see Configuring Balloon Tooltips.

For example:

<body>
 <script "type=text/javascript">
   // This creates the balloon object
   var balloon = new Balloon;
   balloon.fontSize  = '11pt';
   balloon.fontColor = 'blue';
   balloon.delayTime = 500;
 </script>

The following options can be reset/configured in the page header or body (after the balloon object has been initialized) using the syntax below, where ‘balloon’ is the object created by the ‘new Balloon’ command.

NOTE: The default values are shown. Edit the file balloon.config.js to change the values below.

 // ID of element to which balloon should be added
 // default = none (document.body is used)
 // This option may be required for mediawiki or other
 // implementations with complex stylesheets
 balloon.parentID = null;

 balloon.minWidth = 150;
 balloon.maxWidth = 600;

 // Delay before balloon is displayed (msec)
 balloon.delayTime = 500;

 // If fade-in/out is allowed
 balloon.allowFade = false;
 // time interval for fade-in (msec)
 balloon.fadeIn    = 300;
 // time interval for fade-out (msec)
 balloon.fadeOut   = 300;

 // Vertical Distance from cursor location (px)
 balloon.vOffset  = 10;

 // text-padding within the balloon (px)
 balloon.padding  = 10;

 // How long to display mousover balloons (msec)
 // false = 'always on'
 balloon.displayTime = 10000;

 // width of shadow (space aroung whole balloon; px)
 // This can be zero if there is no shadow and the
 // edges of the balloon are also the edges of the image
 balloon.shadow   = 20;

 // images of balloon body.  If the browser is IE < 7, png alpha
 // channels will not work.  An optional alternative image can be
 // provided.  It should have the same dimensions as the default png image
 balloon.images        = '/images/balloons';

 balloon.balloonImage  = 'balloon.png';    // with alpha channels

 balloon.ieImage       = 'balloon_ie.png'; a// indexed color, transparent background

 // whether the balloon should have a stem
 balloon.stem          = true;

 // The height (px) of the stem and the extent to which the
 // stem image should overlaps the balloon image.
 balloon.stemHeight  = 32;
 balloon.stemOverlap = 3;

 // A stem for each of the four orientations
 balloon.upLeftStem    = 'up_left.png';
 balloon.downLeftStem  = 'down_left.png';
 balloon.upRightStem   = 'up_right.png';
 balloon.downRightStem = 'down_right.png';

 // A close button for sticky balloons
 balloon.closeButton   = 'close.png';

 balloon.fontSize      = '12pt';
 balloon.fontColor     = 'black';
 balloon.fontFamily    = 'Arial, sans-serif';

This section allows support for AJAX, iframes and JavaScript in balloons. If you have concerns about XSS vulnerabilities, set some or all of these values to false;

 // URL for default AJAX request handler
 balloon.helpUrl            = false;

 // Should AJAX be allowed at all?
 balloon.allowAJAX          = true;

 // Allow iframe elements in balloons?
 balloon.allowIframes       = true;

 // Allow javascript event handlers in balloons?
 balloon.allowEventHandlers = false;

 // Allow <script> elements in balloons?
 balloon.allowScripts       = false;

 // Escape all HTML characters -- this will be very
 // unnattractive unless your AJAX request returns plain
 // text.  short of disallowing AJAX entirely, This is the safe
 // way to go if you must have AJAX in an environment where
 // outside users can send text to the browser/balloon
 balloon.escapeHTML         = false;

Using a formatted box with no balloon images

  var box = new Box();
  BalloonConfig(box,'GBox');

  // background color of the box (web colors of hex)
  box.bgcolor = "red";

  // border style (standard CSS syntax)
  box.borderStyle = "2px solid purple";

Configuration Sets

var plainBalloon = new Balloon;
BalloonConfig(plainBalloon,'GPlain');

var fancyBalloon = new Balloon;
BalloonConfig(fancyBalloon,'GFade');

Configuration Sets included in the balloon.js package

GBubble and GFade

This is the original cartoon bubble popup balloon style. It has a couple of new behaviors, including an opacity setting (the example shown has opacity set to 0.9).

GBubble.png

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.

GPlain.png

GBox

GBox is a formatted box. It can have fixed dimensions or resize dynamically (actually, this is true of all balloon tooltips).

The GBox style

Configuring Default Tooltip Styles

Below is the syntax for default configuration for the three styles above in balloon.config.js


  ////////////////////////////////////////////////////////////////
  // 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;
  }

The JavaScript User Interface

Basic Usage

The API is fairly simple. Simply add a mouseover event handler to any HTML element you want to fire a tooltip.

onmouseover="balloon.showTooltip(event,caption[,sticky][,width][,height])"

NOTE: Even if width and height are specified, the balloon will shrink to fit when the actual contents are smaller than the specified dimensions.

Examples:

A simple message

 <a href="someURL" onmouseover="balloon.showTooltip(event,'Some text...')">Link</a>

A sticky balloon

 <a href="someURL" onmouseover="balloon.showTooltip(event,'Some text...',1)">Link</a>

A sticky balloon that is 250px wide

 <a href="someURL" onmouseover="balloon.showTooltip(event,'Some text...',1,250)">Link</a>

A non-sticky balloon that is 150px wide

 <a href="someURL" onmouseover="balloon.showTooltip(event,'Some text...',0,150)">Link</a>

A balloon that has its content stored in a \

  Your message goes here.  It may be long and have lots of HTML markup,
  forms, images, etc...

 <a href="someURL" onmouseover="balloon.showTooltip(event,'load:contents1',1,250)">Link</a>

A balloon that contains another website loaded via an iframe

<span onmouseover="balloon.showTooltip(event,'\
 <iframe style=\'width:270;height:300;border:0\' \
 src=\'http://www.nypost.com/avantgo/avantnews/avantnews.htm\'></iframe>',1,300)"
</span>

How do I put an image in the balloon?

Note: see notes below about nested quoted and the ‘load:myContent’ syntax.

Examples

 <span onmouseover="balloon.showTooltip(event,'<img src=\'myImage\' />')">Mouseover text</span>

 <a href="http:/some.site.org" onmouseover="balloon.showTooltip(event,'<img src=\'myImage\' />')">Link</a>

 <span onclick="balloon.showTooltip(event,'<a href=\'http:/some.site.org\'><img src=\'myImage\' /></a>',1)">
   Mouseover text
 </span>

 <span onclick="balloon.showTooltip(event,'load:myImageLink',1)">
   Mouseover text
 </span>

 <span id="myImageLink" style="display:none">
  <a href="http:/some.site.org">
    <img src="myImage" />
  </a>
 </span>

Sticky balloon behavior

Formatting balloon contents

Escape characters and multi-line strings

For very long or multiple-line strings that are being passed to a javascript function, use the ‘\ escape character to break up the text, with the string terminator occurring only once at the end.

For example:

'This is some text.  It is quite long, perhaps too long to fit comfortably on \
one line.  Yep, I thought so.  Well, here comes the end, anyway.'

Nested quotes:

For example;

'This is some text.  It is \'very interesting\'.  Well, maybe not. \
I guess it depends on your definition of &quote;interesting&quote;'

Storing balloon contents in invisible page elements

For example, the string above would be encoded as:

 This is some text.  It is 'very interesting'.  Well, maybe not.
 I guess it depends on your definition of "interesting".

and the contents are retreived using the syntax below:

onmouseover="balloon.showTooltip(event,"load:contents1");

NOTE: For special characters, do not use HTML escape characters (eg & for &) URI escape codes such as those described here.

If you have URI encoding that you do not want to be unencoded inside the balloon, for example:

http://mysite.org?paramx=my%20param%20has%20spaces

edit balloon.config.js and set balloon.protectEncoding to ‘true’.

Using AJAX to get balloon contents

NOTE: Currently only AJAX requests to the same host are supported.

The ‘helpURL’ variable on the configuration section can be used to specify the URL of a perl script that will act as an ajax handler and return text in response to an ajax query.

For example:

balloon.helpUrl = '/cgi-bin/help.pl';

If ‘helpUrl’ is defined, balloon.js will send an http request to the address specified with the following parameters:

Assuming a function call ‘showTooltip(event,’section2’)’, the following query would be generated and the result of the query would be used to populate the balloon.

/cgi-bin/help.pl?section=section2

The AJAX handling script and its behavior are the responsibility of the implementer.

An example: the AJAX handler used by wormbase

balloon.helpUrl = null;

An alternative AJAX implementation

An alternative to using an AJAX handler script is to specify the balloon contents with a self-contained URL in the balloon.showTooltip function call. This requires a special syntax:

balloon.showTooltip(event,'url:/examples/example1.html')

NOTE: The URL is subject to the same cross-domain limitation as other AJAX requests.

Inserting images and other remote content without AJAX

Images:

Inserting images is a simple as encoding the image in a regular HTML image tag.

showTooltip(event,'<img height=200 src=image1.png>')

Other remote content:

Inserting content from URLs outside of the domain that hosts balloon.js can be done with an <iframe> element.

showTooltip(event,'<iframe frameborder=0 width=250 src=http://somehost.com></iframe>',1)

CHANGES

version 1.11

version 1.19

version 1.20

version 1.22

version 1.27

version 1.33

version 1.37

version 1.41

version 1.43

version 1.46

version 2.0

version 2.1

NOTE: to the helpful, if somewhat pugilistic, user who spent so such time bug-hunting and pointing out errors: I’m sorry I deleted your email before recording your name and can not acknowledge you properly. Please contact me if you want to be acknowledged.

version 2.2

New Features

Cursor Tracking

 balloon.trackCursor = false;

Overflow and Scrollbars

  1. for sticky tooltips, scrollbars will appear.
  2. 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.

Troubleshooting for the impatient

Almost all problems reported are not bugs in balloon.js but implementation errors, such as those described below:

What is a Document Root?

The directory (in the real filesystem) from which your Web server will be serving most of its Web pages.

For example: If you set the document root to /home/httpd/html, then accesses to http://your.webserver.com/index.html would return the file /home/httpd/html/index.html. An access to gazonk.gif would return /home/httpd/html/foo/gazonk.gif.

For URLs used by your web browser, the document root is ‘/’. If you create subdirectories, ‘test’ for example, the URL for path for the contents of ‘test’ would be /test/*, e.g. ‘/test/images’, ‘/test/js’, etc.

library locations
Your web browser needs to know where the javascript files are. Make sure the <script src=… lines in your page header point to the actual location of the javascript files on your web server. If you do not put them in /js (relative to the document root), you must change the header lines in your HTML accordingly. For example, lets say you put the whole works under /test relative to your web servers document root. The the correct URL for your js files is ‘/test/js’.

image locations
Your web browser needs to know where the image files are. By default, image files are located in /images/balloons (relative to the document root) under GBubble, GPlain, etc. This is specified in the balloon.config.js file. If you move the image files somewhere else on your web server’s files system, edit balloon.config.js accordingly. For example, lets say you put the whole works under /test relative to your web servers document root. The the correct URL for your js files is ‘/test/images/balloons’

typos
These take many forms but almost all are fatal. JavaScript is case-sensitive and bear in mind that you are editing Javascript code, which will only work if it is exactly right. For example:

 var balloon = new Balloon();

is NOT the same as:

var balloon = new balloon();

This package is NOT a desktop application

With apologies, the author does not provide user support for this package installed on local desktop computers

Reporting errors

Software License

This balloon tooltip package and associated files not otherwise copyrighted are
distributed under the MIT-style license:

 http://opensource.org/licenses/mit-license.php


 Copyright (c) 2007-2012 Sheldon McKay, Cold Spring Harbor Laboratory

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:

 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.

 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.

 If publications result from research using this SOFTWARE, we ask that
 CSHL and the author be acknowledged as scientifically appropriate.

Categories:

Documentation

Community

Tools