<?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[...
<h:commandButton value="Button">
	<rich:tooltip value="Tooltip content"/>
</h:commandButton>
...
]]></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
&quot;value&quot; 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">
	<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>Tooltip component with default content</title>
      <mediaobject> 
        <imageobject>
            <imagedata fileref="images/tooltip2.png"/>
        </imageobject>
    </mediaobject>
    </figure>
<para>
And after <property>tooltip</property> loaded it will be changed to next one:
</para>
    <figure>
        <title>Tooltip component with loaded content</title>
      <mediaobject> 
        <imageobject>
            <imagedata fileref="images/tooltip3.png"/>
        </imageobject>
    </mediaobject>
    </figure>
<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 &quot;direction&quot;. 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 doShow(). <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 doHide().
</para>

<note>
<title>Note:</title> 
It is recommended to define parent component "id" for correction of <property>tooltip</property> work.
</note>

<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>Client</listitem>
		<listitem>Ajax</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>
Special JS API is provided to control the component behaviour:
    <itemizedlist>
		<listitem>doShow() - Shows the corresponding tooltip</listitem>
		<listitem>doHide() - Hides the corresponding tooltip</listitem>
		<listitem>doEnable() - Enables the corresponding tooltip</listitem>
		<listitem>doDisable() - Disables the corresponding tooltip</listitem>
	</itemizedlist>
</para>
<para>
Disabled <property>tooltip</property> is rendered to a page as usual but JS that responds for its activation is
disabled until doEnable() is called.
</para>
<para>
Moreover, to add  some JavaScript effects, client events defined on it are used:
</para>
<para>
    Standart:
    <itemizedlist>
		<listitem>onclick</listitem>
		<listitem>ondblclick</listitem>
		<listitem>onmouseout</listitem>
		<listitem>onmousemove</listitem>
		<listitem>onmouseover</listitem>
    </itemizedlist>  
</para>	
<para>
    Special:
    <itemizedlist>
		<listitem>onshow - Called after the tooltip is called (some element hovered) but before its request
		</listitem>
		<listitem>oncomplete - Called just after the tooltip is shown
		</listitem>
		<listitem>onhide - Called after the tooltip is hidden
		</listitem>
    </itemizedlist> 
</para>
</section>

 <section>
 <title>Look-and-Feel Customization</title>
	<para>For skinnability implementation the components, use a <emphasis><property>style class redefinition method</property></emphasis>.
	</para>
	<para>Default style classes are mapped on <emphasis><property>skin parameters</property>.</emphasis></para>

	<para>To redefine appearance of all <property>tooltip</property> at once, there are two ways:</para>
        <itemizedlist>
			<listitem>to redefine the corresponding skin parameters</listitem>
			<listitem>to add to your style sheets style classes used by a <property>tooltip</property></listitem>
         </itemizedlist>

	 <para>
    <table>
      <title>Skin parameters redefinition</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters for the tooltip component</entry>
            <entry>Corresponding CSS parameters</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>		 
	</para>
</section>

	
 <section>
	 <title>Definition of Custom Style Classes</title>
   <table>
     <title>Classes names that define a tooltip</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:tooltip&gt;</property>
   </emphasis> components on a page using CSS, it&apos;s enough to create class with the
     same name and define necessary properties in it.</para>
   
   <para>To change styles of particular <emphasis role="bold">
     <property>&lt;rich:tooltip&gt;</property>
   </emphasis> components define your own style class in the corresponding <emphasis
     role="bold">
     <property>&lt;rich:tooltip&gt;</property>
   </emphasis>attributes</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>
  