JBoss.orgCommunity Documentation
Some concepts covered in this chapter may refer to the previous version of Richfaces, version 3.3.3. This chapter is scheduled for review to ensure all information is up to date.
Read this chapter to alter the layout and appearance of web applications using special components.
The <rich:jQuery> component applies styles and custom behavior to both JSF (JavaServer Faces) objects and regular DOM (Document Object Model) objects. It uses the jQuery JavaScript framework to add functionality without conflicting with the prototype.js library.
The query triggered by the <rich:jQuery> component is specified using the query attribute.
The query can be triggered in three different ways. Use the timing attribute to specify the point at which the query is triggered:
immediateThe query is triggered immediately.
onloadThe query is triggered when the document is loaded.
onJScall
The query is triggered when a JavaScript function is invoked. The JavaScript function is specified using the name attribute.
If the name attribute is included when the timing attribute is set to either immediate or onload, the query can be triggered using the JavaScript function in addition to the specified trigger timing.
Example 12.1. <rich:jQuery> example
<rich:dataTable id="customList" ... >
...
</rich:dataTable>
<rich:jQuery selector="#customList tr:odd" timing="onload" query="addClass(odd)" />
In the example, the selector picks out the odd <tr> elements that are children of the element with an id="customlist"addClass(odd) is then performed on the selection during page loading (onload) such that the odd CSS class is added to the selected elements.
Any objects or lists of objects used in the query are specified using the selector attribute. The selector attribute references objects using the following method:
The selector attribute can refer to the id attribute of any JSF component or client.
If the selector attribute does not match the id identifier attribute of any JSF components or clients on the page, it instead uses syntax defined by the World Wide Web Consortium (W3C) for the CSS rule selector. Example 12.2, “Example selector values” shows a list of examples of the selector syntax. Refer to the syntax specification at http://www.w3.org/TR/CSS2/selector.html for full details.
Example 12.2. Example selector values
p:has(a)
All <p> elements which contain an <a> element are selected.
p.foo:has(a)
All <p> elements of class foo which contain an <a> element are selected.
p#secret
All <p> elements with an id identifier of secret are selected.
ul > li
All <li> elements that are children of <ul> elements are selected.
input[name=bar]
All <input> elements with a name attribute whose value is bar are selected.
input[type=radio][@checked]
All <input> elements with both a type="radio"checked attribute are selected.
p,span,td
All <p> elements, <span> elements, and <td> elements are selected.
p span
All <span> elements that are direct or indirect children of <p> elements are selected. Use p > span for direct children only.
p[foo^=bar]
All <p> elements that contain a foo attribute with a textual value beginning with bar are selected.
p[foo$=bar]
All <p> elements that contain a foo attribute with a textual value ending with bar are selected.
p[foo*=bar]
All <p> elements that contain a foo attribute with a textual value that contains the sub-string bar in any position are selected.
Because the selector attribute can be either an id identifier attribute or CSS selector syntax, conflicting values could arise. Example 12.3, “Avoiding syntax confusion” demonstrates how to use double backslashes to escape colon characters in id identifier values.
Example 12.3. Avoiding syntax confusion
<h:form id="form">
<h:panelGrid id="menu">
<h:graphicImage value="pic1.jpg" />
<h:graphicImage value="pic2.jpg" />
</h:panelGrid>
</h:form>
The id identifier for the <h:panelGrid> element is form:menu, which can conflict with CSS selector syntax. Double backslashes can be used to escape the colon character such that the identifier is read correctly instead of being interpreted as CSS selector syntax.
<rich:jQuery selector="#form\\:menu img" query="..." />
If the name attribute is specified, the <rich:jQuery> component generates a JavaScript function that can be called by any other JavaScript on the page.
Calls to the function must pass a direct reference (this) to the calling object as a parameter. If the function requires extra parameters itself, these are provided in JavaScript Object Notation (JSON) syntax as a second parameter in the JavaScript call. The param namespace is then used in the <rich:jQuery> query to access the passed function parameters. Example 12.4, “Calling a <rich:jQuery> component as a function” demonstrates the use of the name attribute and how to pass function parameters through the JavaScript calls.
Example 12.4. Calling a <rich:jQuery> component as a function
<h:graphicImage width="50" value="/images/price.png" onmouseover="enlargePic(this, {pwidth:'60px'})" onmouseout="releasePic(this)" />
<h:graphicImage width="50" value="/images/discount.png" onmouseover="enlargePic(this, {pwidth:'100px'})" onmouseout="releasePic(this)" />
...
<rich:jQuery name="enlargePic" timing="onJScall" query="animate({width:param.pwidth})" />
<rich:jQuery name="releasePic" timing="onJScall" query="animate({width:'50px'})"/>
The example enlarges the images when the mouse moves over them. The enlargePic and releasePic components are called like ordinary JavaScript functions from the image elements.
The <rich:jQuery> component applies style and behavioral changes to DOM objects dynamically. As such, changes applied during an Ajax response are overwritten, and will need to be re-applied once the Ajax response is complete.
Any queries with the timing attribute set to onload may not update during an Ajax response, as the DOM document is not completely reloaded. To ensure the query is re-applied after an Ajax response, include the name attribute in the <rich:jQuery> component and invoke it using JavaScript from the oncomplete event attribute of the component that triggered the Ajax interaction.
RichFaces includes the jQuery JavaScript framework. The features of the framework can be accessed directly without using a <rich:jQuery> component by including the library on the page using the <a4j:loadScript> component:
<a4j:loadScript src="resource://jquery.js"/>
Refer to the jQuery documentation at http://docs.jquery.com for full details on jQuery syntax and usage.