affordable web development services
| About Us | Services | Download | Order | Support | Subscribe to News Feed Follow us on Twitter Join us on Facebook |
 

Tigra Hints v2.1 - Documentation

Table of Contents

Description

Tigra Hints is free JavaScript component that displays rich HTML content in pop-up boxes. Also known as tooltips or hints, these boxes can be activated on any event (such as mouseover or click) and provide or request context sensitive information.

Here are some application examples:

Features

Compatibility Table

Tigra Hints software is known to be working with any relatively modern browsers.
The table below lists some of the browsers the script was successfully tested with.

PlatformBrowser
MS IENetscapeMozilla/FirefoxOperaSafari
Windows 95/98/ME/2000/XP4.0+6+0.9+7.0+n/a
Mac OS 8/9/X5.0+6+0.9+7.0+1.3+

Note: Transition Effects are only supported in Internet Explorer v.5 or higher

Using this Document

Tigra Hints component is provided in form of the distribution package that contains the series of well commented functional samples. In many cases these samples can be customized and reused without thoroughly reading the documentation. Use this page as the reference and for troubleshooting purposes.

In this document we'll be using the following terms:

Code Organization

Tigra Hints have to be embedded and properly configured in the HTML page. Below is the list of the elements of the Tigra Hints configuration:

Element Description Notes Type
Script's Code The implementation of the Tigra Hints
  • Normally no changes are required in this element
  • The code must be made available in the document before the first hint instance is created. Recommended location is between <head> .. </head>
JavaScript, required
Configuration Settings for the appearance and behaviour of the hints (more)
  • Configuration is a named JavaScript variable containing the set of key:value pairs
  • Multiple configurations can be defined within the singe HTML document to individually configure different hint instances. The name of the variable must be unique within the document.
  • Same configuration can be reused by multiple instances of the hints
  • If the configuration omitted the script will use all default settings
  • Configuration must be made available in the document before it is referenced in the hints initialization
JavaScript, optional
Hints List The list of HTML strings for individual hints (more)
  • Hints List is a named JavaScript array containing the text or HTML strings for the hints
  • Multiple hints lists can be defined within the singe HTML document to be used in different hint instances. The name of the variable must be unique within the document
  • The hints list can be omitted if page has pre-existing HTML code for the hints and the script is not required to generate them
  • Hints List must be made available in the document before it is referenced in the hints initialization
JavaScript, optional
CSS classes Hints' CSS
  • In the configuration the user can specify the class name for the hint container. The actual CSS class with the specified name must be defined in <style> section of the document or in external linked CSS file.
CSS, optional
Existing Hints Tigra Hints can control pre-existing HTML elements it didn't generate
  • Pre-existing hints must be contained in absolutely positioned tag with the unique ID
  • The ID of the existing element is used in the activation calls the same as the text keys of the Hints List
  • The HTML code for pre-existing hint should be placed after the hint initialization but before any event hookups for that hint (preferably right under the initialization)
  • Appearance settings from the script's configuration don't apply to the pre-existing hints
  • The text of the pre-existing hints is indexed by the search engines
HTML, optional
Initialization Creates the hints object instance
  • Hints instance initialization receives two optional parameters: configuration and hints list (see above)
  • Names of the variables passed to the initialization as parameters must exactly match those in the definitions of the variables
  • The initialization generates the HTML for the hints at its location in the document
  • It is recommended to place the hints initialization just below <body> tag to make sure they're not requested before created
  • There can be multiple hints initializations in the single HTML document in order to create several groups of hints with different settings
JavaScript, Required
Event Hookups Attach the hints to the elements of the page
  • The hint can be activated on virtually any event in the HTML element, usually it's onmouseover or onclick
  • The hints can also be called from any custom JavaScript function
  • The hookups use methods of the hints object: hintRef.show(hintID, originRef) and hintRef.hide()
HTML/JavaScript, required

Note: JavaScript and CSS elements can be either embedded into the HTML document directly or saved in the external file and referenced via the link. Generally if the JavaScript element is used in more than one page then it makes sense to put it in the linked external file. This allows browser to cache and reuse the content between page loads. This also simplifies the configuration management because changes applied in the external file will automatically apply to all the documents it is linked to.

Hint's Elements Examples

Linked Script's code (head)

<!-- link Tigra Hints script file -->
<script language="JavaScript" src="tigra_hints.js"></script>

Embedded CSS classes (head)

<style>
	.hintsClass {
		font-family: tahoma, verdana, arial;
		font-size: 12px;
		background-color: #f0f0f0;
		color: #000000;
		border: 1px solid #808080;
		padding: 5px;
	}
