<?xml version='1.0' encoding='UTF-8'?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>effect</keyword>
      <keyword>rich:effect</keyword>
      <keyword>HtmlEffect</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.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>
    <title>Creating the Component with a Page Tag</title>
    <para>To create the simplest variant of <emphasis role="bold"><property>&lt;rich:effect&gt;</property></emphasis> on a page, use the
      following syntax:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<rich:effect for="componentId" type="Appear"/>
...
]]></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.HtmlRichEffect;
...
HtmlRichEffect myEffect = new HtmlRichEffect();
...
]]></programlisting>
  </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: <itemizedlist>
        <listitem><para>attached to the JSF components or html tags 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>
    <para>
      <emphasis role="bold">Those a the typical variants of using:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<!-- attaching by event  -->
<rich:panel>
	<rich:effect event="onmouseout" type="Opacity" params="duration:0.8,from:1.0,to:0.3" />
    .... panel content ....
</rich:panel>
...

<!--  invoking from JavaScript -->
<div id="contentDiv">
  ..... div content ......
</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" />

<!-- attaching to window on load and applying on 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>
      <emphasis>
        <property>&quot;name&quot;</property>
      </emphasis> attribute defines a name of the JavaScript function that is be generated on a page
      when the component is rendered. You can invoke this function to activate the effect. The
      function accesses one parameter. It is a set of effect options in JSON format. </para>

    <para>
      <emphasis>
        <property>&quot;type&quot;</property>
      </emphasis> attribute defines the type of an effect. For example, "Fade", "Blind", "Opacity".
      Have a look at <ulink url="http://script.aculo.us">scriptaculous documentation</ulink> for set
      of available effect. </para>

    <para>
      <emphasis>
        <property>&quot;for&quot;</property>
      </emphasis> attribute defines the id of the component or html tag, the effect is attached
      to. RichFaces converts the <emphasis>
        <property>&quot;for&quot;</property>
      </emphasis> attribute value to the client id of the component if such component is found. If
      not, the value is left as is for possible wiring with on the DOM element&apos;s id on the client
      side. By default, the target of the effect is the same element that effect pointed to.
      However, the target element is might be overridden with <emphasis>
        <property>&quot;targetId&quot;</property>
      </emphasis> option passed with <emphasis>
        <property>&quot;params&quot;</property>
      </emphasis> attribute of with function paramenter. </para>

    <para>
      <emphasis>
        <property>&quot;params&quot;</property>
      </emphasis> attribute allows to define the set of options possible for particurar effect. For
      example, 'duration', 'delay', 'from', 'to'. 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. Those are: <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> You can use a set of effects directly without defining the <emphasis role="bold">
        <property>&lt;rich:effect&gt;</property>
      </emphasis> component on a page if it&apos;s convenient for you. For that, load the
      scriptaculous library to the page with the following code: </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<a4j:loadScript src="resource://scriptaculous/effect.js" />
...
]]></programlisting>
    <para> If you do use the <emphasis role="bold">
        <property>&lt;rich:effect&gt;</property>
      </emphasis>component, there is no need to include this library because it&apos;s already here. </para>

    <para>For more information look at <ulink
        url="http://jboss.com/index.html?module=bb&amp;op=viewtopic&amp;t=119044">RichFaces
        Users Forum</ulink>.</para>
  </section>
  
  <section>
    <title>Look-and-Feel Customization</title>
    
    <para><emphasis role="bold">
      <property>&lt;rich:effect&gt;</property>
    </emphasis> has no skin parameters and custom <property>style classes</property>, as the
      component isn&apos;t visual.</para>
  </section>
  
  <section>
    <title>Relevant Resources Links</title>
    <para>
    	<ulink
    		url="http://wiki.jboss.org/wiki/CreateABannerUsingEffectsAndPoll">
    		Here
    	</ulink>
    	you can get additional information how to create an image banner
    	using
    	<emphasis role="bold">
    		<property>&lt;rich:effect&gt;</property>
    	</emphasis>
    	and
    	<emphasis role="bold">
    		<property>&lt;a4j:poll&gt;</property>
    	</emphasis>
    	components and
    	<ulink
    		url="http://wiki.jboss.org/auth/wiki/CreateAHTMLBannerUsingEffectsAndPoll">
    		here
    	</ulink>
    	how to create a HTML banner.
    </para>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/effect.jsf?c=effect"
      >Here</ulink> you can see the example of <emphasis role="bold">
        <property>&lt;rich:effect&gt;</property>
      </emphasis> usage. </para>
    <para>How to save <emphasis role="bold">
        <property>&lt;rich:effect&gt;</property>
      </emphasis>status see on the <ulink
        url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;t=118833"
        >RichFaces Users Forum</ulink>.</para>
  </section>
</section>
