JBoss.orgCommunity Documentation
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 to web applications.
The query triggered by the <rich:jQuery>
component is specified using the query
attribute.
With the query defined, the component is used to trigger the query as either a timed query or a named query. The query can be bound to an event to act as an event handler. These different approaches are covered in the following sections.
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 elements by using syntax of the jQuery Selectors (a superset of CSS selectors defined by W3C consortium) and additionally it expands JSF component IDs to client-side IDs (see the VDL documentation for the selector
attribute).
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. Refer to the syntax specification at http://api.jquery.com/category/selectors/ for full details.
Because the selector
attribute can be either an id
identifier attribute or CSS selector syntax, conflicting values could arise. Example 15.1, “Avoiding syntax confusion” demonstrates how to use double backslashes to escape colon characters in id
identifier values.
Example 15.1. 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="..." />
Queries set as event handlers are triggered when the component specified in the selector
attribute raises an event. The query is bound to the event defined using the event
attribute.
Use the attachType
attribute to specify how the event-handling queries are attached to the events:
bind
This is the default for attaching queries to events. The event handler is bound to all elements currently defined by the selector
attribute.
live
The event handler is bound to all current and future elements defined by the selector
attribute.
one
The event handler is bound to all elements currently defined by the selector
attribute. After the first invocation of the event, the event handler is unbound such that it no longer fires when the event is raised.
Timed queries are triggered at specified times. This can be useful for calling simple methods when a page is rendered, or for adding specific functionality to an element. Use the timing
attribute to specify the point at which the timed query is triggered:
domready
This is the default behavior. The query is triggered when the document is loaded and the DOM is ready. The query is called as a jQuery()
function.
immediate
The query is triggered immediately. The query is called as an in-line script.
Example 15.2. <rich:jQuery>
example
<rich:dataTable id="customList" ... >
...
</rich:dataTable>
<rich:jQuery selector="#customList tr:odd" timing="domready" query="addClass(odd)" />
In the example, the selector picks out the odd <tr>
elements that are children of the element with an
attribute. The query id
="customlist"addClass(odd)
is then performed on the selection during page loading (load
) such that the odd
CSS class is added to the selected elements.
Named queries are given a name such that they can be triggered by other functions or handlers. Use the name
attribute to name the query. The query can then be accessed as though it were a JavaScript function using the specified name
attribute as the function name.
Calls to the function must pass a direct reference (this
) to the calling object as a parameter. This is treated the same as an item defined through the selector
attribute.
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 options
namespace is then used in the <rich:jQuery>
query to access the passed function parameters. Example 15.3, “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 15.3. 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" query="animate({width:options.pwidth})" />
<rich:jQuery name="releasePic" 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 timed queries with the timing
attribute set to domready
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 complete
event attribute of the component that triggered the Ajax interaction.