A flexible, adaptable and easy to use tooltip positioning library.
- jQuery
- Unerscore.js
- CoffeeScript (development only)
The documentation and source of this library refers to several terms that may require clarification:
Tooltip: An instance of FlowTip object.
Root: The root of a tooltip refers to the element that contains both the tooltip's "content" element, and "tail" element.
Content (element): The container element for the tooltip's content.
Tail: The tail of the tooltip. It's usually visualized as a pointy "nub" of sort.
Target: The target is the thing the tooltip points to.
Region: There are four different regions a tooltip could be in at any given time. The four regions are "top", "bottom", "left" and "right". Region is described relative to the target of the tooltip. For example, region "top" means the tooltip would appear above the target, and region "right" means the tooltip would appear to the right side of the target.
Pivot: The pivot is a imaginary line that is aligned to the target and the tooltip's root is then in term aligned to the pivot.
Creates an instance of the FlowTip object:
var tooltip = new FlowTip();
An instance of the FlowTip can be created with options (see Attributes section below):
var myFlowTip = new FlowTip({
region: "bottom"
className: "my-tip"
hasTail: false
})
At this point, the tooltip is not yet "attached" to a target. The tooltip's target can be set by
calling setTarget:
tooltip.setTarget(tooltipTarget);
... where tooltipTarget may be a DOM object or a jQuery selection.
To make the tooltip visible, call show:
tooltip.show();
This will render the tooltip is it's not already rendered, and position the tooltip in the
appropriate region (see region in Attributes section below) with proper alignments
(see Alignments section below).
It's important to note that instances of FlowTip does not automatically re-position themselves when their targets move. The responsibility of detecting target movement lies outside the scope of this library. To update the tooltip's position against its target:
tooltip.reposition();
Default value: ""
Additional class name(s) for the container of the tooltip.
Default value: ""
Additional class name(s) for the tooltip's content.
Default value: ""
Additional class name(s) for the tooltip's tail.
Default value: null
The element within which the tooltip will be inserted into. Can be set or updated by calling
setAppendTo. Default value is the document's body and the tooltip would thus be free to appear
and move anywhere on the page and edge detection will only be performed on the edge of the page.
If appendTo is set to an element then edge detection will be performed on the edge of
the element instead.
Default value: null
The content of the tooltip. May be specified as (HTML) string or DOM element. Can be set original
updated by calling setTooltipContent.
Default value: top
The preferred region in which the tooltip will appear at first relative to its target. Possibly
values are: top, bottom, left and right.
Default value: false
When set to true, the specified region will become unavailable for the various edge detection
algorithms.
Default value: false
When set to true, and when the only suitable regions for the tooltip are disabled, the tooltip
will be hidden. When set to false, and when the only suitable regions for the tooltip are
disabled, the tooltip will be placed in its original region.
Default value: false
If set to true, the tooltip will revert back to its preferred region whenever there is enough
space in that region. If set to false, the tooltip will remain in the region edge detection
puts it in, until edge detection changes it again.
Default value: true
Controls if the tooltip's tail's visibility. When set to false the tooltip's tail will be hidden
and ignored for all positioning calculations.
Default value: null
Width of the tooltip's root. If set to null, the tooltip will expand to fit its content's width.
Default value: auto
Height of the tooltip's root. If set to null, the tooltip will expand to fit its content's
height. If set to "auto", the tooltip's content will be relatively positioned to allow possible
scrolling.
Default value: null
In the form of 42px, or other forms accepted by CSS min-width.
Default value: null
In the form of 42px, or other forms accepted by CSS max-width.
Default value: null
In the form of 42px, or other forms accepted by CSS min-height.
Default value: null
In the form of 42px, or other forms accepted by CSS max-height.
Default value: 20
Width of the tail element.
Default value: 10
Height of the tail element.
Default value: 10
The distance between the tooltip's root (or tip of the tail, see targetOffsetFrom below) and
the target's edge.
Default value: root
Possible values are root and tail. When set to root, targetOffset will be calculated
against the edge of the tooltip's root; When set to tail, targetOffset will be calculated
against the tip of the tail.
Default value: 30
The distance between the tooltip's root's edge and the edge of the boundary representative the
tooltip's appendTo element. When this distance is smaller than edgeOffset, edge detection
will place the tooltip in an opposite region (i.e. flipping the tooltip).
Default value: 30
The distance between the target's edge and the edge of the boundary representative the tooltip's
appendTo element. When this distance is smaller than rotationOffset, edge detection will
place the tooltip in an adjacent region (i.e. rotating the tooltip).
Default value: center
Possible values are center and edge. When set to center, the pivot will be center aligned
against the target. When set to edge, one of the pivot's edge will be aligned against the pivot.
See targetAlignOffset for the exact mechanics of the two values. This value can also be
specified on a per-region basis via [top|bottom|left|right]TargetAlign, and if a region's
specific value is absence, the value from targetAlign will be used.
Default value: 0
If targetAlign is set to center, this value controls the clockwise distance from the center
of the target the pivot will shift. When this value is positive, the pivot will shift clockwise,
and counter-clockwise when this value is negative.
If targetAlign is set to edge, the pivot will shift away from one of the target's edges.
When this value is positive, the clockwise edge will be used, and the counter-clockwise edge
will be used when this value is negative. The absolute value of this value controls the amount
of shifting.
Default value: center
Possible values are center and edge. When set to center, the tooltip's root will be center
aligned against the pivot. When set to edge, one of the tooltip's root's edge will be aligned
against the pivot. See rootAlignOffset for the exact mechanics of the two values. This value
can also be specified on a per-region basis via [top|bottom|left|right]RootAlign, and if a
region's specific value is absence, the value from rootAlign will be used.
Default value: 0
If rootAlign is set to center, this value controls the clockwise distance from the pivot the
tooltip's root will shift. When this value is positive, the root will shift clockwise, and
counter-clockwise when this value is negative.
If rootAlign is set to edge, one of the tooltip's root's edge will be aligned against the
pivot. When this value is positive, the clockwise edge will be used, and the counter-clockwise
edge will be used when this value is negative. The absolute value of this value controls the
amount of shifting.
Accepts a hash of options. See Attributes.
Render the tooltip's root (if not already rendered), content and insert the tooltip into the DOM. If called repeatedly, only re-render the tooltip's content.
Set the tooltip's containing element. If the tooltip has already been rendered, the tooltip will be moved/inserted into the new containing element.
Set the tooltip's target. The target is the element to which the tooltip will be pointing at.
Set the tooltip's target to be a ClientRect instead of a html element. The target is the ClientRect to which the tooltip will be pointing at.
Set the tooltip's content. If render is set to true for options, the render() method will
be called to re-render the content.
Perform edge detection and position calculations to update the tooltip's position.
Show the tooltip. Also update the tooltip's visible attribute.
Hide the tooltip. Also update the tooltip's visible attribute.
Trigger an event from the root of the tooltip.
Remove the tooltip's root from DOM.
There are three strategies for detection: flip, rotate and squeeze.
The tooltip will be flipped when the root of the tooltip gets too close to the edge of the
boundary. Adjust edgeOffset to control the amount of space allowed. The tooltip will be
flipped horizontally when in the left and right regions, and vertically when in the top and
bottom regions.
The tooltip will be rotated to an adjacent region if the target gets too close to the edge of
the boundary. Adjust rotationOffset to control the amount of space allowed. For example, the
tooltip will be rotated to the top region if the tooltip is currently in the left or right
region, and the target gets too close to the bottom edge of the boundary.
The tooltip will be squeezed to an adjacent region if the root of the tooltip gets too close to the edge of the boundary on both sides. For example, if the tooltip is in left or right region, and neither region has enough space, the tooltip will be squeezed to the top region.
Tool tip's alignments are divided into root alignment and target alignment, each with a corresponding offset attribute that controls the direction of the alignment and offset amount.
Target alignment refers to the alignment of the pivot relative to the target of the tooltip. See
targetAlign and targetAlignOffset.
Root alignment refers to the alignment of the tooltip's root relative to the pivot. See
rootAlign and rootAlignOffset.
TODO: Add documentation for FlowTip.Coordinator