Documentation in development
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 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
selectorattribute can refer to theididentifier of any JSF component or client.If the
selectorattribute does not match theididentifier 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 16.1, “Avoiding syntax confusion” demonstrates how to use double backslashes to escape colon characters in id identifier values.
Example 16.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:
bindThis is the default for attaching queries to events. The event handler is bound to all elements currently defined by the
selectorattribute.liveThe event handler is bound to all current and future elements defined by the
selectorattribute.oneThe event handler is bound to all elements currently defined by the
selectorattribute. 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:
domreadyThis 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.immediateThe query is triggered immediately. The query is called as an in-line script.
Example 16.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 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.
[D]
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 16.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 16.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.