Base a4j:repeat component

We should keep the component as base for all data iteration ones. It will allow the customer to use our common features  for iteration components and implement their own ones with free markup.

• It should support actuall components iteration          
  • menus, columns and so on creation dynamically

Component features

//TODO: this probably duplicates the 'Features" table and should be removed.

Data Models Support

• Standard Data Models

• RichFaces Extended datamodels

  • AI Nick, Kostya — current model should be revised for changes and improvements.

• Seam Data Models

Partial updates

• AjaxKeys functionality - http://community.jboss.org/thread/5767

Implementation proposal

Tags set

Proposed not to combine all the features in one component, because the developers who have no need in them will have to use component with more complex layout scripts includes but without features used. So we should provide two ways:

• To use complex but high featured component

• To use light-weight component with simple table functionality.

We will implement that providing two actual components. Them should rely on the same server side model objects and interfaces and should not have different default models implementation as it was in 3.3.x and earlier.

Tables design

After initial discussion proposed next design implementation:

Simple table- current table based markups

ExtendedTable - table/div based markup (thats why some features marked as not for implementation in this table in genaral caused by markup limitations/complexity)

Features

Features to be implemented in tables will be shown as matrix where features marked with plus sign is for implementation for concrete table.

Version columns wil contains versions markers. I assume that initial is A2 and next ones will have marks like B1 B2 and so on. Note: some features could be postponed during implementation so versioning isn't final. A2/B1 means that simple table implements feature in A2 version and extendedTable has it planned to B1.

The next step is to modify the "+" to marks with versions. This should be done after complexity review and estimations.

Features Descriptions (CONSIDER THAT NAMING COULD BE CHANGED)

Features Disablement/Configuration

     This requirement is most popular among the community. It should be possible to turn off/on any advanced feature which will be available by deatult like for example resizing, reordering, built-in menus, selection and so on.

Two situations:

• common way "works if defined". like col/row spans. good from the beggining.
• Ability to resize the columns. Works by default. but attribute (like allowResize) should present at dataTable in order to turn off.

Configuration:

We need to provide the way to configure any complex feature in details.

E.g.:

• One table scroll could be availalbe and the second isn't.
• Built-in Menu items disablement/rendered condition, and content for sure  should be possible to be easilly changed/internationalized/etc.. E.g. even if sorting on the table columns present and turned on - it's not directly means that built-in menu should always contains sorting menuItems. Addition of custom user controls also should be possible.

Table Scrolling

Common points

As it was mentioned before we should provide possibility to show:

• table without scrols
• table with vertical OR horizontal scroll
• table with both scrolls
• auto mode for scrolls (if this reasonable/possible?/A2) Behavior like overflow:auto.              
  • https://jira.jboss.org/jira/browse/RF-5778

Ajax Scrolling

• new clientRows attribute should be introduced in order to use Ajax scrolling     
  • attribute should be defined with number of rows to be loaded to client
  • if rows not defined or defined and clientRows less than rows - ajax loading activated.

Columns Resizing

• current functionality - when the resizing making column wider causes all the other cells moved to right and horizontal scroll to appear. Decreasing some columns - caused all the other column after that to be moved to the left and just empty space to appears(but main header/footer - has defined size so could be wider than summ of the columns).        
  • no fake cells should be visible.
• proposed second mode - resizing with auto-fit feature. Horizontal - scroll not used and all the column on the right resized in order to fit width. (for A2?)
• proposed third mode - enlarging and reducing the column makes table itself to be enlarged/reduced(for A2?)

So, resizeMode attribute should be added to table and has three values - "scroll", "autofit","tableResize"(third name TBD)

• event columnresize should be fired after resize complete.
• boolean attribute resizeable should present on the column in order to turn the resizability on/off
• It should be possible to store columns sizes in some state object(e.g. I could need to persist some preferences for concrete users)

Columns Reordering

• Columns reordering should be available using drag and drop the headers of the columns one to another                 
  • after the user drop one column to another - dropped one should be placed before drop target column.                 
    • TBD - revise the approach. Maybe small drop zones near the column headers borders more convinient?
  • if we not change approach to dropzones near borders - headers should be highlighted on hovering with dragged column.      
    • It could be done by defining classes for that state, or by using additional events. (e.g. something like dropOver, dropOut)
