Popup Balloons

From GMOD
Revision as of 17:31, 4 September 2007 by Mckays (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Overview

Balloon tooltips is a DHTML-based utility that will put your help text into balloons. It allows HTML markup of text. Help messages can be coded into your HTML or dynamically generated via AJAX. The location and orientation of the balloon is controlled automatically by the page geometry.


Example Implementations

Example 1: A basic demonstration: balloons.html


Example 2: More than one type of balloons on the same page: balloons3.html


Example 3: Tooltips for image maps: balloons2.html


Example 4: WormBase

Balloon tooltips with AJAX content retrieval (mouseover the navigation bar to the top of the page) WormBase

Availability

The complete package can be obtained from the GMOD CVS site at: http://gmod.cvs.sourceforge.net/gmod/balloon-tooltips/

Installation

Required components

Put the required files on your web server

  • Copy the above javascript libraries to your web server, for example in
document_root/js
  • Copy the above image files (or your own) to your web server, for example in
document_root/images/balloons

Specify the location of the javascript libraries

  • Add the following directives to your page header.
  • The yahoo library can be installed as a local copy or else served remotely by Yahoo. The latter option is shown here.

via HTML:

 <head>
 <script type="text/javascript" src="/js/prototype.js"></script>
 <script type="text/javascript" src="/js/balloon.js"></script>
 <script type="text/javascript"
   src="http://yui.yahooapis.com/2.3.0/build/yahoo-dom-event/yahoo-dom-event.js"
 </script>
 </head>
 

or via javascript:

 document.write('<script type="text/javascript" src="/js/prototype.js"></script>');
 document.write('<script type="text/javascript" src="/js/balloon.js"></script>');
 document.write(' <script type="text/javascript" src="http://yui.yahooapis.com/2.3.0/build/yahoo-dom-event/yahoo-dom-event.js"  </script>');
 

Initialize balloon object(s)

  • Insert a script like the example below either in the <head> section of the document or near the top of the <body> section.
  • Only one object is required but multiple objects are allowed.
  • See the configuration section (below) for more details on configuration options.
  • More examples can be seen in the example implementations above.
 <script type="text/javascript">
   // white balloon with default configuration
   var whiteBalloon    = new Balloon;

   // Stemless blue balloon
   var blueBalloon  = new Balloon;
   blueBalloon.balloonTextSize  = '90%';
   blueBalloon.balloonImage     = '/images/balloons/blue_balloon.png';
   blueBalloon.vOffset          = 15;
   blueBalloon.shadow           = 0;
   blueBalloon.stem             = false;
 </script>

Notes on balloon images

Where to get them

  • Default balloon images are provided here.
  • These images were created and/or edited with The GIMP

How they are used

  • A total of five images are required to draw balloons in all possible orientations: The balloon body and four stems (up, down, left and right).
  • In addition, a close button for sticky balloons and an optional no-shadow version of the balloon (for internet explorer versions < 7) are also included.


The images below are provided with the package (not to scale): 

Sample balloons.png


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:

Balloon up bottom left.png


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 is substituted is IE version < 7 is detected.

  • If you design custom balloon images that use alpha channels, consider creating an alternative body image for older IE browsers.
  • The use of the alternate image is configured as follows:
balloon.ieImage = '/images/balloons/balloon_ie.png;

Customization

  • The balloon.js library offers default configuration setting that should work "out of the box".
  • Any of the default settings shown below can be overridden via a script in the body section of your HTML.

For example:

<body>
 <script "type=text/javascript">
   // This creates the balloon object
   var balloon = new Balloon;
   balloon.balloonTextSize = '11px';
   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.
<script type="text/javascript">
  // maximum allowed balloon width
  balloon.minWidth = 150;

  // minimum allowed balloon width
  balloon.maxWidth = 600;

  // Default tooltip text size
  balloon.balloonTextSize = '90%';

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

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

  // text-padding within the balloon
  balloon.padding  = 10;

  // width of shadow (space aroung whole balloon)
  // Balloon 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.balloonImage  = '/images/balloons/balloon.png';    // with alpha channels
  balloon.ieImage       = '/images/balloons/balloon_ie.png'; // 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    = '/images/balloons/up_left.png';
  balloon.downLeftStem  = '/images/balloons/down_left.png';
  balloon.upRightStem   = '/images/balloons/up_right.png';
  balloon.downRightStem = '/images/balloons/down_right.png';


  // A close button for sticky balloons
  balloon.closeButton   = '/images/balloons/close.png';
</script>
  • If you wish to create your own balloon images, the image below demonstrates some key balloon image properties. The stem height, the stem overlap and the padding and shadow widths must be accurate to a precision of 1px or the balloon will not render properly.

Options.png

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.tooltip(event,caption[,sticky][,width])"
  • The 'event' argument passes the event object to the showTooltip function. The event object is used to get the page coordinates of the mouseover identify the target element.
  • The 'caption' argument can be plain text,HTML, a URL or the ID of a div element on the page that contains the balloon contents.
  • The optional 'sticky' argument can be any true value
  • The optional 'width' argument will force the balloon to be a specified width.

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 200px 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 <div>

 <div id="contents1" style="display:none">
  Your message goes here.  It may be long and have lots of HTML markup, 
  forms, images, etc...
 </div>
 <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,'Some text \
<a href="www.google.com">search...</a>')">mouseover text</span>


Sticky balloon behavior

  • Sticky balloons will now persist until either
  1. the close button is clicked
  2. another sticky balloon is called

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.'
  • If you are editing HTML directly, the escape character '\' should be used once for each occurrence.
  • If you are adding string from within a perl/CGI script and are using double quotes or qq(), use a double escape '\\'.


Nested quotes:

  • Single quotes nested without the string must be escaped. You can use this character '\' or else the HTML escape character &#39;
  • Double quotes within the string may cause problems with your browser's HTML-parsing.
    • For internal or nested double quotes, use the HTML escape &#34;.

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

  • An alternative to the quoting and multiline strings described above is to wrap the balloon contents in an invisible element on the page.

For example, the string above would be encoded as:

<div id="contents1" style="display:none">
 This is some text.  It is 'very interesting'.  Well, maybe not.
 I guess it depends on your definition of "interesting".
</div>

and the contents are retreived using the syntax below:

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

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:

  • section - the text label specified as an argument to the showTooltip function.

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

  • If you do not intend to use this functionality, make sure the helpUrl variable is not defined.
  • 'contents2' will then be interpreted as the literal balloon contents:
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.

  • This approach has the advantage of having no preset CGI parameters and leaves the implementer free to structure queries in whatever way they prefer.

Inserting images and other remote content without AJAX

Images:

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

  • It up to the implementor to ensure that the image is the correct size to fit in the balloon.
  • In some browsers, the calculation of the balloon's position will be wrong unless the size of the image is known prior to loading. Specifying an image height ensures consistent behavior across browsers.
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.

  • As with images, it up to the implementor to ensure that the contents returned by the remote URL are the correct size to fit in the balloon.
  • Specify the dimensions of the iframe element for best results.
  • Balloons with complex content should be made sticky.
showTooltip(event,'<iframe frameborder=0 width=250 src=http://somehost.com></iframe>',1)

CHANGES

Version 1.11

  • Substantial changes to balloon rendering
    • dynamic balloon size
    • new background images
  • Made sticky balloons stickier
  • Improved cross-browser behavior

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 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.