<?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>
    <title>Creating the Component with a Page Tag</title>
    <para>To create the simplest variant of <property>toolTip</property> 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>
<property>toolTip</property> main area is a simple rectangle area with any information inside. The content may be defined via
<emphasis><property>&quot;value&quot;</property></emphasis> attribute as text or via any nested content. When both are defined, the value is displayed as text and nested content
after the text. <property>toolTip</property> stretches if the content more than the <property>toolTip</property> sizes.
</para>
<para>
There is possibility to define a facet with the name &quot;defaultContent&quot;. This facet provides the default content to
display while the main content is loaded to a page in an Ajax mode. Thus when <property>toolTip</property> 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.
</para>
<para>
	Here is an example: 
</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 <property>toolTip</property> 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>
  <note>
    <title>Note:</title>
    <para>
      If you define the <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> attached as the child to some componetns 
      and except <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> there are some other components inside 
      it is recommended to define <emphasis role="bold"><property>&lt;rich:toolTip&gt;</property></emphasis> in code as last component.
    </para>
  </note>
<para>
By default, <property>toolTip</property> 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's possible to define vertical and horizontal
offsets relatively to a mouse position. 
</para>
<para>
<property>toolTip</property> appears attached to the corner dependent on the <emphasis><property>&quot;direction&quot;</property></emphasis> attribute. By default it is positioned bottom-right.
<property>toolTip</property> activation occurs after a defined event (default=mouseover) on the parent component takes into consideration
the &quot;delay&quot; attribute (default=0) or after calling JS API function show(). <property>toolTip</property> deactivation occurs after mouseout event on the parent component (excepting the situation when the mouse is hovered onto the <property>toolTip</property> itself) or after calling JS API function hide().
</para>

<note>
<title>Note:</title> <para>
  It is recommended to define parent component  <emphasis><property>&quot;id&quot;</property></emphasis> for correction of <property>toolTip</property> work.
</para>
</note>

  <para>The attribute <emphasis><property>&quot;for&quot;</property></emphasis>   is used for defining the <emphasis><property>&quot;id&quot;</property></emphasis> of an element a toolTip should be attached to. Look at the example:
</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>Here, the attribute <emphasis><property>&quot;for&quot;</property></emphasis> of a <emphasis role="bold">
    <property>&lt;rich:toolTip&gt;</property>
  </emphasis> component is required. Without it an example doesn&apos;t work because HTML elements aren't presented in component tree built by facelets.
  </para>
  
<para>
The <emphasis><property>&quot;mode&quot;</property></emphasis> attribute is provided you to control the way of data loading to <property>toolTip</property>. It has following values:
    <itemizedlist>
		<listitem><para>Client</para></listitem>
		<listitem><para>Ajax</para></listitem>
	</itemizedlist>  
</para>
<para>
In a client mode, <property>toolTip</property> content is rendered once on the server and could be reRendered only via external submit.
In an Ajax mode, <property>toolTip</property> content is requested from server every activation.
</para>
<para>
Disabled <property>toolTip</property> is rendered to a page as usual but JS that responds for its activation is
disabled until enable() is called.
</para>
<para>
Moreover, to add  some JavaScript effects, client events defined on it are used:
</para>
<para>
    Standart:
    <itemizedlist>
		<listitem><para>onclick</para></listitem>
		<listitem><para>ondblclick</para></listitem>
		<listitem><para>onmouseout</para></listitem>
		<listitem><para>onmousemove</para></listitem>
		<listitem><para>onmouseover</para></listitem>
    </itemizedlist>  
</para>	
<para>
    Special:
    <itemizedlist>
		<listitem><para>onshow - Called after the toolTip is called (some element hovered) but before its request
		</para></listitem>
		<listitem><para>oncomplete - Called just after the toolTip is shown
		</para></listitem>
		<listitem><para>onhide - Called after the toolTip is hidden
		</para></listitem>
    </itemizedlist> 
</para>
</section>
  
  <section>
    <title>JavaScript API</title>
    <table>
      <title>JavaScript API</title>
      
      <tgroup cols="2">
        <thead>
          <row>
            <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><property>&lt;span&gt;</property></emphasis> or <emphasis><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’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’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  tool tip 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>
  