JS Tutorial
- Overview
- Documents
Simpletip is a plugin for the popular jQuery JavaScript library. It allows you to create tooltips with ease on any element on the page using the power of jQuery's selectors and event management. The tooltips can be static, dynamic, or even loaded through AJAX with a variety of different visual effects.
Configuration
There are many other ways of using this tool than the demos provided here. It is important to realize that any element can have a simpletip assigned to it! Simpletip is always styled and instantiated with following:
$("JQUERY SELECTOR").simpletip({
// Configuration properties
content: 'My Simpletip',
fixed: false
});
// Default tooltip class name: .tooltip
.tooltip{
position: absolute;
top: 0;
left: 0;
z-index: 3;
display: none;
}
The tooltip must be absolutely positioned for the positioning to work correctly. If you are having problems with tooltips not showing or being positioned correctly this is most likely the cause of it!
Configuration properties
| Name | Description | Possible values | Default value |
|---|---|---|---|
| content | The HTML content which will appear inside the tooltip. | Valid HTML | A simple tooltip |
| persistent | If set to true the tooltip will activate onclick rather than the defaultonhover behaviour. | true or false | false |
| focus | For use with the persistent config option. If set to true the tooltip will stay active (on screen) until the document is clicked elsewhere. If false, tooltip will also close when clicked. | true or false | false |
| hidden | If set to false the tooltip will be shown immediately when created.Works well with persistent. | true or false | true |
| position | Determines how the tooltip is positioned relative to the element it is shown on. An array of x, y can be used set an absolute position. Encapsulating them in a string e.g. ["0", "0"] causes the positioning to be done relative to the top left corner of the root element. An HTML element can also be passed as an argument and it's current position assumed by the tooltip. |
default top, bottom left, right absolute: [x, y] relative: ["x", "y"] mixed: ["x", y] / [x, "y"] HTML element |
default |
| offset | Array of x, y by which to offset the tooltips position relative to that calculated by the position property. | Array of any 2 integers | [0, 0] |
| boundryCheck |
If true positioning will take into account window height and width to ensure tooltip does not scroll off page e.g. is always visible. NOTE: Set this to false if your experiencing jittering on non-fixed tooltips |
true or false | true |
| fixed | If set to false the tooltip moves with mouse as long as mouse is hovered over the root element. | true or false | true |
| showEffect | Type of show effect to use. | fade, slide, none | fade |
| hideEffect | Type of hide effect to use. | fade, slide, none | fade |
| showTime | Time in milliseconds for showEffect effect. | Positive integer | 150 |
| hideTime | Time in milliseconds for hideEffect effect. | Positive integer | 150 |
| showCustom | Used along with the showEffect: 'custom' property. Custom method called when tooltip is shown. | Defined method | null |
| hideCustom | Used along with the hideEffect: 'custom' property. Custom method called when tooltip is hidden. | Defined method | null |
| baseClass | Class name to apply to generated tooltip elements supplied without the dot prefix. | Any valid class name | tooltip |
| activeClass | Class name to apply to active (currently shown) tooltip elementssupplied without the dot prefix. | Any valid class name | active |
| fixedClass | Class name to apply to tooltip elements which move with the mouse i.e. non-static supplied without the dot prefix. | Any valid class name | fixed |
| persistentClass | Class name to apply to presistent tooltip elements supplied without the dot prefix. | Any valid class name | persistent |
| focusClass | Class name to apply to persistent focus tooltip elements supplied without the dot prefix. | Any valid class name | focus |
| onBeforeShow | Callback method to execute before tooltip is shown. | Defined method | function(){} |
| onShow | Callback method to execute after tooltip is shown. | Defined method | function(){} |
| onBeforeHide | Callback method to execute before tooltip is hidden. | Defined method | function(){} |
| onHide | Callback method to execute after tooltip is hidden. | Defined method | function(){} |
| beforeContentLoad | Callback method to execute before content is loaded using theload method. | Defined method | function(){} |
| onContentLoad | Callback method to execute after content is loaded using the loadmethod. | Defined method | function(){} |
Callback functions
The Simpletip library provides several key callback functions as part of it's API, allowing you to extend the functionality of the library with custom methods. Below is an example utilising the onShow method to change the content an element:
$("JQUERY SELECTOR").simpletip({
// onShow method - change content of parent element
onShow: function(){
this.getParent().text('My content changes when my tooltip appears!')
}
// Configuration properties
content: 'My Simpletip'
});
Scripting API
The Simpletip comes with a great scripting API for users. A lot of effort has been made to make sure you have the necessary functionality to enrich the library with as little effort as possible. Once you've setup your simpletip on your element(s) the API can be accessed via the simpletip() call. An example of this is below:
// Create your tooltips
$('JQUERY SELECTOR').simpletip();
// Access the API of a previously initatied simpletip
var api = $('JQUERY SELECTOR').eq(0).simpletip();
// Perform a simple API call to update tooltip contents
api.update('New tooltip content!');
Here's a list of all API methods available to you in the library:
| Method | Arguments | Return value | Description |
|---|---|---|---|
| getVersion() | [x, x, x] | Returns the version number of the Simpletip library currently in use. | |
| getParent() | Object | Returns the element which the tooltip is associated with e.g. the element on which the simpletip() method was called. | |
| getTooltip() | Object | Returns the tooltip element. | |
| getPos() | [top, left] | Returns the absolute current position of the tooltip element. | |
| setPos() | posX, posY | Simpletip | Sets position of tooltip to absolute arguments posX and posY if supplied as integers, or relative to parent element if supplied as strings. A mixture of both strings and integers can also be used. |
| show() | Simpletip | Displays the tooltip element. | |
| hide() | Simpletip | Hides the tooltip element. | |
| update() | content | Simpletip | Updates the contents of the tooltip element with the supplied argument, usually a string or integer. |
| load() | url, data | Simpletip | Updates the contents of the tooltip element with the contents of a remote file urlusing AJAX. Use the data array to pass POST data on the AJAX call. |