</style>

Linked CSS classes (head)

	<link rel="stylesheet" href="hints.css" />

Embedded Configuration and Hints List (head or body)

<script language="JavaScript">

// configuration variable for the hint object, these setting will be shared among all hints created by this object
var HINTS_CFG = {
	'wise'       : true,
	'margin'     : 10,
	'gap'        : 0,
	'align'      : 'tcbc',
	'css'        : 'hintsClass',
	'show_delay' : 200,
	'hide_delay' : 500,
	'follow'     : false,
	'z-index'    : 100,
	'IEfix'      : false,
	'IEtrans'    : ['blendTrans(DURATION=.3)', 'blendTrans(DURATION=.3)'],
	'opacity'    : 100 // opacity of the hint in %%
};
// text/HTML of the hints
var HINTS_ITEMS = [
	'short definition',
	'tooltip for item2 with some <b>HTML</b>',
	'tooltip for item3<br />This one is multi line',
	'tooltip for item4',
	'another sample tooltip with the <a href="http://www.softcomplex.com">link</a>'
];
</script>

Existing Hints (body)

<div id="preExHint1" style="position:absolute;z-index:1;visibility:hidden;width:250px;height:300px;">
	Sample Hint
</div>

Initialization (body)

<script language="JavaScript">
	var myHint = new THints (HINTS_ITEMS, HINTS_CFG);
</script>

Event Hookups (body)

<img src="img/k001.jpg" width="100" onMouseOver="myHint.show('tt1', this)" onMouseOut="myHint.hide()" />

Configuration Structure

Tigra Hints configuration is a JavaScript array of key:value pairs. Table below lists all the supported keys and their accepted values.

Key Description Unit Accepted Values Default Value
 
Positioning
align Alignment of the hint relatively to the origin. The value defined as the string of four characters 1 - origin vertical (t|m|b), 2 - origin horizontal (l|c|r), 3 - hint vertical (t|m|b), 4 - hint horizontal (l|c|r). Where t - top, m - middle, b - bottom, l - left, c - center, r - right. For example 'tcbc' means align bottom center of the hint with top center of the origin.

Notes:

  • When 'smart' option is activated the alignment may be affected by the script trying to move the hint into the visible part of the document
  • When the origin reference is not provided to the script the mouse position is used as the origin. In this case the first part of alignment value defaults to 'mc' regardless of what is specified
pixels 4 characters string, one of 91 possible combinations. '(t|m|b)(l|c|r)(t|m|b)(l|c|r)'. All letters are in lower case. The string must be in quotes. 'tlbl'
gap The minimal distance between the origin and the hint.

Notes:

  • Negative setting can be used to create overlapping
  • The same value is used for both vertical and horizontal distance
pixels Integer value (positive or negative) 0
margin When 'smart' option is activated this setting determines the minimal allowed distance between the hint and the edge of the browser window or frame.

Notes:

  • Negative setting can be used to create overlapping
  • The same value is used for both vertical and horizontal distance
  • If there is not enough space the display whole hint anywhere around the origin then the 'margin' parameter may be ignored
pixels Integer value (positive or negative) 0
smart If set to true the script attempts to always keep the hint in the visible area of the document.

Notes:

  • If the edge of the browser window or frame is closer than the distance specified in 'margin' setting then script will shift the hint to maintain the margin
  • If there is not enough space to shift the hint without affecting the 'gap' then the hint will be flipped to the other side of the origin element
  • The priorities of the parameters (from higher to lower) are: 'gap', 'margin', 'follow' and 'align'
boolean false - disabled, true - enabled true
follow If set to true the hint follows the mouse pointer.

Notes:

  • If origin reference is provided to the script then 'align' and 'gap' are maintained relatively to the origin element while the mouse pointer is within its boundaries. Outside of those boundaries the parameters are applied relatively to the mouse pointer location
  • The hint may stop following the mouse pointer if this conflicts with other parameter(s). For example if this conflicts with 'margin' setting when 'smart' is activated
boolean Boolean value:
false - no, true - yes
false
z-index Specifies the z-index which is the position of the element in the document's layers. Elements with the larger z-indexes are positioned in the front.

Notes:

  • This parameter needs to be adjusted only when some other elements of the page appear on top of the hints
  • The problem with windowed controls such as selectboxes can often be addressed by activating 'IEfix' feature
  • Negative z-index places the hint under the document making that hint invisible to the viewer
index integer value (usually positive) 1
Timing
show_delay Determines the pause between the triggering event and the time the hint is being displayed. This feature prevents hints from popping-up while user moves the mouse pointer over the origin without intending to stop it there.

