# BeautyTips Demo

BeautyTips is a jQuery tooltips plugin which uses the canvas drawing element in the HTML5 spec in order to dynamically draw tooltips (sometimes called "talk bubbles" or "help balloons") associated with a html element on the page. These tips are highly configurable and can be triggered in many different ways.

The canvas element is supported in modern versions of FireFox, Safari, and Opera. However, Internet Explorer needs a separate library called ExplorerCanvas included on the page in order to support canvas drawing functions. ExplorerCanvas was created by Google for use with their web apps and you can find it here.

BeautyTips was written to be simple to use and pretty. All of its options are documented at the bottom of the .js file and defaults can be overwritten globally for the entire page, or individually for each target element (more about this in the wrapup section).

BeautyTips has been tested with jQuery 1.2.6 and 1.3 on Firefox 3.x, Safari 3.x (also works on iPhone!), IE 6.x+, and Opera 8+, but I'm sure other canvas-capable browsers will work as well.

By default each tooltip will be positioned on the side of the target element which has the most free space. This is affected by the scroll position and size of the current window, so each Beauty Tip is redrawn each time it is displayed. It may appear above an element at the bottom of the page, but when the page is scrolled down (and the element is at the top of the page) it will appear below it. Additionally, positions can be forced or a preferred order can be defined. See examples below.

## Project Page and Download

BeautyTips has a page in the plugins directory on jQuery.com. This is where you can download the latest version. It is also the best place to post bugs and feature requests.

http://plugins.jquery.com/project/bt

## Other helpful plugins

To fix z-index problems with form elements in IE6, include the bgiframe plugin on your page. BeautyTips will automatically recognize it and use it.

BeautyTips also works with the hoverIntent plugin see hoverIntent example below for usage.

## Usage

The function can be called in a number of ways.
`$(selector).bt();`
`$(selector).bt('Content text');`
`$(selector).bt('Content text', {option1: value, option2: value});`
`$(selector).bt({option1: value, option2: value});`

## Examples

Note: html and javascript textareas are live. Feel free to experiment with the code and see how BeautyTips are affected.

### No options

hover

This is the simplest example. No arguments are sent and the default settings are used to create a tip which appears on the side with the most space.

$('#example1').bt();

### Content from argument

click

Tip appears above the element when it is clicked. The contents of tip is provided when creating the tip.

$('#example2').bt('Contents of the tip is provided in the .bt() call', {trigger: 'click', positions: 'top'});

### Content from attribute

hover

