rich:jQuery in 4.x

    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.