clueTip Plugin Details
Multiple Content Sources
The contents of the clueTip can come from one of these sources:
- a separate file, via AHAH / AJAX
- an element on the same page, typically hidden
- the title attribute, parsed by a user-defined delimiter (if the "splitTitle"
option is set). The text before the first delimiter becomes the clueTip title,
and the rest of the text parts are placed in
<div class="split-body"></div>elements and appended to the clueTip body
Smart Positioning
The clueTip Plugin uses the excellent Dimensions Plugin to accurately position the tooltips on the page. It has 4 positioning modes, which you can change via the "positionBy" option.positionBy: 'auto'(default)- places the tooltip just to the right of the invoking element , but...
- if there is not enough room for the tooltip to be fully visible between the right edge of the invoking element and the right edge of the browser window, switches from the right side to the left side , but...
- if the invoking element is too close to the bottom edge of the browser window, adjusts the tooltip upwards until the whole tooltip is visible , but...
- if the tooltip is taller than the window (i.e. the viewable area), adjusts the tooltip back down until the tooltip's top is at the top edge of the browser window , but...
- position if the invoking element is so wide that the tooltip can't completely fit to the left or the right of it, places the tooltip to the right or left of the mouse , but...
- if the tooltip itself can't fit to the right or left of the mouse position, places the tooltip below the mouse position (centered horizontal if enough room) , but...
- if (a) there isn't enough room below without being cut off, and (b) there is enough room between the top of the viewable area and the mouse, puts the tooltip above the mouse position
positionBy: 'mouse'- places the tooltip to the right of the mouse position , but...
- if there is not enough room to the right, places the tooltip to the left of the mouse position , but...
- if the tooltip itself can't fit to the right or left of the mouse position, places the tooltip below the mouse position (centered horizontally if enough room) , but...
- if (a) there isn't enough room below without being cut off, and (b) there is enough room between the top of the viewable area and the mouse, puts the tooltip above the mouse position
positionBy: 'bottomTop'- places the tooltip below the mouse position (centered horizontally if enough room) , but...
- if (a) there isn't enough room below without being cut off, and (b) there is enough room between the top of the viewable area and the mouse, puts the tooltip above the mouse position
positionBy: 'fixed'- places the tooltip in the same location relative to the invoking element , regardless of where it appears on the page.
- the fixed position can be adjusted by modifying the number of pixels in the
topOffsetandleftOffsetoptions
Flexible Behavior
- The clueTip takes advantage of Brian Cherne's fantastic hoverIntent
plugin
if it's available. (Just include it in a
<script>tag if you want the clueTip to use it.) - It can be activated on hover or on click.
- It can fade in, slide down, etc.
- It can close when the invoking element is moused out or when the tooltip is moused out or when the user clicks a "close" link.
- It can cache the results of ajax requests—or not.
- It can be turned off
Variety of Styles
The clueTip Plugin comes with three themes: default, jTip, and rounded
corners. Additional themes can be created by following the naming patterns in
the stylesheet, jquery.cluetip.css. To apply one of the alternative themes, just
indicate it in the cluetipClass
option as 'jtip'
or
'rounded'
.
The "loading" image comes from this rule in the stylesheet:
#clueti
p-waitimage {
width
:
43px
;
height
:
11px
;
position
:
absolute
;
background-image
:
url
(
wait
.gif);
}
It can be turned off with the following option: waitImage:
false
Other options that affect the visual appearance include
hoverClass
, arrows
, dropShadow
, and
dropShadowSteps
. Please see API / Options
for more information.
clueTip Plugin API / Options
clueTip Plugin API / Options
- /*
- * @name clueTip
- * @type jQuery
- * @cat Plugins/tooltip
- * @return jQuery
- * @author Karl Swedberg
- *
- * @credit Inspired by Cody Lindley's jTip (http://www.codylindley.com)
- * @credit Thanks to Shelane Enos for the feature ideas
- * @credit Thanks to the following people for their expert advice, code enhancements, bug fixes, etc.:
- Glen Lipka, Hector Santos, Torben Schreiter, Dan G. Switzer, Jörn Zaefferer
- * @credit Thanks to Jonathan Chaffer, as always, for help with the hard parts. :-)
- */
- /**
- *
- * Displays a highly customizable tooltip when the user hovers (default) or clicks (optional) the matched element.
- * By default, the clueTip plugin loads a page indicated by the "rel" attribute via ajax and displays its contents.
- * If a "title" attribute is specified, its value is used as the clueTip's heading.
- * The attribute to be used for both the body and the heading of the clueTip is user-configurable.
- * Optionally, the clueTip's body can display content from an element on the same page.
- * * Just indicate the element's id (e.g. "#some-id") in the rel attribute.
- * Optionally, the clueTip's body can display content from the title attribute, when a delimiter is indicated.
- * * The string before the first instance of the delimiter is set as the clueTip's heading.
- * * All subsequent strings are wrapped in separate DIVs and placed in the clueTip's body.
- * The clueTip plugin allows for many, many more options. Pleasee see the examples and the option descriptions below...
- *
- *
- * @example $('#tip).cluetip();
- * @desc This is the most basic clueTip. It displays a 275px-wide clueTip on mouseover of the element with an ID of "tip." On mouseout of the element, the clueTip is hidden.
- *
- *
- * @example $('a.clue').cluetip({
- * hoverClass: 'highlight',
- * sticky: true,
- * closePosition: 'bottom',
- * closeText: '<img src="cross.png" alt="close" />',
- * truncate: 60,
- * ajaxSettings: {
- * type: 'POST'
- * }
- * });
- * @desc Displays a clueTip on mouseover of all <a> elements with class="clue". The hovered element gets a class of "highlight" added to it (so that it can be styled appropriately. This is esp. useful for non-anchor elements.). The clueTip is "sticky," which means that it will not be hidden until the user either clicks on its "close" text/graphic or displays another clueTip. The "close" text/graphic is set to diplay at the bottom of the clueTip (default is top) and display an image rather than the default "Close" text. Moreover, the body of the clueTip is truncated to the first 60 characters, which are followed by an ellipsis (...). Finally, the clueTip retrieves the content using POST rather than the $.ajax method's default "GET."
- *
- * More examples can be found at http://plugins.learningjquery.com/cluetip/demo/
- *
- * @param Object defaults (optional) Customize your clueTips
- * @option Integer width: default is 275. The width of the clueTip
- * @option Integer|String height: default is 'auto'. The height of the clueTip. Setting a specific height also sets <div id="cluetip-outer"> to overflow:auto
- * @option Integer cluezIndex: default is 97; sets the z-index style property of the clueTip.
- * @option String positionBy: default is 'auto'. Available options: 'auto', 'mouse', 'bottomTop', 'fixed'. Change to 'mouse' if you want to override positioning by element and position the clueTip based on where the mouse is instead. Change to 'bottomTop' if you want positioning to begin below the mouse when there is room or above if not -- rather than right or left of the elemnent and flush with element's top Change to 'fixed' if you want the clueTip to appear in exactly the same location relative to the linked element no matter where it appears on the page. Use 'fixed' at your own risk.
- * @option Integer topOffset: number of pixels to offset the clueTip from the top of the linked element. For positionBy "auto", "mouse", and "bottomTop" the number will be added to the clueTip's "top" value if the clueTip appears below the linked element and subtracted from it if the clueTip appears above. For positionBy "fixed", the number will be added to the "top" value, offsetting the clueTip from the top of the linked element.
- * @option Integer leftOffset: number of pixels to offset the cluetip horizontally from the linked element. For positionBy "auto", "mouse", and "bottomTop" the number will be added to clueTip's "left" value if the clueTip appears to the right of the linked element and subtracted if the clueTip appears to the left. For positionBy "fixed", the number will be added to the "left" value of the clueTip, offsetting it from the right-most part of the linked element.
- * @option Boolean local: default is false. Whether to use content from the same page (using ID) for clueTip body
- * @option Boolean hideLocal: default is true. If local option is set to true, determine whether local content to be shown in clueTip should be hidden at its original location.
- * @option String attribute default is 'rel'. The attribute to be used for the URL of the ajaxed content
- * @option Boolean showtitle: default is true. Shows the title bar of the clueTip, whether a title attribute has been set or not. Change this to false to hide the title bar.
- * @option String cluetipClass: default is 'default'; this adds a class to the outermost clueTip div with a class name in the form of 'cluetip-' + clueTipClass. It also adds "clue-left-default" or "clue-right-default" to the same div, depending on whether the clueTip is to the left or to the right of the link element. This allows you to create your own clueTip theme in a separate CSS file or use one of the three pre-packaged themes: default, jtip, or rounded.
- * @option String titleAttribute: default is 'title'. The attribute to be used for the clueTip's heading, if the attribute exists for the hovered element.
- * @option String splitTitle: default is '' (empty string). A character used to split the title attribute into the clueTip title and divs within the clueTip body; if used, the clueTip will be populated only by the title attribute,
- * @option String hoverClass: default is empty string. designate one to apply to the hovered element
- * @option String closePosition: default is 'top'. Set to 'bottom' to put the closeText at the bottom of the clueTip body
- * @option String closeText: default is 'Close'. This determines the text to be clicked to close a clueTip when sticky is set to true.
- * @option Number truncate: default is 0. Set to some number greater than 0 to truncate the text in the body of the clueTip. This also removes all HTML/images from the clueTip body.
- * @option Boolean waitImage: default is true. Set to false to avoid having the plugin try to show/hide the image.
- * @option Boolean arrows: Default is false. Set to true to display an arrow at the appropriate side of the cluetip and lined vertically with the hovered element.
- * @option Boolean dropShadow: default is true; set it to false if you do not want the drop-shadow effect on the clueTip
- * @option Integer dropShadowSteps: default is 6; change this number to adjust the size of the drop shadow
- * @option Boolean sticky: default is false. Set to true to keep the clueTip visible until the user either closes it manually by clicking on the CloseText or display another clueTip.
- * @option Object fx: default is: {open: 'show', openSpeed: ''}. Change these to apply one of jQuery's effects when opening the clueTip
- * @option String activation: default is 'hover'. Set to 'toggle' to force the user to click the element in order to activate the clueTip.
- * @option Object hoverIntent: default is {sensitivity: 3, interval: 50, timeout: 0}. If jquery.hoverintent.js plugin is included in <head>, hoverIntent() will be used with these settings instead of hover(). Set to false if for some reason you have the hoverintent plugin included but don't want to use it. For info on hoverIntent options, see http://cherne.net/brian/resources/jquery.hoverIntent.html
- * @option Function onShow: default is function (ct, c){} ; allows you to pass in your own function once the clueTip has shown.
- * @option Boolean ajaxCache: Default is true; caches the results of the ajax request to avoid unnecessary hits to the server. When set to false, the script will make an ajax request every time the clueTip is shown, which allows for dynamic content to be loaded.
- * @option Object ajaxProcess: Default is function(data) { data = $(data).not('style, meta, link, script, title); return data; } . When getting clueTip content via ajax, allows processing of it before it's displayed. The default value strips out elements typically found in the <head> that might interfere with current page.
- * @option Object ajaxSettings: allows you to pass in standard $.ajax() parameters, not including error, complete, success, and url. Default is { dataType: 'html'}
- *
- */
- /*
* Global defaults for clueTips. Apply to all calls to the clueTip plugin.
*
* @example $.cluetip.setup({
* insertionType: 'prependTo',
* insertionElement: '#container'
* });
*
* @property
* @name $.cluetip.setup
* @type Map
* @cat Plugins/tooltip
* @option String insertionType: Default is 'appendTo'. Determines the method to be used for inserting the clueTip into the DOM. Permitted values are 'appendTo', 'prependTo', 'insertBefore', and 'insertAfter'
* @option String insertionElement: Default is 'body'. Determines which element in the DOM the plugin will reference when inserting the clueTip.
*
*/