This example uses the contentSelector attribute to determine where the content comes from. In this case the selector is `$(this).attr('href')` and the content is the href attribute of the hovered link. Other options define a red balloon with bold white text. The box will be a variable width up to 400px ("width: 'auto' in cssStyles makes text box shrink-to-fit) with rounded corners. The script will try to position the box to the left, then to the right, and finally it will place it on the bottom if it does not fit elsewhere.

$('#example3').bt({ contentSelector: "$(this).attr('href')", fill: 'red', cssStyles: {color: 'white', fontWeight: 'bold', width: 'auto'}, width: 400, padding: 10, cornerRadius: 10, spikeLength: 15, spikeGirth: 5, positions: ['left', 'right', 'bottom'] });

### Pre/post functions

hover

There are four different functions which can be triggered at different points in the lifetime of a beautyTip: preShow, postShow, preHide, and postHide.

In this example, a function is triggered to change the content of the target element before the tip is shown. After the tip is hidden, another function changes the content back. `this` in these function refers to the target element. These functions could be used for just about anything.

$('#example4').bt({ preShow: function() { $(this).data('origContent', $(this).html()); $(this).html('hovering active'); }, postHide: function() { $(this).html($(this).data('origContent')); } });

### CSS tricks

hover

When the BeautyTip is active, an additional class is added to the target element. This class, called "activeClass", can be defined when calling the bt() function. Additionally, each BeautyTip popup has a wrapper div which surrounds its content. The class on this div is also definable.

Note that the BeautyTip "balloon" itself is drawn as a bitmap using canvas methods and functions similar to an <img> element, so it can not be affected by CSS. There are many options for changing this element using JavaScript options though.

$('#example5').bt({ activeClass: 'example-5-active', cssClass: 'example-5-tip' });

### Customizing the balloon

hover

The BeautyTip balloons are drawn dynamically and highly configurable. Customizable attributes include background color and opacity, stroke width and color, spike length and width, corner radius, and more. For convenience, style attributes such as font color and weight can be sent through the JavaScript call as well.

$('#example6').bt({ padding: 20, width: 100, spikeLength: 40, spikeGirth: 40, cornerRadius: 40, fill: 'rgba(0, 0, 0, .8)', strokeWidth: 3, strokeStyle: '#CC0', cssStyles: {color: '#FFF', fontWeight: 'bold'} });

### Image content

hover

Images can be loaded into the BeautyTip. You should, however, add width and height attributes (or use CSS for this) so that the browser will know what size to "save space for" as the image loads.

This example also uses some special triggers so that the tip appears on mouseover, but disappears using click. BeautyTips' default clickAnywhereToClose option also allows the user to click anywhere in the document (outside of the tip) in order to close it. This can be disabled either globally or per tip.

$('#example16').bt('', { width: 200, fill: 'white', cornerRadius: 20, padding: 20, strokeWidth: 1, trigger: ['mouseover', 'click'] });

### Customizing triggers

The trigger is what causes the tip to appear/disappear. The default option is 'hover', which will trigger the tip when the mouse hovers over an element. If the hoverintent plugin is installed (as on this page), that will become the default trigger and there will be slight (but configurable) delay before the tip appears.

In this example, the trigger events for this textfield are 'focus' and 'blur'. This means that the tip will get triggered even if the user uses the tab key to enter/leave this form field.

$('#example7').bt({ trigger: ['focus', 'blur'], positions: ['right'] });

### Customizing triggers 2

In this example, 'keyup' triggers the display of the tip while 'blur' removes it. This means that the tip won't appear until the user actually changes the field (using the keyboard).

The full list of trigger events are: `blur, focus, load, resize, scroll, unload, click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup,` and `error`. However not all events are available for all elements (see: events documentation).

$('#example8').bt({ trigger: ['keyup', 'blur'], positions: ['right'] });

### Scripting on/off

no trigger

This tip is initiated with a trigger of 'none'. All of the options are set, but turn on/off of the tip isn't bound to any event. We can, however, turn on and off the tip using Javascript. $('#example15').btOn(); turns it on. $('#example15').btOff(); turns it off. These btOn() and btOff() functions are available for all elements which have been set up using the bt() function. So, we can programmatically turn on any BeautyTip on the page. Click here to turn on the tip from the previous example.

$('#example15').bt({ trigger: 'none', contentSelector: "$('#example-15-content')", width: 400 });

### HoverIntent

hover and wait

The hoverIntent plugin allows control over how and when the mouseOver event gets triggered when a user hovers over an element. In this example, the `interval` has been cranked up to 1 second, so the user needs to hover for almost a second before the tip appears. The timeout has been raised to 2 seconds so the tip will remain visible for that long before disappearing.

$('#example9').bt({ hoverIntentOpts: { interval: 1000, timeout: 2000 } });

### Ajax content

hover

Content comes from the `#content` div of the html page: demo-ajax.html. Note: this isn't really ajax, it's actually ahah (asychronous HTML and HTTP). Ahah is much easier to deal with than ajax (which technically uses XML).

$('#example10').bt({ ajaxPath: 'demofiles/demo-ajax.html div#content' });

### Ajax error

hover

Requested ajax page doesn't exist. This example uses a custom error message. This example may not work correctly if you have opened the file locally (without a web server).

$('#example11').bt({ ajaxPath: 'foo.html', ajaxError: "Egads! There was a problem getting this content. Here's what we know: %error." });

### Ajax dynamic path

hover

AjaxPath is being read from the 'href' value of the link. This is accomplished by defining the ajaxPath as an array. The first value of the array is the jQuery code to find the path value (in this case `"$(this).attr('href')"`). The optional second value of the array is the content selector within the loaded page (in this case `'div#content'`). This is a handy way of adding "preview" BeautyTips to a bunch of links on a page.

$('#example18').bt({ ajaxPath: ["$(this).attr('href')", 'div#content'] });

### Big Big Big

click

A popup with lots of content. This popup gets populated from a div which immediately follows this text in the html source, but gets hidden by the same script which defines the BeautyTip. This is a good way to provide degradable help which appears for users with JavaScript disabled.

### A really big popup

This tip is chock-full of content. It is intended to show how BeautyTips deals with fitting large content onto the page. The rest of this content is gibberish. Seamlessly empower dynamic communities with clicks-and-mortar testing procedures. Globally scale front-end ideas through next-generation web services. Holisticly harness business data via resource maximizing meta-services.

Assertively pontificate extensible ROI via end-to-end manufactured products. Compellingly scale resource sucking human capital rather than visionary infomediaries. Quickly evolve robust data with intuitive vortals.

Authoritatively revolutionize scalable solutions without e-business intellectual capital. Compellingly restore web-enabled potentialities through tactical information. Phosfluorescently disintermediate stand-alone convergence for team building sources.

Interactively leverage existing sticky products rather than orthogonal expertise. Enthusiastically innovate worldwide process improvements whereas proactive markets. Appropriately evisculate B2B niche markets before vertical content.

Quickly reinvent state of the art potentialities after process-centric experiences. Completely e-enable sticky technology whereas impactful ideas. Dynamically underwhelm holistic "outside the box" thinking whereas effective testing procedures.

Synergistically plagiarize cost effective leadership and low-risk high-yield e-commerce. Credibly maintain market positioning strategic theme areas and client-based benefits. Globally disseminate clicks-and-mortar infomediaries for premium e-tailers.

Professionally reconceptualize interdependent content through error-free innovation. Collaboratively provide access to one-to-one strategic theme areas without magnetic web-readiness. Appropriately negotiate strategic opportunities without timely alignments.

Continually engineer premier best practices after plug-and-play communities. Monotonectally drive installed base users whereas wireless products.

$('#example-14-content').hide(); $('#example14').bt({ trigger: 'click', contentSelector: "$('#example-14-content').html()", /*get text of inner content of hidden div*/ width: 500, fill: '#00FF4E', strokeWidth: 0, /*no stroke*/ spikeLength: 40, spikeGirth: 10, padding: 20, cornerRadius: 15, cssStyles: { fontFamily: '"lucida grande",tahoma,verdana,arial,sans-serif', fontSize: '13px' } });

### Netflix style

hover

Netflix-style big descriptive popups using ajax.

$('#example13').bt({ ajaxPath: 'demofiles/netflix.html', overlap: -8, centerPointY: .1, positions: ['right', 'left'], padding: 0, width: 256, spikeGirth: 60, spikeLength: 50, cornerRadius: 10, fill: '#FFF', strokeStyle: '#B9090B', shadow: true, shadowBlur: 12, hoverIntentOpts: {interval: 800, timeout: 0}, cssStyles: { fontSize: '12px', fontFamily: 'arial,helvetica,sans-serif' } });

### Google Maps

Google Maps balloons! Content is provided by a hidden div on the page. Note the use of centerPointX to adjust where the spike extends from. We're also using a close-box "x" image in the content which is a javascript link to close the tip.

Address:
123 Main St.
Seekonk, MA 02771
Get directions: To here - From here
Search nearby - Save to My Maps
Edit
$('#example-17-content').hide(); $('#example17').bt({ positions: 'top', contentSelector: "$('#example-17-content')", /*hidden div*/ trigger: 'click', width: 220, centerPointX: .9, spikeLength: 65, spikeGirth: 40, padding: 15, cornerRadius: 25, fill: '#FFF', strokeStyle: '#ABABAB', strokeWidth: 1 });

### Facebook style

hover

Facebook-style.

$('#example12').bt({ fill: '#F7F7F7', strokeStyle: '#B7B7B7', spikeLength: 10, spikeGirth: 10, padding: 8, cornerRadius: 0, cssStyles: { fontFamily: '"lucida grande",tahoma,verdana,arial,sans-serif', fontSize: '11px' } });

## Options

A full list of options can be found at the bottom of the jquery.bt.js file itself. Scroll to the bottom of the file to see the list of options along with their default values and a short descriptions of what each one does.

These defaults can be overridden during each call to the $.bt() function (as in the examples above) or they can be overridden globally for all BeautyTips on the page. For instance, to change the ajax loading content for all BeautyTips on the page, you could insert the following code into your document's <head> (somewhere after <script src="jquery.bt.js"...):

> `<script language="JavaScript">
> jQuery.bt.defaults.ajaxLoading = '<img src="/images/throbber.gif" width="40" height="40" />';
> jQuery.bt.defaults.closeWhenOthersOpen = true;
> </script>`

## Wrapup

Found bugs and/or want to contribute to development? Please use the issue queue on jQuery.com.

Twitter: I tend to post about BeautyTips development on Twitter, so follow me if you'd like to keep up with the latest news.

IRC: I also tend to hang out in the #jQuery IRC room (username: jjeff). If you've got quick questions about BeautyTips, try to find me there.

It's always encouraging to hear from people using BeautyTips for cool and/or notable things. Just send a note to
. I'd love to hear from you. Please do not email me with support requests. Those should go to the issue queue.

- Jeff Robbins