Notes:

  • When 'show_delay' is set to 0 then hints are displayed immediately after triggering event
  • To maintain the threshold longer delays may be needed for larger origin elements
  • Any new hide or show event received while the delay is in effect resets the timer
millisecond (1/1000th of the second) Non-negative integer value 200
hide_delay Determines the pause between the triggering event and the time the hint is being hidden. This feature creates prevents flicker effects and allows hints to remain visible while multiple conflicting events are firing consequently.

Notes:

  • When 'hide_delay' is set to 0 then hints are hidden immediately after triggering event
  • Any new hide or show event received while the delay is in effect resets the timer
  • The sequence of the events is following: 1. show event 2. show_delay 3. show 4. hide event 5. hide_delay 6. hide. The script will not hide the hints automatically without hide event
milliseconds (1/1000th of the second) Non-negative integer value 200
Look
css The string supplied to 'css' parameter will be used inside class=".." attribute of the hints generated by the script. This feature can be used to apply style settings to all hints within the hint object instance.

Notes:

  • The class is applied to a <div> tag
  Name of existing CSS class no style
IEtrans Configures the transition effects supported in Internet Explorer 5 and higher. The parameter is the array of two strings: 1 - show transition, 2 - hide transition.

Notes:

  • If only one string provided in the array then the same effect will be used as hide transition and as show transition
  • If either transition needs to be disabled then null should be provided in its place
  • The list of the supported transitions is provided the next section of the document
none Array of two strings [null,null]
IEfix Activates the feature that provides the work around for the problem in the Internet Explorer with the windowed controls being visible through the document layers earless of z-indexes.

Notes:

  • This option doesn't affect the browsers other than IE5 and IE6 because other browsers don't have this issue
  • For best performance it is recommended to disable this feature if the hints don't overlap any windowed controls
boolean Boolean value:
false - disabled, true - enabled
false
opacity Sets the level of the hint's opacity with 0 for fully transparent and 100 for fully opaque.

Notes:

  • This setting applies to the whole hint. To have the 100% opaque text and fully transparent background do not specify the background color for the hint anywhere in CSS or in its HTML.
% 0-100 100

Notes: Use of the JavaScript structure as for the script configuration makes it very efficient because no additional parsing is required, but this also makes it very syntax sensitive. Below are some recommendations on how to avoid or detect the configuration problems:

Configuration Structure Sample

var HINTS_CFG2 = {
	'wise'       : true,
	'margin'     : 10,
	'gap'        : 20,
	'align'      : 'bctc',
	'css'        : 'hintsClass2',
	'show_delay' : 200,
	'hide_delay' : 500,
	'follow'     : false,
	'z-index'    : 100,
	'IEfix'      : false,
	'IEtrans'    : ['revealTrans(TRANSITION=3,DURATION=.5)', 'revealTrans(TRANSITION=2,DURATION=.5)'],
	'opacity'    : 80
};

See other notes in Code Organization section of this document.

Transition Effects

The transition effects are supported in Internet Explorer version 5 or later. The table below lists the effects that can be used in the IEtrans key in the configuration structure.

