<section role="NotInToc" id="rich_effect">
   <title>
         &lt;rich:effect&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:effect&gt;</property></emphasis> utilizes a set of effects provided by the Scriptaculous JavaScript library. 
                  It allows to attach effects to JSF components and HTML tags.
            </para>
      </section>
      
      <section>
            <title>Key Features</title>
            <itemizedlist>
                  <listitem>
                        <para>Represents Scriptaculous JavaScript library functionality</para>
                  </listitem>
                  <listitem>
                        <para>No JavaScript needed to the component</para>
                  </listitem>
            </itemizedlist>
      </section>
      
      <section>
            <title>Details of Usage</title>
            <para>
                  It is possible to use <emphasis role="bold"><property>&lt;rich:effect&gt;</property></emphasis> in two modes: 
            </para>
            <itemizedlist>
                  <listitem>
                        <para>
                              attached to a JSF component or HTML tag and triggered by a particular event.
                              Wiring effect with JSF components might occur on the server or client. 
                              Wiring with html tag is possible only on the client side.
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              invoking from the JavaScript code by an effect name. 
                              During the rendering, <emphasis role="bold"><property>&lt;rich:effect&gt;</property></emphasis> generates the JavaScript function with defined name. 
                              When the function is called, the effect is applied
                        </para>
                  </listitem>
            </itemizedlist>
               
            <para>
                  <emphasis role="bold">Those a the typical variants of using:</emphasis>
            </para>
            <programlisting role="XML"><![CDATA[<!-- triggered by an event  -->
<rich:panel>
	<rich:effect event="onmouseout" type="Opacity" params="duration:0.8,from:1.0,to:0.3" />
    ...
</rich:panel>

<!--  invoking by JavaScript -->
<div id="contentDiv">...</div>
<input type="button" onclick="hideDiv({duration:0.7})" value="Hide" />
<input type="button" onclick="showDiv()" value="Show" />
<rich:effect  name="hideDiv"  for="contentDiv" type="Fade" />
<rich:effect  name="showDiv"  for="contentDiv" type="Appear" />

<!-- attached to a window onload event and applied to a particular page element -->
<rich:effect for="window" event="onload" type="Appear" params="targetId:'contentDiv',duration:0.8,from:0.3,to:1.0" />]]></programlisting>

      <figure>
            <title>Initial</title>
            <mediaobject>
                  <imageobject>
                        <imagedata fileref="images/effect_init.png"/>
                  </imageobject>
            </mediaobject>
      </figure>
            <figure>
                  <title>When the mouse cursor is over</title>
                  <mediaobject>
                        <imageobject>
                              <imagedata fileref="images/effect_2.png"/>
                        </imageobject>
                  </mediaobject>
            </figure>

      <para>
            The <emphasis><property>&quot;name&quot;</property></emphasis> attribute defines a name of the JavaScript function that will be generated on a page after the component is rendered. 
            This function will activate the needed effect. 
            The function accesses one parameter. 
            It is a set of effect options in JSON format. </para>

      <para>
            The <emphasis><property>&quot;type&quot;</property></emphasis> attribute defines the type of an effect that will be applied. 
            Possible values are <code>Fade</code>, <code>Blind</code>, <code>Opacity</code>. 
      </para>

      <para>
            The <emphasis><property>&quot;for&quot;</property></emphasis> attribute defines the ID of the component or HTML tag, the effect is attached to. 
            RichFaces converts value of <emphasis><property>&quot;for&quot;</property></emphasis> attribute to a component client ID if such component is found. 
            In case if such component is not found the value is left because of possible wirings with some DOM element id on the client side. 
            By default, the target of the effect is the same element that effect is pointed to. 
            Тarget element can be redefined with the <emphasis><property>&quot;targetId&quot;</property></emphasis> attribute;
            new parameters should be passed with the <emphasis><property>&quot;params&quot;</property></emphasis> attribute.
      </para>

      <para>
            The <emphasis><property>&quot;params&quot;</property></emphasis> attribute allows to define a set of options (<code>duration</code>, <code>delay</code>, <code>from</code>, <code>to</code>) possible for a particurar effect. 
            Additionally to the options used by the effect itself, there are two option that might override the <emphasis role="bold"><property>&lt;rich:effect&gt;</property></emphasis>attribute: 
            <itemizedlist>
                  <listitem>
                        <para>
                              <emphasis><property>&quot;targetId&quot;</property></emphasis> allows to re-define the target of effect. 
                              The option is override the value of <emphasis><property>&quot;for&quot;</property></emphasis> attribute.
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              <emphasis><property>&quot;type&quot;</property></emphasis> defines the effect type. 
                              The option is override the value of <emphasis><property>&quot;type&quot;</property></emphasis> attribute.
                        </para>
                  </listitem>
            </itemizedlist>
      </para>

      <para>
            Besides all you can load the Scriptaculous library to the page and use it directly without <emphasis role="bold"><property>&lt;rich:effect&gt;</property></emphasis>:
      </para>
            <programlisting role="XML"><![CDATA[<a4j:loadScript src="resource://scriptaculous/effect.js" />]]></programlisting>
      <para>
            But if you use the <emphasis role="bold"><property>&lt;rich:effect&gt;</property></emphasis> there is no need to include this library because it's already there.
      </para>
      </section>
      
      <section>
            <title>Reference Data</title>
            <para>
                  <ulink url="&tlddoc;rich/effect.html">Table of &lt;rich:effect&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.Effect</entry>
                        </row>
                        <row>
                              <entry>component-class</entry>
                              <entry>org.richfaces.component.html.HtmlEffect</entry>
                        </row>
                        <row>
                              <entry>component-family</entry>
                              <entry>org.richfaces.Effect</entry>
                        </row>
                        <row>
                              <entry>renderer-type</entry>
                              <entry>org.richfaces.EffectRenderer</entry>
                        </row>
                        <row>
                              <entry>tag-class</entry>
                              <entry>org.richfaces.taglib.EffectTag</entry>
                        </row>
                  </tbody>
            </tgroup>
      </table>
      </section>
      
      <section>
      <title>Relevant Resources Links</title>
      <para>
            Visit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/effect.jsf?c=effect">Effect page</ulink> at RichFaces LiveDemo for examples of component usage and their sources.
      </para>
            <para>Useful articels:</para>
             
            <itemizedlist>
                  <listitem>
                        <para>
                              &quot;<ulink url="http://www.jboss.org/community/wiki/CreateABannerUsingEffectsAndPoll">Create a banner using effects and poll</ulink>&quot; and 
                              &quot;<ulink url="http://wiki.jboss.org/auth/wiki/CreateAHTMLBannerUsingEffectsAndPoll">Create a HTML banner using effects and poll</ulink>&quot; at RichFaces wiki contains sorces for creating an image and HTML banners;
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              &quot;<ulink url="http://wiki.jboss.org/auth/wiki/RichFacesCookbook/SlideShow">Slideshow</ulink>&quot; article at RichFaces Cookbook describes 
                              how to make a slideshow with help of the <emphasis role="bold"><property>&lt;rich:effect&gt;</property></emphasis> and <emphasis role="bold"><property>&lt;a4j:poll&gt;</property></emphasis> components;
                        </para>
                  </listitem>
            </itemizedlist>
            <para>
                  Look at Scriptaculous <ulink url="http://script.aculo.us">documentation</ulink> for set of available effect.
            </para>
            <para>
                  Find more information about the compinent at <ulink url="http://jboss.com/index.html?module=bb&amp;op=viewtopic&amp;t=119044">RichFaces Users Forum</ulink>.
            </para>
      </section>
      
</section>
