1. Common Ajax core components points

1.1 Common Ajax attributes names

Proposed to drop the naming compatibility with 3.3.x release for some attributes and made the names consistent to JSF 2 standard parameters names. And also to drop/add some common attributes. So here are the lists:

(attributes which has "-" in 3.3.x cell - added attributes)

Common events Attributes list

TBD: sequence diagram for events.

TBD: table of components and applicable events

1.2 Server Side Process/Render mechanisms

Next features should be implemented in order to be available from any RichFaces core ajax component defined later in this doc:

1. regions support for Impl in A2
2. additional execute features
3. render-ing lists

1) link to region req.

2) execute -  a space or comma delimited list of client identifiers or one of the keywords. These reference the components that will be processed during the  execute” phase of the request processing lifecycle. As mentioned before we should extend the list of keywords with the @region.

3) rendering

1. We should also keep automatically updated zones feature. So outputPanel component with ajaxRendered property defined as true should be added in list automatically.
2. the only exception to 1) is the components which is uses disableImplicitRender defined as true. For the requests from such components - the outputPanels and components based on it (messages, includes..) should not be updated automatically.This rendering limitation should be done at server side.
3. render a space or comma delimited list of client identifiers or one of the keywords
4. Also render attribute should be possible to be defined fully at server side(from action, listeners). So it should be possible to define it with value-binding to some id's List, String with comma or space separated values, id's Set.

1.3 Difference for JSF and RF render/execute mechanisms

JSF declares just client side render/execute declarations. And we declare server side definitions of lists. it's mean that the same construction:

<f:ajax render="#{bean.renderList}" execute="#{bean.executeList}" />

and

<a4j:ajax render="#{bean.renderList}" execute="#{bean.executeList}" />

will produce different results. f:ajax will get ids when encoded and a4j:ajax will calculate ids during sent request processing. For request scoped beans results will not be the same. Maybe we need some different modes in order to developer to be able to use our ajax components in the same way as standard one?

2. a4j:ajax (former a4j:support)

Should be implemented as a JSF 2 behavior which could be added to any component and bind to some client side event provided by the component.

Should be possible to wrap some subtree with this behavior as standard f:ajax support. For Impl In in A2.

Sending request

event - attribute of the behavior. It is used to defined the event which activate behavior. So event occured at the component will activate the a4j:ajax and request will be fired. If not defnied - component's defaultEventName should be used.

This is base component for all the ajax stuff and all the other attributes defined in common section. It has no more specific ones.

3. region - for Impl in A2

Regions should has the same processing limitation functionality as for 3.3.x except one point - the component now will extend rendering zone instead of reducing it. It caused by the fact that we should care about the defaults for ajax attributes in order them to be consistent with JSF defaults.

So:

• by default ajax behaviors/components has execute = "@this"
• if ajax behaviors/components wrapped into region and no execute specified - execute became @region and whole region processed.
  • so if in 3.3.x - absense of region meant that whole view processed - in 4.x it will works as ajaxSingle(execute=@this).
  • execute="@region" should be allowed as value for ajax components/behaviors in order to declare region processing implicitly.
  • if execute="@region" used but there is no region around the component - JSF @this default value should be used.
• Standard JSF components/behaviors and other libraries components should not be affected by RF region component  

It should still be allowed to nest regions.

The component should also provides limitRenderToRegion(former renderRegionOnly) option(same as in 3.3.x). This option defined as true should not allow the action components inside made updates outside the region. This could be usefull in order to limit auto render'ed components outside the region encoding without disableImplicitRender definition at every action component. out of A2 scope.

Not implemented:

• immediate - we not going to implement this
• renderRegionOnly - not in A2
• selfRendered - not in A2

a4j:status components should not be bound to regions as in 3.x.

Code Samples below declares the same processing

<a4j:region>
 <h:inputText value="#{userBean.name}">
 <a4j:ajax event="onkeyup" render="outname" execute="@region"/>
 </h:inputText>
</a4j:region>

and 

<a4j:region>
 <h:inputText value="#{userBean.name}">
 <a4j:ajax event="onkeyup" render="outname" />
 </h:inputText>
</a4j:region>

Forum thread: http://community.jboss.org/message/20205#20205

4. outputPanel - Implemented in A1

The component analogous to standard h:panelGroup and declares next additional features:

• Always has DOM representation (div when block, span when inline or placeholder elements if has no children rendered when none layout.)
• Should have 'none' layout - not implemented in A1
  
  • If child component not rendered - should encode some placeholder to encode child component when it will became rendered.
