<?xml version='1.0' encoding='UTF-8'?>
<section>
<sectioninfo>
<keywordset>
<keyword>toolTip</keyword>
<keyword>rich:toolTip</keyword>
<keyword>HtmltoolTip</keyword>
</keywordset>
</sectioninfo>
    <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>

  <section id="tab_ccpt">
    <title>Creating the Component with a Page Tag</title>
    <para>The simplest way to create the <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> component on a page is as following:</para>
 
    <programlisting role="XML"><![CDATA[...
<rich:panel>
	<rich:toolTip value="Hello, I am the content of this tooltip!"/>
</rich:panel>
...
]]></programlisting>
</section>
  
<section>
  <title>Creating the Component Dynamically Using Java</title>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
  <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmltoolTip;
...
HtmltoolTip mytoolTip = new  HtmltoolTip();
...
]]></programlisting>
</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>&quot;value&quot;</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>&quot;attached&quot;</property></emphasis> attribute is &quot;true&quot; 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>&quot;for&quot;</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>&quot;for&quot;</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>&quot;attached&quot;</property></emphasis> attribute should be set to &quot;false&quot; 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>&quot;id&apos;s&quot;</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>&quot;mode&quot;</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>&quot;defaultContent&quot;</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>&quot;direction&quot;</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 &quot;delay&quot; attribute 
     or after calling JS API function <code>show()</code>. 
     <emphasis><property>&quot;hideEvent&quot;</property></emphasis> attribute defines the way 
     how <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> disappears. 
     It default value is &quot;none&quot;, 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>&quot;direction&quot;</property></emphasis>. 
     And also it&apos;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>&quot;onclick&quot;</property></emphasis></para></listitem>
       <listitem><para><emphasis><property>&quot;ondblclick&quot;</property></emphasis></para></listitem>
       <listitem><para><emphasis><property>&quot;onmouseout&quot;</property></emphasis></para></listitem>
       <listitem><para><emphasis><property>&quot;onmousemove&quot;</property></emphasis></para></listitem>
       <listitem><para><emphasis><property>&quot;onmouseover&quot;</property></emphasis></para></listitem>
     </itemizedlist>
   </para>
   <para>
     Special:
     <itemizedlist>
       <listitem><para><emphasis><property>&quot;onshow&quot;</property></emphasis> - Called after the tooltip is called (some element hovered) but before its request</para></listitem>
       <listitem><para><emphasis><property>&quot;oncomplete&quot;</property></emphasis> - Called just after the tooltip is shown</para></listitem>
       <listitem><para><emphasis><property>&quot;onhide&quot;</property></emphasis> - Called after the tooltip is hidden</para></listitem>
     </itemizedlist>
   </para>
 </section>
  
  <section id="tab_jsapi">
  <title>JavaScript API</title>
  <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>
    
  </section>

  <section>
		<title>Facets</title>
		<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 = &quot;ajax&quot;</entry>
						</row>
					</tbody>
				</tgroup>
		</table>
	</section>
  
 <section>
 <title>Look-and-Feel Customization</title>
   
   <para>For skinnability implementation, the components use a <emphasis>
     <property>style class redefinition method.</property>
   </emphasis> Default style classes are mapped on <emphasis>
     <property>skin parameters.</property>
   </emphasis></para>
   
   <para>There are two ways to redefine the appearance of all <emphasis role="bold">
     <property>&lt;rich:toolTip&gt;</property>
   </emphasis> components at once:</para>
   
   <itemizedlist>
     <listitem>
       <para>Redefine the corresponding skin parameters</para>
     </listitem>
     
     <listitem>
       <para>Add to your style sheets <emphasis>
         <property>style classes</property>
       </emphasis> used by a <emphasis role="bold">
         <property>&lt;rich:toolTip&gt;</property>
       </emphasis> component</para>
     </listitem>
   </itemizedlist>
	   
 </section>
  <section>
    <title>Skin Parameters Redefinition</title>
    <table>
      <title>Skin parameters redefinition for a component</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>tipBackgroundColor</entry>
            <entry>background-color</entry>
          </row>
          <row>
            <entry>tipBorderColor</entry>
            <entry>border-color</entry>
          </row>
          <row>
            <entry>generalSizeFont</entry>
            <entry>font-size</entry>
          </row>
          <row>
            <entry>generalFamilyFont</entry>
            <entry>font-family</entry>
          </row>
          <row>
            <entry>generalFontColor</entry>
            <entry>color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>		 
	
</section>

	
 <section>
	 <title>Definition of Custom Style Classes</title>
   <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>
   
   <para>
     It depends on <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> layout what a wrapper element <emphasis role="bold"><property>&lt;span&gt;</property></emphasis> or <emphasis role="bold"><property>&lt;div&gt;</property></emphasis>to choose.
   </para>
   <para>In order to redefine styles for all <emphasis role="bold">
     <property>&lt;rich:toolTip&gt;</property>
   </emphasis> components on a page using CSS, it&apos;s enough to create classes with the
     same names (possible classes could be found in the table <link linkend="tab_cn6">above</link>) and define necessary properties in them. An example is placed below:</para>
   
   <para>
     <emphasis role="bold">Example:</emphasis>
   </para>
   <programlisting role="CSS"><![CDATA[...
.rich-tool-tip{
    background-color: #eef2f8;
    border-color: #7196c8;
    
}
...]]></programlisting>  
   
   <para>This is a result:</para>
   
   <figure>
     <title>Redefinition styles with predefined classes</title>
     <mediaobject>
       <imageobject>
         <imagedata fileref="images/toolTip_pc.png"/>
       </imageobject>
     </mediaobject>
   </figure>
   
   <para>In the example a tool tip background color, border color and font style  were changed.</para>
   <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
     ><property>&lt;rich:toolTip&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
       ><property>&lt;rich:toolTip&gt;</property></emphasis> <emphasis><property>styleClass</property></emphasis> attributes. An example is placed below:</para>
  
   <para>
     <emphasis role="bold">Example:</emphasis>
   </para>
   <programlisting role="CSS"><![CDATA[...
.myClass{
     font-style: italic;
}
...]]></programlisting>  
   <para>The <emphasis><property>&quot;styleClass&quot;</property></emphasis> attribute for <emphasis role="bold"
     ><property>&lt;rich:toolTip&gt; </property></emphasis> is defined as it&apos;s shown in the example below:</para>
   
   <para>
     <emphasis role="bold">Example:</emphasis>
   </para>
   <programlisting role="XML"><![CDATA[<rich:toolTip ... styleClass="myClass"/>
]]></programlisting>    
   
   <para>This is a result:</para>
   
   <figure>
     <title>Redefinition styles with own classes and <emphasis><property>styleClass</property></emphasis> attributes</title>
     <mediaobject>
       <imageobject>
         <imagedata fileref="images/toolTip_oc.png"/>
       </imageobject>
     </mediaobject>
   </figure>  
   
   <para>As it could be seen on the picture above, background color and border color of  <property>tool tip</property> were changed.</para>      
</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>
  