View source for How to add tooltips to your Joomla! website

{{underconstruction}}
===Tooltips Overview===
A tooltips is a piece of text that pops up when you hover the mouse over a region on a website. If you use the Joomla! back end, for example, tooltips are used to help explain the action of different parameters, as shown in the screenshot below: 

[[Image:Screen_tooltip_example_20090208.png]]

Tooltips are a great way to give the user access to information without using up space on the screen. You can use basic tooltips just by adding a "title" attribute to a tag. However, this doesn't give you the option to style the tooltips. With Joomla! version 1.5, it is very easy to add styled tooltips to your site. This tutorial will show you how. <blockquote>''Note: If you are converting old code, make sure it doesn't use the prototype.js file.  That file will keep the tooltips from working.''</blockquote>

===Activate Tooltip Behavior===
To start, you must activate the tooltip behavior.  This is done with the following line of code:
<source lang="php">
JHTML::_('behavior.tooltip');
</source>
Note that you only put this line in once per file. A good place is right after the <code>defined('_JEXEC') or die('Restricted access');</code> line. If you are curious about what this line does, it inserts the following JavaScript code in the heading of the HTML page:
<source lang="html4strict">
<script type="text/javascript">
    window.addEvent('domready', function(){ 
       var JTooltips = new Tips($$('.hasTip'), 
       { maxTitleChars: 50, fixed: false}); 
    });
</script>
</source>
This allows tooltips to function, as outlined below.