• The component automatically added to render areas by ajaxRendered attribute set to true.
• layout attribute - let's drop the 3.3.x compatibility there and have it block by default. Users which nest block components inside (very often situation as span is default and our components div based) has Ajax updates of this area broken.

ajaxRendered default is false.

Open issue Do we still need to keep keepTransient functionality? Not for A2. depends on region selfRendered

5. status - Implemented in A1

The component for indication of ajax requests activities.

status implemented as a component and not a behaviour because it should have it's own representation in DOM according to definition in component tree.

status name attribute is just alias for id - For review in A2

Status not planned to be connected with regions as it was in 3.3.x.

status representation definitions:

• startText, stopText, errorText - attributes which allows to define simple text labels which will be shown in corresponding states.
• start, stop, error - facets. Allows to define any markup for the states.

"Error" functionality is new for 4.x and defines the status representation when request finished but erorr event was risen.

status definitions options:

• common status for view

Should be defined inside the view but outside any forms without name defined. Supported multiple statuses for the same view.

     <a4j:status>
            <f:facet name="start">
                <h:graphicImage value="/images/status.gif"/>
            </f:facet>
     </a4j:status>
         ...
     <h:form>
          ...
     </h:form>
     ...
     <h:form>
          ...
     </h:form>

All the components inside both forms will use this status instance

• common status for form

Should be defined inside the form without name defined. Supported multiple statuses for the same form.

        <h:form>
           <a4j:status>
                <f:facet name="start">
                    <h:graphicImage value="/images/status.gif"/>
                </f:facet>
            </a4j:status>
            </h:panelGrid>
            <h:commandButton value="Submit" type="button" action="#{userBean.store}">
                <f:ajax render="out"/>
            </h:commandButton>

            <a4j:commandButton value="submit"/>
        </h:form>

All the components inside the form will reuse the status.

• status defined explicitly on ajax components

Should be defined with the name defineds. Will react only specific requests from components with status defined with this name.

<h:panelGrid columns="3">
                <h:outputText value="User name:" />
                <h:inputText value="#{userBean.name}" >
                    <a4j:ajax event="keyup"/>
                    <a4j:attachStatus status="nameStatus" event="keyup"/>
                </h:inputText>
                <a4j:status name="nameStatus">
                    <f:facet name="start">
                        <h:graphicImage value="/images/ai.gif"/>
                    </f:facet>
                </a4j:status>
                <h:outputText value="Adress:" />
                <h:inputText value="#{userBean.address}">
                    <a4j:ajax event="keyup"/>
                    <a4j:ajax status="adressStatus" event="keyup"/>
                </h:inputText>
                <a4j:status name="adressStatus">
                    <f:facet name="start">
                        <h:graphicImage value="/images/ai.gif"/>
                    </f:facet>
                </a4j:status>
            </h:panelGrid>

different components pointed to specific statuses.

attachStatus could be also used as wrapper behavior for some set of components.

events attributes:

• onstart
• onstop
• onerror
• onsuccess

For impl in A2

ClientSide component API:

#{rich:component('statusId')}.switchToState('stateName');

#{rich:component('statusId')}.getCurrentState();

stateName - one of the "start", "stop", "error". Corresponding events should be risen and handlers called

Common ClientSide API

RichFaces.Status.find(object) //TBD possible objects.. e.g. Id, element, component and so on..

returns the status for the component (one of the global ones for the component if exist).

6. jsFunction - Implemented in A1

The component designed to send ajax request from using JSF calls.

name: main attribute. registers the component as function with specified name(e.g. myFunc). so calling myFunc() method will cause ajax request with given parameters to be fired.

Main features:

• ajax call by js call with registered name.
• automaticall passing parameters using next construction:

<a4j:jsFunction name="ajaxCall"..>
     <f:param name="rowKey">
</a4j:jsFunction> 

<rich:column onclick="ajaxCall('#{rowKey}')">
...
</rich:colum> 

Queueing changes for the component

requestGroupingId(similarityGroupingId) for the component was equals to client id if not set. And that was caused that all requests from that jsFunction was combined in queue. As this component designed to rise Ajax call from js which could be used at many different components that behavior seems not always expected. So for 4.x we're going to change that to:

• if component has no requestGroupingId defined - requests will not be processed as sililar in queue by default so would not be grouped.
• if the developer still need to mark all the concrete jsFunction requests as similar - he just need to define that attribute and them all will use that similarity Id.

7. Push/Poll component A1/A2

(Poll - not implemented in A1)

Similar to 3.3.x variant except changes from common section and:

• produces client side event (something  ondataavailable for push(server event dataAvailable) and something like ontimer(name?) for poll).
• this event could be handled by ajax behavior or some custom js.
• If the component not have submitting behavior it encodes its default one which could be configured using core attributes.

