6.49.  < rich:effect >

6.49.1. Description

The <rich:effect> utilizes a set of effects provided by the scriptaculous JavaScript library. It allows to attach effects to JSF components and html tags.

6.49.2. Key Features

  • No developers JavaScript writing needed to use it on pages

  • Presents scriptaculous JavaScript library functionality

Table 6.189. rich : effect attributes

Attribute NameDescription
bindingThe attribute takes a value-binding expression for a component property of a backing bean
disableDefaultDisable default action for target event ( append "return false;" to javascript )
eventEvent on the component or html tag the effect is attached to
forId of the target component.
idEvery component may have a unique id that is automatically created if omitted
nameGenerated Javascript name.
paramsParameters passed to the effect function. Example params="{duration:0.2,from:1.0,to:0.1}"
renderedIf "false", this component is not rendered
targetIdThe id of the element the effect apply to. Might be component id or client id of jsf component or html tag. If targetId is not defined the value of the attribute 'for' or the 'targetId' option effect play its role
typeDefines the type of effect. Possible values: "Fade", "Blind", "Opacity".

Table 6.190. Component identification parameters

NameValue
component-typeorg.richfaces.Effect
component-classorg.richfaces.component.html.HtmlEffect
component-familyorg.richfaces.Effect
renderer-typeorg.richfaces.EffectRenderer
tag-classorg.richfaces.taglib.EffectTag

6.49.3. Creating the Component with a Page Tag

To create the simplest variant of <rich:effect> on a page, use the following syntax:

Example:


...
<rich:effect for="componentId" type="Appear"/>
...

6.49.4. Creating the Component Dynamically Using Java

Example:


import org.richfaces.component.html.HtmlRichEffect;
...
HtmlRichEffect myEffect = new HtmlRichEffect();
...

6.49.5. Details of Usage

It is possible to use <rich:effect> in two modes:

  • 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

  • invoking from the JavaScript code by an effect name. During the rendering, <rich:effect> generates the JavaScript function with defined name. When the function is called, the effect is applied

Those a the typical variants of using:


...
<!-- 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" />
...
Initial

Figure 6.88. Initial


When the mouse cursor is over

Figure 6.89. When the mouse cursor is over


"name" 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.

"type" attribute defines the type of an effect. For example, "Fade", "Blind", "Opacity". Have a look at scriptaculous documentation for set of available effect.

"for" attribute defines the id of the component or html tag, the effect is attached to. Richfaces converts the "for" 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'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 "targetId" option passed with "params" attribute of with function paramenter.

"params" 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 rich:effect attribute. Those are:

  • "targetId" allows to re-define the target of effect. The option is override the value of "for" attribute.

  • "type" defines the effect type. The option is override the value of "type" attribute.

You can use a set of effects directly without defining the <rich:effect> component on a page if it's convenient for you. For that, load the scriptaculous library to the page with the following code:

Example:


...
<a4j:loadScript src="resource://scriptaculous/effect.js" />
...

If you do use the <rich:effect> component, there is no need to include this library because it's already here.

For more information look at RichFaces Users Forum.

6.49.6. Look-and-Feel Customization

<rich:effect> has no skin parameters and custom style classes, as the component isn't visual.

6.49.7. Relevant Resources Links

Here you can see the example of <rich:effect> usage.

How to save <rich:effect> status see on the RichFaces Users Forum.