toolTip rich:toolTip HtmltoolTip

Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.component.toolTip
component-class | org.richfaces.component.html.HtmltoolTip
component-family | org.richfaces.component.toolTip
renderer-type | org.richfaces.renderkit.html.toolTipRenderer
tag-class | org.richfaces.taglib.HtmltoolTipTag

## Creating the Component with a Page Tag

To create the simplest variant of toolTip on a page, use the following syntax:

Example:

    ...
    <h:commandButton value="Button">
    	<rich:toolTip value="toolTip content"/>
    </h:commandButton>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmltoolTip;
    ...
    HtmltoolTip mytoolTip = new  HtmltoolTip();
    ...

## Details of Usage

toolTip main area is a simple rectangle area with any information inside. The content may be defined via "value" attribute as text or via any nested content. When both are defined, the value is displayed as text and nested content after the text. toolTip stretches if the content more than the toolTip sizes.

There is possibility to define a facet with the name "defaultContent". This facet provides the default content to display while the main content is loaded to a page in an Ajax mode. Thus when toolTip called in an Ajax mode, it appears with the content defined in the facet and when loading is completed, the content is changed to a loaded one.

Here is an example:

Example:

    ...
    <h:commandLink value="Simple Link">
    	<rich:toolTip followMouse="true" direction="top-right" mode="ajax" value="#{bean.toolTipContent}" horizontalOffset="5"
    		verticalOffset="5" layout="block">
    		<f:facet name="defaultContent">
    			<f:verbatim>DEFAULT toolTip CONTENT</f:verbatim>
    		</f:facet>
    	</rich:toolTip>
    </h:commandLink>
    ...

This is the result:

toolTip component with default content

And after toolTip loaded it will be changed to next one:

toolTip component with loaded content

By default, toolTip appears smart positioned. But as you can see from the previous example, you can define an appearance direction via the corresponding attribute "direction". And also it's possible to define vertical and horizontal offsets relatively to a mouse position.

toolTip appears attached to the corner dependent on the "direction" attribute. By default it is positioned bottom-right. toolTip activation occurs after a defined event (default=mouseover) on the parent component takes into consideration the "delay" attribute (default=0) or after calling JS API function Show(). toolTip deactivation occurs after mouseout event on the parent component (excepting the situation when the mouse is hovered onto the toolTip itself) or after calling JS API function Hide().

Note:

It is recommended to define parent component "id" for correction of toolTip work.

The attribute "for" is used for defining the "id" of an element a toolTip should be attached to. Look at the example:

Example:

    ...
    <div id="elementId">
          <rich:toolTip for="elementId">Using a toolTip<rich:toolTip>
           <p>The first simple example<p>
    </div>
    ...
    <div id="elementId">
            <p>The second simple example<p>
    </div>
    <rich:toolTip for="elementId">Using a toolTip<rich:toolTip>
    ...

Here, the attribute "for" of a <rich:toolTip> component is required. Whithout it an example doesn’t work because HTML elements aren't presented in component tree built by facelets.

The "mode" attribute is provided you to control the way of data loading to toolTip. It has following values:

- Client
- Ajax

In a client mode, toolTip content is rendered once on the server and could be reRendered only via external submit. In an Ajax mode, toolTip content is requested from server every activation.

Disabled toolTip is rendered to a page as usual but JS that responds for its activation is disabled until Enable() is called.

Moreover, to add some JavaScript effects, client events defined on it are used:

Standart:

- onclick
- ondblclick
- onmouseout
- onmousemove
- onmouseover

Special:

- onshow - Called after the toolTip is called (some element hovered) but before its request
- oncomplete - Called just after the toolTip is shown
- onhide - Called after the toolTip is hidden

## JavaScript API

JavaScript API

Function | Description
--- | ---
Show() | Shows the corresponding toolTip
Hide() | Hides the corresponding toolTip
Enable() | Enables the corresponding toolTip
Disable() | Disables the corresponding toolTip

## Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:toolTip> components at once:

- Redefine the corresponding skin parameters

- Add to your style sheets style classes used by a <rich:toolTip> component

## Skin Parameters Redefinition

Skin parameters redefinition for a component

Skin parameters | CSS properties
--- | ---
tipBackgroundColor | background-color
tipBorderColor | border-color
generalSizeFont | font-size
generalFamilyFont | font-family
generalFontColor | color

## Definition of Custom Style Classes

Classes names that define a component appearance

Class name | Description
--- | ---
rich-tool-tip | Defines styles for a wrapper <span> or <div> element of a toolTip

It depends on <rich:toolTip> layout what a wrapper element <span> or <div>to choose.

In order to redefine styles for all <rich:toolTip> components on a page using CSS, it's enough to create class with the same name and define necessary properties in it.

To change styles of particular <rich:toolTip> components define your own style class in the corresponding <rich:toolTip> attributes

## Relevant Resources Links

Here you can see the example of <rich:toolTip> usage and sources for the given example.