Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.14.1.  < rich:componentControl > available since 3.0.0

expand all
6.14.1.1. Description
6.14.1.2. Key Features
6.14.1.3. Creating the Component with a Page Tag
6.14.1.4. Creating the Component Dynamically Using Java
6.14.1.5. Details of Usage
6.14.1.6. Look-and-Feel Customization
6.14.1.7. Relevant Resources Links

The <rich:componentControl> allows to call JavaScript API functions on components after defined events.

Table 6.520. rich : componentControl attributes

Attribute Name Description
attachTimingDefines the page loading phase when componentControl is attached to another component. Default value is "onavailable"
attachToClient identifier of the component or id of the existing DOM element that is a source for given event. If attachTo is defined, the event is attached on the client according to the attachTiming attribute. If attachTo is not defined, the event is attached on the server to the closest in the component tree parent component.
binding JSF: The attribute takes a value-binding expression for a component property of a backing bean
disableDefaultDisable default action for target event. If the attribute is not set, it's made "true" by default if the event oncontextmenu is used and false in all other cases. if the attribute set, its value is used.
eventThe Event that is used to trigger the operation on the target component
forClient identifier of the target component.
id JSF: Every component may have a unique id that is automatically created if omitted
nameThe optional name of the function that might be used to trigger the operation on the target component
operationThe function of JavaScript API that will be invoked. The API method is attached to the 'component' property of the root DOM element that represents the target component. The function has two parameters - event and params. See: 'params' attribute for details.
paramsThe set of parameters passed to the function of Javascript API that will be invoked. The JSON syntax is used to define the parameters, but without open and closed curve bracket. As an alternative, the set of f:param can be used to define the parameters passed to the API function. If both way are used to define the parameters, both set are concatenated. if names are equals, the f:param has a priority.
rendered JSF: If "false", this component is not rendered

Table 6.521. Component identification parameters

NameValue
component-typeorg.richfaces.ComponentControl
component-classorg.richfaces.component.html.HtmlComponentControl
component-familyorg.richfaces.ComponentControl
renderer-typeorg.richfaces.ComponentControlRenderer
tag-classorg.richfaces.taglib.ComponentControlTag

To create the simplest variant on a page use the following syntax:


...
<rich:componentControl attachTo="doExpandCalendarID" for="ccCalendarID" event="onclick" operation="Expand" />
...

Example:

import org.richfaces.component.html.HtmlComponentControl;   

...
HtmlComponentControl myComponentControl = new HtmlComponentControl();
...

<rich:componentControl> is a command component, that allows to call JavaScript API function on some defined event. Look at the example:


...
<rich:componentControl attachTo="doExpandCalendarID" event="onclick" operation="Expand" for="ccCalendarID" />
...

In other words it means "clicking on the component with ID doExpandCalendarID expands the component with ID ccCalendarID". It can be said, that <rich:componentControl> makes interact two components with the help of JavaScript API function.

The ID of the component the event that invokes JavaScript API function is applied, is defined with "attachTo" attribute (see the exapmle above). If "attachTo" attribute is not specified, the <rich:componentControl> is supposed to be attached to it's parent.


<h:commandButton value="Show Modal Panel">
      <!--componentControl is attached to the commandButton-->
      <rich:componentControl for="ccModalPanelID" event="onclick" operation="show"/> 
</h:commandButton>

It is possible to invoke the <rich:componentControl> handler operation as usual JavaScript function. For this purpose it is necessary to specify the name of the JS function with the help of the "name" attribute:

Example:

function func (event) {
}

<rich:componentControl name="func" event="onRowClick" for="menu" operation="show" />

An important <rich:componentControl> feature, is that it allows transferring parameters, with the help of special attribute "params" :


...
<rich:componentControl name="func" event="onRowClick" for="menu" operation="show" params="#{car.model}"/>
...

The alternative way for parameters transferring uses <f:param> attribute. As the code above, the following code will represent the same functionality:


...
<rich:componentControl event="onRowClick" for="menu" operation="show">
      <f:param value="#{car.model}" name="model"/>
</rich:componentControl>
...

With the help of the "attachTiming" attribute you can define the page loading phase when <rich:componentControl> is attached to source component. Possible values are:

<rich:componentControl> interacts with such components as: <rich:contextMenu> , <rich:toolTip> , <rich:modalPanel > , <rich:listShuttle> , <rich:orderingList> , <rich:calendar>

In order to use <rich:componentControl> with another component you should place the id of this component into "for" attribute field. All operations with defined component you can find in the JavaScript API section of defined component.


<h:form>
      <rich:toolTip id="toolTip" mode="ajax" value="and then just touch me." direction="top-right" />
</h:form>
<h:commandButton id="ButtonID" value="Push me">
      <rich:componentControl attachTo="ButtonID" event="onmouseover" operation="show" for="toolTip" />
</h:commandButton>

This is a result:


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

Visit the ComponentControl page at RichFaces LiveDemo for examples of component usage and their sources.

Information on JSF <f:param> component You can find at <f:param> TLD reference in Java Server Faces technology section at Sun portal.