Overal description:
The tag designed to provide possibility to perform simple jquery api calls in declarative manner.
E.g. in order to add zebra-style to the table you could use nex declarative definition instead of adding <script> block:
- <rich:jQuery selector="#carList tr:odd" query="addClass('odd-row')" />
- <rich:jQuery selector="#carList tr:even" query="addClass('even-row')" />
We still want to keep that tag in 4.x especially considering that jquery is the only base library for RichFaces starting from 4.x version. So the document will cover changes for the component migration.
Use-cases
We have next main popular jquery usages to consider:
1) jQuery(selector).simpleAPICall(options);
just calling some simple methods when page script evaluated or page rendererd.
2) binging some handler using jQuerry to elements(returned by jQuery(selector))
3) definition of function which contains the same jQuery(selector).simpleAPICall(options); call but could be called from some other handlers.
4) definition of function which will bind handler to elements
Requirements:
definitions of selector
selector could be defined by selector named attribute. It should be any valid jQuery selector
Note:The jQuery selector (subset of CSS selectors defined by W3C) of the element to which the jQuery function should be applied. ID selectors starting with hash sign (#) will be expanded from componentId to clientId form. (e.g. #component is expanded to #form:component in case that component is nested in form)
definitions of query call
query attribute - defines js statement to be called
e.g.
- <rich:jQuery selector="#divId" query="someApiCall">
will be encoded as
- jQuery('#divId').someApiCall();
query as handler to event
event attribute should be introduced in 4.x. It will be event of elements returned by jQuery(selector) to which query will be bound as event handler
e.g.
- <rich:jQuery event="click" selector="#divId" query="someApiCall">
will be encoded as
- jQuery('#divId').bind(click, function(){someApiCall()});
or
- jQuery('#divId').live(click, function(){someApiCall()});
type of handler binding
attachType should be introduced and have "live", "one" and "bind"(default) values in order the developer to be able to choose between the attachment variants.
Unnamed Queries execution
Unnamed queries ( 1) and 2) from usecases) should be handled according to timing attribute.
Execution timing
The attribute specifies if the query should be executed "immediate" or "domready"(default). If "domready" specified - query should be wrapped with jQuery(...) if "immediate" query should be just called as inline script.
Note: onJsCall removed as now just depends on name.
Named queries
Named queries ignores timing attribute as definition of the name - means that we just creating the function which should be called by some JS. ( 3) and 4) from use-cases)
Instead of selector - handler also should accept element. For example. - in named queries - user could pass element to function instead of using selector definition.
Name attribute definitions
component should provide name attriute to be handled in next way:
1) for queries not bound to event query should be just wrapped to function in order to call from js
- <rich:jQuery name="fooName" selector="fooSelector" query="fooApi">
will be encoded as
- function fooName(){
- jQuery(fooSelector).fooApi();
- }
2) for queries which defines event - it should wrap binging handler to the function making binding to event available from some js call.
- <rich:jQuery name="fooName" selector="fooSelector" query="fooApi" event="click" attachType="bind">
will be encoded as
- function fooName(){
- jQuery(fooSelector).bind('click' , fooApi());
- }
Options Passed - :
If the handler was called with two arguments - first one defines selector or element and the second - options hash (named options). If single parameter - it's jsut options hash.
https://community.jboss.org/wiki/RichjQueryIn4x
rich:jQuery(id) - returns a jQuery object with an element for given short id