JBoss.orgCommunity Documentation
Read this chapter for details on miscellaneous components that provide extended functionality to web applications.
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.5, “<rich:hashParam>” for details.
client-behavior-renderer-type
: org.richfaces.behavior.ComponentControlBehavior
behavior-id
: org.richfaces.behavior.ComponentControlBehavior
handler-class
: org.richfaces.taglib.ComponentControlHandler
behavior-class
: org.richfaces.component.behavior.ComponentControlBehavior
client-behavior-renderer-class
: org.richfaces.renderkit.html.ToggleControlRenderer
The <rich:hotKey>
component allows to register hot keys for the page or particular elements and to define client-side processing functions for these keys.
There are two ways to register <rich:hotKey>
:
place it anywhere on the page. In this case the <rich:hotKey>
component is attached to the whole page. This is default scenario.
attach it with selector
attribute to all the elements defined using this selector. This attribute uses syntax for CSS rule selector defined by W3C consortium with some jQuery extensions.
The key
attribute defines the hot key itself which is processed by the component.
The key sequences can be defined using a "+
" key separator. The key sequence modifiers needs to be defined in an alphabetical order, e.g. alt+ctrl+shift
.
The hot key processing can be disabled by setting rendered
to false
.
Example 17.3. <rich:hotKey>
basic usage
<rich:hotKey key="ctrl+z">
<rich:componentControl target="popup" operation="show" />
</rich:hotKey>
<rich:popupPanel id="popup">
...
</rich:popupPanel>
The example contains <rich:hotKey>
which handles Ctrl+Z
key sequence on the whole page. When the key sequence is pressed, the <rich:popupPanel>
is displayed.
The enabledInInput
attribute enables the hot key event processing when form inputs are focused. This attribute is false
by default.
The preventDefault
attribute specifies whenever hot key binding should prevent default browser-specific actions to be taken (e.g. Ctrl+A
hot key selecting all available text, Ctrl+B opening bookmarks bar, etc.). This attribute has default value true
.
Even though RichFaces instructs browser prevent default action, browser implementations does not support preventing browser's native actions for selected key combinations.
Althought the inability to prevent default action is not usual, you may experience that both programatically-defined action and browser's native action are triggered (e.g. native popup appears).
To keep application accessible, it is convenient to do not depend on hot keys or hot key combinations heavily. Best practice is using hot key only as shortcut for given action.
The following event handlers could be used to trigger client-side behaviors or to invoke javascript directly:
keydown
(default event) is fired when hot key sequence is initiated (keys are down)
keyup
is fired when hot key sequence is finished (keys are up)
Example 17.4. <rich:hotKey>
event handlers
<rich:hotKey key="ctrl+a" onkeyup="alert('Ctrl+A was pressed')" />
The <rich:editor>
uses <iframe>
for the editable area.
The <iframe>
doesn't allow to propagate events outside of <rich:editor>
,
making <rich:hotKey>
unusable for handling events from <rich:editor>
.
The CKEditor specific event handling mechanism could be used instead.
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.5. <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.