<section role="NotInToc" id="rich_toolTip">
   <title>
				&lt;
				rich:toolTip
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.1.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
      <title>Description</title>
      <para>The <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> component is used 
        for creation of event-triggered non modal popup, that contains information regarding the page element, that event was applied to. 
	</para>
      <figure>
        <title>
            <emphasis role="bold">
               <property>&lt;rich:toolTip&gt;</property>
            </emphasis> component</title>
         <mediaobject> 
            <imageobject>
               <imagedata fileref="images/toolTip_init.png"/>
            </imageobject>
         </mediaobject>
      </figure>
    </section>
   <section>
      <title>Key Features</title> 
      <itemizedlist>
		       <listitem>
            <para>Highly customizable look and feel </para>
         </listitem>
		       <listitem>
            <para>Different ways of data loading to toolTip</para>
         </listitem>
		       <listitem>
            <para>Disablement support</para>
         </listitem>
      </itemizedlist>  
   </section>
   <section>
      <title>Details of Usage</title>
      <para>
             Text information, labeled on the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis>, is specified with <emphasis>
            <property>"value"</property>
         </emphasis> attribute. 
         Text that is put between tooltip start and end tags will also be rendered as tooltip content and could be marked with HTML tags. 
         Images, links, buttons and other RichFaces components are also may be put and composed inside the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis>. 
         The <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> borders are stretched automatically to enclose the contents.
   </para>
      <para>
             There are three ways to attach the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> to a page element. 
         The first and simplest one is when the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> is nested into a page element the tooltip is applied to. 
         This way is shown on example in the <link linkend="tab_ccpt">Creating the Component with a Page Tag</link> section. 
         The <emphasis>
            <property>"attached"</property>
         </emphasis> attribute is "true" by default in this case,  
         which means that the tolltip will be invoked automatically when the mouse cursor is hovered above the parent component.         
   </para>
           
      <para>
         The second one uses <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> 
         <emphasis>
            <property>"for"</property>
         </emphasis> attribute. 
         In this case the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> is defined separately from a component it is applied to.
   </para>
       
      <para>
                <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="XML"><![CDATA[<rich:panel id="panelId">
...
</rich:panel>
<rich:toolTip value="This is a tooltip." for="panelId"/>]]></programlisting>
   
       <para>These two ways are also applicable for HTML elements that are not presented in components tree built by facelets.  
             Use <emphasis>
            <property>"for"</property>
         </emphasis> attribute to attach the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> in both cases.   
       </para>
      <para>
         <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="XML"><![CDATA[<!-- The <rich:toolTip> is nested into the parent HTML element -->
<div id="para1">
      <p>This paragraph and tooltip are nested into the same <div> element.</p>
      <rich:toolTip for="para1">This is a tooltip.</rich:toolTip>
</div>

<!-- The <rich:toolTip> is defined separately -->
<div id="para2">
      <p>The tooltip for this paragraph is defined separately.</p>
</div>
<rich:toolTip for="para2">This is a tooltip.</rich:toolTip>]]></programlisting>
       
      <para>The third way to invoke the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> uses JS API function.
     List of JS API functions available for <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> is listed <link linkend="tab_jsapi">below</link>.
     JS API functions are defined for a component the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> is applied to. 
         The <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> 
         <emphasis>
            <property>"attached"</property>
         </emphasis> attribute should be set to "false" in this case.         
   </para>
       <para>
             <emphasis role="bold">Example:</emphasis>
       </para>
      <programlisting role="XML"><![CDATA[<rich:panel id="panelId" onclick="#{rich:component("tooltipId")}.show(event);" />
<a4j:form>
      <rich:toolTip id="tooltipId" attached="false" value="This is a tooltip."/>
</a4j:form>]]></programlisting>
     
       <note>
             <title>Notes:</title>
             <para>To provide <emphasis role="bold">
               <property>&lt;rich:toolTip&gt;</property>
            </emphasis> component proper work in complex cases do the following:
                   <itemizedlist>
                         <listitem>
                  <para>specify <emphasis>
                        <property>"id's"</property>
                     </emphasis> for both <emphasis role="bold">
                        <property>&lt;rich:toolTip&gt;</property>
                     </emphasis> and component it is applied to;</para>
               </listitem>
                         <listitem>
                  <para>define the <emphasis role="bold">
                        <property>&lt;rich:toolTip&gt;</property>
                     </emphasis> as last child, when nesting it into the component the <emphasis role="bold">
                        <property>&lt;rich:toolTip&gt;</property>
                     </emphasis> is applied to;</para>
               </listitem>
                         <listitem>
                  <para>put the <emphasis role="bold">
                        <property>&lt;rich:toolTip&gt;</property>
                     </emphasis> into <emphasis role="bold">
                        <property>&lt;a4j:form&gt;</property>
                     </emphasis> when invoking it with JS API function.</para>
               </listitem>
                   </itemizedlist>
             </para>
       </note>
       
      <para>
     The <emphasis>
            <property>"mode"</property>
         </emphasis> attribute is provided you to control the way of data loading to <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis>.
     The component works properly in client and Ajax modes.
     In client mode <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> content is rendered once on the server and could be rerendered only via external submit. 
     In Ajax mode <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> content is requested from server for every activation. 
     For Ajax mode there is possibility to define a facet <emphasis>
            <property>"defaultContent"</property>
         </emphasis>, which provides default <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> content to be displayed, while main content is loading into the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> (see the example below).
   </para>
      <para>
         <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="XML"><![CDATA[...
<h:commandLink value="Simple Link" id="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>
...
]]></programlisting>
      <para>
     This is the result:
   </para>
   
      <figure>
         <title>
            <emphasis role="bold">
               <property>&lt;rich:toolTip&gt;</property>
            </emphasis> component with default content</title>
         <mediaobject>
            <imageobject>
               <imagedata fileref="images/toolTip2.png"/>
            </imageobject>
         </mediaobject>
      </figure>
   
      <para>
     And after <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> loaded it is changed to next one:
   </para>
   
      <figure>
         <title>
            <emphasis role="bold">
               <property>&lt;rich:toolTip&gt;</property>
            </emphasis> component with loaded content</title>
         <mediaobject>
            <imageobject>
               <imagedata fileref="images/toolTip3.png"/>
            </imageobject>
         </mediaobject>
      </figure>
   
      <para>
         <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> appears attached to the corner 
     dependent on the <emphasis>
            <property>"direction"</property>
         </emphasis> attribute. 
     By default it is positioned bottom-right. 
     <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> activation occurs after an event, 
     defined on the parent component, takes into consideration the "delay" attribute 
     or after calling JS API function <code>show()</code>. 
     <emphasis>
            <property>"hideEvent"</property>
         </emphasis> attribute defines the way 
     how <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> disappears. 
     It default value is "none", so the <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> does not disappears. 
     Deactivation may be set for example on <emphasis>
            <property>mouseout</property>
         </emphasis> event on the parent component 
     (excepting the situation when the mouse is hovered onto the 
     <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> itself) 
     or after calling JS API function <code>hide()</code>. 
     </para>
      <para>
     By default, <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> appears smart positioned. But as you can see from the previous example, you
     can define an appearance direction via the corresponding attribute <emphasis>
            <property>"direction"</property>
         </emphasis>. 
     And also it's possible to define vertical and horizontal offsets relatively to a mouse position. 
   </para>
      <para>
     Disabled <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> is rendered to a page as usual but JS that responds for its activation is disabled until <code>enable()</code> is called. 
   </para>
      <para>
     Moreover, to add  some JavaScript effects, client events defined on it are used:
   </para>
      <para>
     Standart:
     <itemizedlist>
            <listitem>
               <para>
                  <emphasis>
                     <property>"onclick"</property>
                  </emphasis>
               </para>
            </listitem>
            <listitem>
               <para>
                  <emphasis>
                     <property>"ondblclick"</property>
                  </emphasis>
               </para>
            </listitem>
            <listitem>
               <para>
                  <emphasis>
                     <property>"onmouseout"</property>
                  </emphasis>
               </para>
            </listitem>
            <listitem>
               <para>
                  <emphasis>
                     <property>"onmousemove"</property>
                  </emphasis>
               </para>
            </listitem>
            <listitem>
               <para>
                  <emphasis>
                     <property>"onmouseover"</property>
                  </emphasis>
               </para>
            </listitem>
         </itemizedlist>
      </para>
      <para>
     Special:
     <itemizedlist>
            <listitem>
               <para>
                  <emphasis>
                     <property>"onshow"</property>
                  </emphasis> - Called after the tooltip is called (some element hovered) but before its request</para>
            </listitem>
            <listitem>
               <para>
                  <emphasis>
                     <property>"oncomplete"</property>
                  </emphasis> - Called just after the tooltip is shown</para>
            </listitem>
            <listitem>
               <para>
                  <emphasis>
                     <property>"onhide"</property>
                  </emphasis> - Called after the tooltip is hidden</para>
            </listitem>
         </itemizedlist>
      </para>
   </section>
   <section>
      <title>Reference Data</title>
      <para>
         <ulink url="&tlddoc;rich/toolTip.html">Table of 
							&lt;rich:toolTip&gt; 
							 attributes</ulink>.
						</para>
      <table>
         <title>Component Identification Parameters </title>
         <tgroup cols="2">
            <thead>
               <row>
                  <entry>Name</entry>
                  <entry>Value</entry>
               </row>
            </thead>
            <tbody>
               <row>
                  <entry>component-type</entry>
                  <entry>org.richfaces.component.toolTip</entry>
               </row>
               <row>
                  <entry>component-class</entry>
                  <entry>org.richfaces.component.html.HtmlToolTip</entry>
               </row>
               <row>
                  <entry>component-family</entry>
                  <entry>org.richfaces.component.toolTip</entry>
               </row>
               <row>
                  <entry>renderer-type</entry>
                  <entry>org.richfaces.renderkit.html.toolTipRenderer</entry>
               </row>          
               <row>
                  <entry>tag-class</entry>
                  <entry>org.richfaces.taglib.HtmlToolTipTag</entry>
               </row>
            </tbody>
         </tgroup>
      </table>
      <table>
         <title>JavaScript API</title>
      
         <tgroup cols="2">
            <thead>
               <row>every acti
            <entry>Function</entry>
            
                  <entry>Description</entry>
               </row>
            </thead>
        
            <tbody>
          
               <row>
                  <entry>show()</entry>
            
                  <entry>Shows the corresponding toolTip</entry>
               </row>
          
               <row>
                  <entry>hide()</entry>
            
                  <entry>Hides the corresponding toolTip</entry>
               </row>
          
               <row>
                  <entry>enable()</entry>
            
                  <entry>Enables the corresponding toolTip</entry>
               </row>
          
               <row>
                  <entry>disable()</entry>
            
                  <entry>Disables the corresponding toolTip</entry>
               </row>
          
            </tbody>
         </tgroup>
      </table>
      <table>
			      <title>Facets</title>
				     <tgroup cols="2">
					       <thead>
						         <row>
							           <entry>Facet name</entry>
							           <entry>Description</entry>
						         </row>
					       </thead>
					       <tbody>
						         <row>
							           <entry>defaultContent</entry>
							           <entry>Defines the default content for toolTip. It is used only if mode = "ajax"</entry>
						         </row>
					       </tbody>
				     </tgroup>
		    </table>
      <table id="tab_cn6">
         <title>Classes names that define a component appearance</title>
         <tgroup cols="2">
            <thead>
               <row>
                  <entry>Class name</entry>
                  <entry>Description</entry>
               </row>
            </thead>
            <tbody>
               <row>
                  <entry>rich-tool-tip</entry>
                  <entry>Defines styles for a wrapper &lt;span&gt; or &lt;div&gt; element of a toolTip</entry>
               </row>
            </tbody>
         </tgroup>
      </table>
							You can find all necessary information about style classes redefinition in 
						<link linkend="customstyles">Definition of Custom Style Classes</link> 
							section.
						</section>
   <section>
      <title>Relevant Resources Links</title>
      <para>
         <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/toolTip.jsf?c=toolTip">On the component LiveDemo page</ulink> you can see the example of <emphasis role="bold">
            <property>&lt;rich:toolTip&gt;</property>
         </emphasis> usage and sources for the given example. </para>
  </section>
</section>