• It should be optionally enabled for the table using table's allowColumnsReordering  bolean attribute.
• It should be possible to store new columns order in some state object(e.g. I could need to persist some preferences for concrete users)
• client side event columndragstart(just after drag occured), columndrop(after drop occured and cancelable), columnreorder(after reordering complete) should be fired on resize operations.

Collapse/expand for subtables

• expandMode attribute of the subtable will defines if the operations should be client, ajax or server ones. If not defined or defined with any other value - subtable will not be expandable.
• expanded attribute of the subtable should defines current state.
• <rich:tableToggleControl/> component should be created to encode special column control with expand collaspe states
  • it should have type (button/link) and expandLabel/collapseLabel attributes to define states representations.
  • additionally it should provide facets to define representation in expanded state and collapsed state if link and button are not suitable options.

Usage

 
<r:table>
     <r:column>
          <tableToggleControl for="subtable2" type="button" expandLabel="+" collapseLabel="-"/>

     </r:column>
     <r:column>
          <tableToggleControl for="subtable3" type="link" expandLabel="+" collapseLabel="-"/>

     </r:column>
     <r:column>
          <tableToggleControl for="subtable1">
               <f:facet name="expand">
                    <img src="plus.gif">
               </f:facet>
               <f:facet name="collapse">
                    <img src="minus.gif">
               </f:facet>
          </tableToggleControl>

     </r:column>





     <subtable expanded="#{tableVar.expanded}" expandMode="ajax" id="subtable1">
          ...
     </subtable>

 
     <subtable expanded="#{tableVar.expanded}" expandMode="client" id="subtable2">
          ...

     </subtable>
 
     <subtable expanded="#{tableVar.expanded}" expandMode="server" id="subtable3">
          ...
     </subtable>

</r:table>
 

<brainstorming> not for nearest impl

     we could think in future how to support just master-table row events to expand collapse subtables like:

<subtable expanded="#{tableVar.expanded}" expandMode="client" expandRowEvent="click" collapseRowEvent="click">

...

...

</subtable>

subtable will be expanded andcollapsed by click on the row from the table

<subtable expanded="#{tableVar.expanded}" expandMode="client" expandRowEvent="mouseover" collapseRowEvent="mouseout">

...

...

</subtable>

subtable will be expanded and collapsed when mouse overs table row and when mouseout occurs.

<brainstorming>

Column Menus - NOT FOR A2

Theme for separate discussion. We should provide the way to make really customizable menu. Current extendedDataTable implementation does not looks good and many customers just turning it off at all because can't customize according to the requirements. Thoughts:

• Should consist of defined items only. As described above it should be possible to remove some item from the menu even if corresponding functionality is present on the table.
• Custom items should be possible to be added.
• Order of the items should be configurable.
• ...continue

The first idea of simplest  implementation based on table JS API planned to be implemented:

<rich:ddmenu label="V">

     <rich:menuItem value="Hide Column" onclick="{rich:component('table')}.hideColumn('columnId')"/>

     //could be rich:element or rich:clientId instead columnId

</rich:ddmenu>

<rich:dataTable... id="table">

    <rich:column ... menu="columnddmenu" id="column" id="columnId">

          ...

    </rich:column>

</rich:dataTable>

But in that case the problem of hardcoded ids occurs and

• The menu is not really reusable should be created for every column (not acceptable at all)
• Problem of dynamic columns and ddmenus to be attached to them appears

Some improvement:

<rich:dataTable... id="table">

    <f:facet name="menu">

          <rich:ddmenu label="V">
                <rich:menuItem value="Hide Column" onclick="??"/>
          </rich:ddmenu>

    </f:facet>

    <rich:column ... id="column" id="columnId">

          ...

    </rich:column>

</rich:dataTable>

As you could see there we will define just one menu which could be used by every column. But there I have the problem of how to define operation iniside the menu item and how the column identification parameters will be passed to the menu(not important for internal operations like hide/sort/group and could be passed transparently but some custom user defined menuItems should know which column menu was activated in their click handler).

