<?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>To create the simplest variant of <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> 
      component on a page, use the following syntax:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<rich:panel>
	<rich:toolTip value="toolTip content"/>
</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>
             To specify text information, labeled on a <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis>, use <emphasis><property>&quot;value&quot;</property></emphasis> attribute. 
              Images, links, buttons and other RichFaces components also may be put and composed inside <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis>. 
             Text, specified between <property>tooltip&apos;s</property> start and end tags will be rendered in browser as simple text. 
              <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> borders stretch to enclose it contents.
   </para>
   <para>
             There are three ways to attach a <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> to a page element. 
             One of them uses nesting (this way is shown on example <link linkend="tab_ccpt">above</link>). 
             In such cases <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> is attached to the parent component by default.
   </para>
   <note>
     <title>Note:</title>
     <para>
                  It is recommended to specify <emphasis><property>&quot;id&quot;</property></emphasis> for parent page element to ensure <property>tooltip&apos;s</property> correct work.
     </para>
   </note>
   <note>
     <title>Note:</title>
     <para>
                  If parent component contains more than one child, it is recommended to define <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> as the last one.
     </para>
   </note>
   <para>
             <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> may be attached to a page element by the use of <emphasis><property>&quot;for&quot;</property></emphasis> attribute. In this case a <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> may be defined separately from a page element it is applied to. 
             <emphasis><property>&quot;id&quot;</property></emphasis> for page element is necessary (see the example below).
   </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 content" for="panelId"/>
...
]]></programlisting>
   <para>
     Because HTML elements are not presented in components tree built by facelets, 
     use the attribute <emphasis><property>&quot;for&quot;</property></emphasis> with HTML elements as shown in example below.
   </para>
   <para>
     <emphasis role="bold">Example:</emphasis>
   </para>
   <programlisting role="XML"><![CDATA[...
<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>
...
]]></programlisting>
   <para>
     <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> may also be invoked by 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 page element, the <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> is applied to. Thus, <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> can be defined separately from that page element. 
     It is necessary to specify <emphasis><property>&quot;ids&quot;</property></emphasis> for both and set <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> <emphasis><property>&quot;attached&quot;</property></emphasis> attribute&apos;s value to &quot;false&quot; (see the example below). 
   </para>
   <programlisting role="XML"><![CDATA[...
<rich:panel id="paneld" onclick="#{rich:component("tooltipId")}.show();">
...
</rich:panel>
<rich:toolTip id="tooltipId" attached="false" value="This is a tooltip content"/>
...
]]></programlisting>
   <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>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:toolTipl&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:toolTipl&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"
      >Here</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>
  