JBoss.orgCommunity Documentation

Chapter 17. Functionality extension

17.1. <rich:componentControl>
17.1.1. Basic usage
17.1.2. Passing parameters to API methods
17.1.3. Reference data
17.1.4. <rich:hashParam>

Read this chapter for details on miscellaneous components that provide extended functionality to web applications.

17.1. <rich:componentControl>

The <rich:componentControl> behavior allows JavaScript API functions to be called on target components. The functions are called after defined events are triggered on the component to with the <rich:componentControl> behavior is attached. Initialization variants and activation events can be customized, and parameters can be passed to the target component.

The operation attribute is required to attach JavaScript functions to the parent component, along with either the target or selector attributes. Use the operation attribute to specify the JavaScript API function to perform. Use the target attribute to define the id identifier of the target component, or use the selector attribute to define a number of target components through the use of valid jQuery selectors.

Use the event attribute to specify the event that triggers the JavaScript API function call if it is different from the default triggering event for the parent component.

Example 17.1. <rich:componentControl> basic usage


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

    <!--componentControl is attached to the commandButton-->

    <rich:componentControl target="ccModalPanelID" event="click" operation="show"/> 

</h:commandButton>

The example contains a single command button, which when clicked shows the modal panel with the identifier ccModalPanelID.


The operation can receive parameters through nested <f:param> elements.

Example 17.2. Using parameters


<rich:componentControl event="click" target="modalPanel" operation="show">

   <f:param value="width" name="500"/>

</rich:componentControl>

To group multiple parameters for a function, use the <rich:hashParam> component to create a hash map. Refer to Section 17.1.4, “<rich:hashParam>” for details.

The <rich:hashParam> component allows client-side parameters to be grouped into a hash map. The hash map can then be passed to the client JavaScript API functions of any RichFaces component.

Nest parameter tags in the <rich:hashParam> component to group them in the hash map. The hash map itself can then be passed as a function parameter.

Example 17.3. <rich:hashParam>


<h:commandButton value="Show popup">

   <rich:componentControl target="popupPanel" operation="show">

      <a4j:param noEscape="true" value="event" />

      <rich:hashParam>

         <f:param name="width" value="500" />

         <f:param name="height" value="300" />

         <f:param name="minWidth" value="300" />

         <f:param name="minHeight" value="150" />

         <a4j:param noEscape="true" name="left" value="(jQuery(window).width()/2)-250" />

         <a4j:param noEscape="true" name="top" value="(jQuery(window).height()/2)-150" />

      </rich:hashParam>

   </rich:componentControl>

</h:commandButton>

The example illustrates the use of the <rich:hashParam> component to group multiple parameters into a hash map. The parameters are passed through to the show function pop-up panel with the popupPanel identifier.