So need to continue investigation.

Customizable built-in statuses

• Current extendedDataTAble status is what i'm talking about
• Should be optional
• Should be possible to change this simple image with any content. (e.g. using facet)
• Should be possible to activate on some user ajax calls. (e.g. external sorting call)                 
  • should be done via client side API                  
    • $('tableId').showSplash();
    • $('tableId').hideSplash();

Selection(different modes e.g. keyboard free) - After A2

There should be next modes of selection mode option:

• none - selection turned off
• single - current standard for extended and scrollable table
• multiple - current standard for extended and scrollable table
• multipleKeyboardFree (need to be named better). Option allows multiple selection without using CTRL and SHIFT controls usage. Every next click at any row - reverts it's selection and do not reset other rows selection state.

Client Side API

Table:

1. $('table').sort(columnId,[direction],[isClear]) - sorts the table by single column, if direction not defined - just reverts to opposite. if isClear passed as true - all previous sorting cleared, in other case sorting by the column just append to current.
2. $('table').clearSorting() - clears all the sorting in table
3. $('table').filter(columnId, filterValue, isClear) - filters the table by single column using filter value passed. If isClear passed as true - clears previous filtering in other case - just appends to current filtering.
4. $('table').clearFiltering() - clears all the sorting in table
5. $('table').switchSubtable(subtableId) - reverts subtable state

    

6. $('table').expandAllSubtables() - expands all subtables
7. $('table').collapseAllSubtables() - collapse all subtables
8. $('table').moveColumn('columnId','newPosition') - moves the column to defined position
9. $('table').getColumnPosition('id') - returns the position of column
10. $('table').resizeColumn('columnId',newSize) - resizes given column
11. TBD?

dataScroller - all 3.3.x api methods should be supported(switchToPage(page), next(), prev(), first(), next()).

Pagging Support

Common:

• pagging should be done using datascroller component
• datascroller component should be possible to use inside(in header/footer) and outside(using for) the table component.
• pagging should be supported for table and all nessted subtables
• if pagging used in EDT together with ajax loading - ajax loading performed for rows from (current page * rows) to ((currentPage+1) * rows)

Exceptional cases:

• if switched page not present in table(if model changed and reduced) - the last page should be set     
  • warning should be logged

related issue

Filtering Feature

Differences from 3.3.x:

• filterBy should be removed from the column. We introducing new filterVar attribute on the table which will allow to unify built/external filtering definitions(to define built-in filtering using the same filterExpression definitions).

<table var="prop" filterVar="fprop">
<column filterExpression="#{fn:contains(fprop, prop.test)}" [filterValue="#{bean.foo}"]>
// current filter value from built-in control could be stored under filterValue binding
     #{prop.test}
</column>
<table>

<table var="prop" filterVar="fprop">
<column filterExpression="#{fn:contains(fprop, prop.test)}" filterValue="#{user.name}">
     #{prop.test}
</column>
<column filterExpression="#{fn:contains(#{user.email}, prop.test2)}">
     #{prop.test2}
</column>
// both definitions similar
<table>

• Instead of filterMethod usage developer should use filter attributde which should be pointed to object which implements Filter(naming could be changed) interface which defines accept method.

<column filter="#{acceptor}" filterValue="#{user.name}">
     #{prop.test}
</column>

 

@Name("acceptor")
class A implements Filter {
  boolean accept(Object o);
}

• as we removed filterBy - we have no property which defines if the default controls will be generated. So we will introduce filterControls (naming could be changed) attribute. It will have two values currently (input, none) and could be extended with selects for exampel in future.

Sorting Feature

Currently no difference with 3.3.x are planned except built-in controls which could be optionally implemented to A2

"noData" facet

Facet to be rendered if collection returned is empty.

• It should be supported by DT, EDT and subtable components.
• noData attribute should be added to simply define text without using facet.

Features to be dropped/postponed to future

There we will collect the features which we will decide to postpone.

External links

1. RichFaces Planning JIRA Issue