The goal of the document to explain the usage of the new RichFaces Event API mechanism and to provide requirements on new behavior which will allow to use it declarativelly.

3.3.x Client Side API usage

     in 3.3.x and older versions every component defined api methods which available on $('componentId').component object.

     Also we had <rich:componentControl/> component which was designed to find the component and to call the api with parameters passing.

     So two usages was available:

<h:outputLink value="#" id="openLink" onclick="#{rich:component('modalPanel')}.show(event)">
     Click
</h:outputLink>

or

<h:outputLink value="#" id="openLink">
     <rich:componentControl for="modalPanel" event="onclick" operation="show">
</h:outputLink>

4.x Event API

For 4.x we want to improve the described mechanism by introducing events API. Main changes:

• the developer will not need to find the component in DOM and access to its client side API directly but could send one of the events which component could handle
• this events could be sent to some component group or event to all the components. (in 3.3.x you will have to call the method on every component)
• Logging will be added. In difference with referencing non-existent meother the event which was not handled by any component will not rise js error. So we will add logging on such events in order to inform the developer about wrong unhandled events sent
  • could depends on project stage

Calling handlers/sending events from JavaScript (Draft, naming could be revised)

Generate events which will be handled by components:

RichFaces.event.fire(selector, eventName, [options])

RichFaces.event.firebyId('id', eventName, [options])

So let look for example to the table component which handles next events:

onclick="RichFaces.fireById('tableId', 'sort', {columnId:'columnIdToSort'})"

onclick="RichFaces.event.fireEvent('tableId', 'expand', {subtableId:'subtableId'})" 
//for concrete subtable

onclick="RichFaces.fireEvent('tableId', 'expand')"  
//expands all subtables.

Binding handlers to component events

Next functions available to bind the handler to an event

• bind(selector, type, function, data)
• bindById(id, type, function, data)
• bindOne(selector, type, function, data)
• bindOneById(id, type, function, data)

example:

fn : function (eventObject, element) {
 //this - object passed as data to bind function or dom element if no data
 //element - dom element
     
}

RichFaces.Event.bind(selector, type, fn, data);

ComponentControl component(Draft namings should be revised)

     This component seems should be included to A2 scope as we told about unified toggler behavior for the table component which could perform the sorting/subtables switching an so on. Next changes proposed:

• Should be implemented as a behavior instead of component
• targetEvent attribute should be added - event which will be setn
• operation attribute will still be available
  • could both these attributes be defined?
• selector attribute should be added
• for attribute will still be available
  • this attributes could not be set both!
• let's move the component to core a4j library as actually it's not a UI component

Sending parameters with the event actually should be performed as for previous version by using nested <f:param> declarations

So calls mentioned above in JS Usage defined declarativelly with the behavior will looks like:

<rich:componentControl event="click" targetEvent="sort" selector="#table">
     <f:param name="columnId" value="columnIdToSort">
</rich:componentControl>

TBD more examples like sending event to particular component group and so on.