JBoss.org Community Documentation

- Prev
- Next

## 6.26. < rich:componentControl >

### 6.26.1. Description

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

### 6.26.2. Key Features

- Management of components JavaScript API

- Customizable initialization variants

- Customizable activation events

- Possibility to pass parameters to the target component

Table 6.99. rich : componentControl attributes

Attribute Name | Description
--- | ---
attachTiming | Defines the page loading phase when componentControl is attached to another component. Default value is "onavailable"
attachTo | Client 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 | The attribute takes a value-binding expression for a component property of a backing bean
disableDefault | Disable default action for target event ( append "return false;" to JavaScript )
event | The Event that is used to trigger the operation on the target component
for | Client identifier of the target component.
id | Every component may have a unique id that is automatically created if omitted
name | The optional name of the function that might be used to trigger the operation on the target component
onsubmit | onsubmit
operation | The 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.
params | The 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 | If "false", this component is not rendered

Table 6.100. Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.ComponentControl
component-class | org.richfaces.component.html.HtmlComponentControl
component-family | org.richfaces.ComponentControl
renderer-type | org.richfaces.ComponentControlRenderer
tag-class | org.richfaces.taglib.ComponentControlTag

### 6.26.3. Creating the Component with a Page Tag

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

Example:

    ...

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

    ...

### 6.26.4. Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlComponentControl;

    ...

    HtmlComponentControl myComponentControl = new HtmlComponentControl();

    ...

### 6.26.5. Details of Usage

<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" for="ccCalendarID" operation="Expand"/>

    ...

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> connects two components with the help of JavaScript API function.

Component ID, to wich the event, that invokes JavaScript API function is applied, is defined with "attachTo" attribute (see the exapmle above). If "attachTo" attribute is not defined, the component will be attached to the parent component.

Example:

    ...

    <h:commandButton value="Show Modal Panel">

        <rich:componentControl for="ccModalPanelID" event="onclick" operation="show"/> <!--attached to the commandButton-->

    </h:commandButton>

    ...

On the result page the component is rendered to JavaScript code. This means, that it is possible to invoke the <rich:componentControl> handler operation as usual JavaScript function. This function is called by name, specified in the component "name" attribute. The definition of "name" attribute is shown on the example below:

    ...

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

    ...

The generated JavaScript function will look as shown below:

    function func (event) {

    }

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

Example:

    ...

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

Example:

    ...

    <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:

- "immediate" - attached during execution of <rich:componentControl> script

- "onavailable" - attached after the target component is initialized

- "onload" - attached after the page is loaded

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

Example:

    ...

    <f:view>

        <h:form>

            <br />

            <rich:toolTip id="toolTipFor" followMouse="false" direction="top-right" mode="ajax" value="This is button" horizontalOffset="5" verticalOffset="5" layout="block" />

        </h:form>

        <h:commandButton id="ButtonID" value="Button">

            <rich:componentControl for="toolTipFor" attachTo="ButtonID" operation="show" event="onclick"/>

        </h:commandButton>

    </f:view>

    ...

This is a result:

Figure 6.22. <rich:toolTip> shows with the help of <rich:componentControl> .

As it could be seen in the picture above, the <rich:toolTip> shows after you click the button.

### 6.26.6. Look-and-Feel Customization

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

### 6.26.7. Relevant Resources Links

Here you can see an example of <rich:componentControl> usage and sources for the given example.

Here you can found some additional information about <f:param> component.

- Prev6.25. < rich:comboBox >
- Top of page
- Front page
- Next6.27. < rich:contextMenu >