8. message/messages - not implemented in A1

Components should be moved to core component (became a4j:message(s)) - questonable.

The components is a combination of h:message(s) and a4j:outputPanel wtih ajaxRendered=true

Should be automatically updated by any ajax request (except requests with disableImplicitRender=true specified).

Should keep 3.3.x functionality of icons facets.

We need to review and add next possibilies:

• add  passed state to be shown when validation occured and succesfull  https://jira.jboss.org/browse/RF-9349
  • should not be shown on initial rendering (before validation actually occured)
  • passedLabel attribute defines message
  • passed facet alloows to define icons (the same as for messages)
  • also styles and classes attributes the same as for messages should be considered
• separate summary and details by putting into separate spans with predefined rf-* classes. It's just for better and simplier styling. https://jira.jboss.org/browse/RF-9350
  • add corresponding classes attributes

Messages should support JS API for messages addition/getting the current messages shown and clearing the message. info about API will be added there http://community.jboss.org/wiki/ClientSideValidation

9. a4j:commandButton/a4j:commandLink - Implemented in A1

Analogous to standard button/link but with support behavior plugged.

Has all common attributes defined in first section except onbegin which is changed with onclick for this component.

onclick - actually this attribute should be used as onrequestbegin handler and has request event data passed to handler. This event should be also cancelable as onrequestbegin.

10. Log A1

RFCs to 3.3.x version:

• Should be possible to switch levels on the client
• should be possible to has next representation 
  • inline in page markup
  • openind new window NOT for A1, A2
  • write in browser console instead of div or just new window - NOT for A1, A2
• Should be possible to define application context param which will turn on log at all application pages NOT for A1, A2
• Should be possible to define popup which will be opened not with keyboard shortcut but clicking some special absolutelly positioned shortcut on the page. (shortcuts definition for different browsers currently really hard for the developer) NOT for A1, A2

   

11. a4j:attachQueue REVISE if we really need two tags if queue - just options container.

http://www.jboss.org/community/docs/DOC-14380

12. componentControl - For impl in A2

The component should be moved to core a4j components set. It should provide the same functionality as for 3.3.3 with next corrections:

Component control should be a behavior.

attachTo and attachTiming should be removed and standard behavior attachment used.

selector attribute should be added. for uses id's to look for target components. And selector should be used with any CSS selector.

It should accept f:param's and pass to api method called

params attribute should became parameters

TBD: revise usage with the other behaviors. e.g. it could be used on ajax oncomplete

After A2 we will discuss Events API more and extend the component like described there if need:

http://community.jboss.org/wiki/EventsAPIandcomponentControl

13. actionparam (<a4j:param> in 4.x) - For impl in A2

• As the component provides not only server side parameters transmission we decided that probably should be renaimed to  just a4j:param
• Defining listener on parameter tag looks not natural. Explicit tag a4j:actionListener(described below) should be created, and the functionality should be removed from param component.
• we should add for attribute which should works the same as for standard f:actionListener: 
  • If present, this attribute refers to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.
• We should review problems with name attirbute. If mandatory - should be marked as required everywhere as possible. If not but has some problems like now with usage inside UIData for example - should be highlighted in documentation.

14. actionListener - For impl in A2

• The only addition which should be done within the tag in difference with standard - listenerMethod attribute shoud be added in order to allow MethodExpression definitions.

15. functions - For impl in A2

All the rich:* functions should be ported from 3.3.x to 4.x transparently.

TBD continue investigations how the set could be expanded.

a4j:apply- Continue at forum only.

Tag idea - to simplify applying queue/statuses/something else.. for some group of the components without "for-like" definition at every component.

Example based on status component:

As we decided that we probably need to drop status definition associating with region we have to define common status for page or define status by name at every component which need to ahve some other one.

But if we have a group of components which need to have one status (a4j:validators "validation" status) and the second group which need to have the other ("save" buttons/links should have "processing" status) we need to generalize status definition for both group.

So we defining common a4j:status for "processing" components for example as default for the view. So we have next page definition:

...
<h:inputText..>
     <a4j:validator id="firstValidator".../>
</h:inputText..>
<h:selectOneMenu..>
     <a4j:validator id="secondValidator".../>
</h:selectOneMenu..>
....

And now we should just define something like this

<a4j:status name="validation" ... />
<a4j:apply componentType="org.richfaces.AjaxValidator" attribute="statusId" value="validation"/>
//by component type

or

<a4j:apply forId="*Validator" attribute="statusId" value="validation"/> 
//by Id 'selector'

In the same way we could add queue definition to some group of ajax components, or even simply add some styleClass'es to any components satisfying selector or type.