===Create a Tooltip with the JHTML::tooltip Method===
One way to create a tooltip is using the JHTML::tooltip method. The API documentation is available at [http://api.joomla.org/Joomla-Framework/HTML/JHTML.html#tooltip http://api.joomla.org/Joomla-Framework/HTML/JHTML.html#tooltip]. The method definition is shown below.  
<source lang="php">
void tooltip (string $tooltip, [string $title = ''], [string $image = 'tooltip.png'], 
              [string $text = ''], [string $href = ''], [boolean $link = 1])
</source>
The brackets mean the parameter is optional. The first parameter, "$tooltip", is the only required parameter. The equals specifies the default if you do not pass that parameter. For example, the image file 'tooltip.png' is the default image.

The following is a basic tooltip.  Keep in mind that the image variable must be in reference to 'includes/js/ThemeOffice'.  Use the prefix '../../../' to reference from the root of the Joomla installation.
<source lang="php">
JHTML::tooltip('This is the tooltip text', 'Tooltip title', 'tooltip.png', '', 
               'http://www.joomla.org');
</source>
The above will make a tooltip using the default "tooltip.png" image, as shown below.  

[[Image:Tooltip_tutorial_example_screenshot_20090208.png|center|frame]]

Clicking the image will take you to <tt>http://www.joola.org</tt>, since that is the "$href" argument.

This code is almost the same as above except the image will not be a link (because the "$href" argument is omitted).
<source lang="php">
JHTML::tooltip('This is the tooltip text', 'Tooltip title', 
               'tooltip.png', '', '', false);
</source>

A tooltip can be attached to an image or to text. For example, this code 
<source lang="php">
echo JHTML::tooltip('This is a tooltip attached to text', 'Text Tooltip Title', 
	            '', 'Hover on this text to see the tooltip');
</source>
will show a tooltip attached to text, as shown below.

[[Image:Tooltip_tutorial_example_screenshot2_20090208.png|center|frame]]

Note that specifying the "$text" parameter will override any image you have passed to tooltip.

===Create a Tooltip Using a CSS Class Name===
If we look at the HTML page source generated by the <code>JHTML::tooltip</code> function above, here is what we see:
<source lang="html4strict">
<span class="editlinktip hasTip" title="Text Tooltip Title::This is a tooltip attached to text" 
      style="text-decoration: none; color: #333;">Hover on this text to see the tooltip</span>
</source>
This function generates an HTML "span" tag with the classes "editlinktip" and "hasTip" and an attribute called "title". Notice that the the "title" attribute has two parts, <code><tooltip title>::<tooltip text></code> (for example, "Tooltip Title::This is the tooltip text"). You can create a tooltip with only text or with only a title. The title has implications for styling, as we'll see below.

The Javascript inserted by the <code>JHTML::('behavior_tooltip')</code> command we entered earlier picks up this tag based on the class called "hasTip". So, a second way of creating a tooltip is to simply create a tag with a class called "hasTip" and an attribute of "title". For example, this code
<source lang="html4strict">
<span class="hasTip" title="Text Tooltip Title::This is a tooltip attached to text">
   Hover on this text to see the tooltip</span>
</source>
will produce exactly the same effect as the <code>JHTML::tootip()</code> example above. 

===Adding CSS Styling to the Tooltip===
The default toottips, whether using the JHTML::tooltip method or class method, use the following three CSS classes: <tt>.tool-tip</tt>, <tt>.tool-title</tt>, and <tt>.tool-text</tt>.

Here are the default styles.
<source lang="css">
/* Tooltips */
.tool-tip {
   float: left;
   background: #ffc;
   border: 1px solid #D4D5AA;
   padding: 5px;
   max-width: 200px;
}

.tool-title {
   padding: 0;
   margin: 0;
   font-size: 100%;
   font-weight: bold;
   margin-top: -15px;
   padding-top: 15px;
   padding-bottom: 5px;
   background: url(../images/selector-arrow.png) no-repeat;
}

.tool-text {
   font-size: 100%;
   margin: 0;
}
</source>

If you have a custom CSS file, copy this code and alter it to your liking. Note that the <tt>.tool-title</tt> class uses by default the "selector-arrow.png" image. This is what gives the outline of the tooltip the little pointer in the upper left of the tooltip box. If you leave out a title in your tooltip, you will just get a rectangle, without the pointer.

===Customizing Your Yooltips===

Ok, time to get down and dirty.  This is based on the mootools demo.  We are going to make our own tip definitions that include a very cool fade in and out.  First create a JavaScript file or simply put this code directly into your code.  Pick a name for the class to use.  I used "zoomTip".
<source lang="javascript">
window.addEvent('domready', function(){
   //do your tips stuff in here...
   var zoomTip = new Tips($$('.zoomTip'), {
      className: 'custom', //this is the prefix for the CSS class
      initialize:function(){
         this.fx = new Fx.Style(this.toolTip, 'opacity', {duration: 500, wait: false}).set(0);
      },
      onShow: function(toolTip) {
         this.fx.start(1);
      },
      onHide: function(toolTip) {
         this.fx.start(0);
      }
   });
});
</source>


I'm only going to cover one line of that code here.  Please look over the mootools library for more information.  I read in their forum that their slider library is not compatible with the tooltips.  The 4th line is the prefix for the CSS classes that will be used.  In this example the classes will be the following: <tt>.custom-tip</tt>, <tt>.custom-title</tt>, and <tt>.custom-text</tt>.

Here is some example CSS straight from the mootools demo.
<source lang="css">
.custom-tip {
   color: #000;
   width: 130px;
   z-index: 13000;
}

.custom-title {
   font-weight: bold;
   font-size: 11px;
   margin: 0;
   color: #3E4F14;
   padding: 8px 8px 4px;
   background: #C3DF7D;
   border-bottom: 1px solid #B5CF74;
}

.custom-text {
   font-size: 11px;
   padding: 4px 8px 8px;
   background: #CFDFA7;
}
</source>


Notice that .custom-title does not have a background property.  This tool tip will be a box without the neat little arrow pointing at the mouse.  If you wanted to change the colors in the box and use the arrows you would have to alter the image to have the color you want and add that property into your .custom-title CSS.  Now you must create the items using the class method and not using JHTML::tooltip.  JHTML::tooltip applies the classes "editlinktip" and "hasTip".  I have not seen any way to easily alter that.  The code below will create a tip using this new js code.
<source lang="html4strict">
<span class="zoomTip" title="My Tooltip Title :: Here is my tip's text">Mootools.net</span>
</source>
Notice the only difference from the previous example using a span is the class name.

===More Information===
* Joomla API - [http://api.joomla.org http://api.joomla.org]
* Mootools Website - [http://www.mootools.net/ http://www.mootools.net/]
* Mootools demos - [http://demos.mootools.net/ http://demos.mootools.net/]

[[Category:Development]]