Effect string valueDescription
revealTrans(TRANSITION=0,DURATION=t)Box in
revealTrans(TRANSITION=1,DURATION=t)Box out
revealTrans(TRANSITION=2,DURATION=t)Circle in
revealTrans(TRANSITION=3,DURATION=t)Circle out
revealTrans(TRANSITION=4,DURATION=t)Wipe up
revealTrans(TRANSITION=5,DURATION=t)Wipe down
revealTrans(TRANSITION=6,DURATION=t)Wipe right
revealTrans(TRANSITION=7,DURATION=t)Wipe left
revealTrans(TRANSITION=8,DURATION=t)Vertical blinds
revealTrans(TRANSITION=9,DURATION=t)Horizontal blinds
revealTrans(TRANSITION=10,DURATION=t)Checkerboard across
revealTrans(TRANSITION=11,DURATION=t)Checkerboard down
revealTrans(TRANSITION=12,DURATION=t)Random dissolve
revealTrans(TRANSITION=13,DURATION=t)Split vertical in
revealTrans(TRANSITION=14,DURATION=t)Split vertical out
revealTrans(TRANSITION=15,DURATION=t)Split horizontal in
revealTrans(TRANSITION=16,DURATION=t)Split horizontal out
revealTrans(TRANSITION=17,DURATION=t)Strips left down
revealTrans(TRANSITION=18,DURATION=t)Strips left up
revealTrans(TRANSITION=19,DURATION=t)Strips right down
revealTrans(TRANSITION=20,DURATION=t)Strips right up
revealTrans(TRANSITION=21,DURATION=t)Random bars horizontal
revealTrans(TRANSITION=22,DURATION=t)Random bars vertical
revealTrans(TRANSITION=23,DURATION=t)Random of all above
blendTrans(DURATION=t)Blending effect
progid:DXImageTransform.Microsoft.Barn(DURATION=t,orientation=horizontal)
progid:DXImageTransform.Microsoft.Blinds(DURATION=t,bands=n)
progid:DXImageTransform.Microsoft.CheckerBoard(DURATION=t)
progid:DXImageTransform.Microsoft.Fade(DURATION=t)
progid:DXImageTransform.Microsoft.GradientWipe(DURATION=t,wipeStyle=0)
progid:DXImageTransform.Microsoft.Iris(DURATION=t,irisStyle=STAR)
progid:DXImageTransform.Microsoft.Iris(DURATION=t,irisStyle=CIRCLE)
progid:DXImageTransform.Microsoft.Pixelate(DURATION=t,maxSquare=n)
progid:DXImageTransform.Microsoft.RandomDissolve(DURATION=t)
progid:DXImageTransform.Microsoft.Spiral(DURATION=t)
progid:DXImageTransform.Microsoft.Stretch(DURATION=t,stretchStyle=push)
progid:DXImageTransform.Microsoft.Strips(DURATION=t,motion=rightdown)
progid:DXImageTransform.Microsoft.Wheel(DURATION=t,spokes=n)

Transition Effect Samples

Show: Wipe Down (0.5 seconds), Hide: None

	'IEtrans': ['revealTrans(TRANSITION=5,DURATION=.5)', null]

Show: None, Hide Circle in (0.6 seconds)

	'IEtrans': [null, 'revealTrans(TRANSITION=2,DURATION=.6)']

Show: Circle out (0.5 seconds), Hide Circle in (0.6 seconds)

	'IEtrans': ['revealTrans(TRANSITION=3,DURATION=0.5)', 'revealTrans(TRANSITION=2,DURATION=.6)']

Show and Hide: Blending (0.5 seconds)

	'IEtrans': ['blendTrans(DURATION=.5)', 'blendTrans(DURATION=.5)']
or
	'IEtrans': ['blendTrans(DURATION=.5)']

Show and Hide: No effects

	'IEtrans': []
or
	'IEtrans': null

Hints List

Tigra Hints configuration is a JavaScript array containing the HTML code for individual hints. The hints can be ordered (with indexes starting from 0) or they can be provided with the text keys (key:hint pairs). The indexes or keys are used in the event hookups where the HTML fragments are linked to their activating elements.
Based on the HTML code provided in the Hits List the script will generate DHTML elements and absolutely position them in the document layers at the initialization time. Hints List is not required when pre-existing hints are used instead.

Below are some examples of the hint lists:

// numeric index based list of hints
var HINTS_ITEMS = [
	'short definition',
	'tooltip for item2 with some <b>HTML</b>',
	'tooltip for item3<br />This one is multi line',
	'tooltip for item4',
	'another sample tooltip with the <a href="http://www.softcomplex.com">link</a>'
];
// text keys based list of hints
var HINTS_ITEMS = {
	'short'   : 'short definition',
	'someHTML': 'tooltip for item2 with some <b>HTML</b>',
	'multi'   : 'tooltip for item3<br />This one is multi line',
	'short2'  : 'tooltip for item4',
	'linked'  : 'another sample tooltip with the <a href="http://www.softcomplex.com">link</a>'
};

JavaScript functions can be used to repeat HTML fragments in multiple hints. This makes the configuration faster to load and simpler to manage. For example following variable:

// using wrapper functions for repeating HTML fragments
var HINTS_ITEMS = [
	myWrap('picture1'),
	myWrap('picture2'),
	myWrap('picture3'),
	myWrap('picture4')
];

function myWrap (s_imgName) {
	return '<img src="/img/' + s_imgName + '.jpg" border="1" />';
}

is the equivalent of:

// using wrapper functions for repeating HTML fragments
var HINTS_ITEMS = [
	'<img src="/img/picture1.jpg" border="1" />',
	'<img src="/img/picture2.jpg" border="1" />',
	'<img src="/img/picture3.jpg" border="1" />',
	'<img src="/img/picture4.jpg" border="1" />'
];

Now if path to images needs to be changed then in first version it will require one change while in second - four changes. This technique makes even more sense with more complex HTML formatting including tables and graphics.

Notes:

Terms and Conditions

Tigra Hints ...

Links and References