Overal description:

The tag designed to provide possibility to perform simple jquerry 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 jquerry 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

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 "onready"(default). If "onready" 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.