O componente group foi desenvolvido para que as listas possam ser agrupadas na view sem muita codificação. O objetivo desse componente é agrupar uma determinada lista por algum campo, de maneira que esses valores possam ser acessíveis via expression language.

Esse componente agrupa listas dos tipos que implementam a interface java.util.List. Para agrupar uma lista deve-se indicar o campo que indica o agrupamento através do atributo groupBy.

Atributos

Atributo "var"

Ao indicar o atributo var, a variável criada, possui 2 valores:

• key - representa o valor do campo indicado no groupBy
• value - representa o valor agrupado

Exemplo de Utilização

Para os exemplos demonstrados vamos considerar as classes abaixo que irão representar pessoa, cidade, estado e país, essas classes irão representar o modelo a ser agrupado.

Person.java

public class Person {

    private String name;
    private City city;
	
    //getters and setters
}

City.java

public class City {

    private String name;
    private State state;
	
    //getters and setters
}

State.java

public class State {

    private String name;
    private Country country;

    //getters and setters	
}

Country.java

public class Country {

    private String name;

   //getters and setters
}

Exemplo 1 - Agrupando uma lista de pessoas por cidade

Considerando as classe Person.java, (que possui name e city) e City.java (que possui name), o exemplo abaixo mostra o uma lista de pessoa agrupada por Cidade:

<x:group value="#{groupComponentMB.people}" var="personGroup"   
         groupBy="city" rowIndexVar="index"  sortField="name"  
         itemSortField="name" itemSortField="descending" >  
    <h:outputText style="font-weight: bold" value="#{index+1} - #{personGroup.key.name}"/>  
    <p:separator/>  
    <p:dataTable value="#{personGroup.value}" var="person" rowIndexVar="indexPerson" >  
        <p:column>  
            <h:outputText value="#{index+1}.#{indexPerson+1}"/>  
        </p:column>  
        <p:column headerText="Name" >  
            <h:outputText value="#{person.name}"/>  
        </p:column> 
    </p:dataTable>  
    <br/>  
</x:group>     

Nesse exemplo ao acessar personGroup.key vamos obter uma instância de cidade, ou seja a cidade da iteração atual, e ao acessar personGroup.value obtemos uma lista de pessoas que pertencem a essa cidade.

O resultado o agrupamento acima, seria algo parecido com o mostrado na imagem abaixo, para cada cidade serão listadas as suas pessoas em um p:dataTable, perceba ainda que o atributo itemSortOrder foi definido como descending, assim os items (as pessoas) serão ordenadas de forma descrecente:

Exemplo 2 - Agrupando uma lista de pessoas por país e estado

Nesse exemplo, serão usados 2 vezes o componente group o primero irá agrupar por país e o segundo irá pegar o resultado do primeiro e agrupar por estado:

<x:group value="#{groupComponentMB.people}" var="personGroupCountry" 
         groupBy="city.state.country" rowIndexVar="indexCountry" itemSortField="name" >   
    <h:outputText style="font-weight: bold;font-size: 18px;font-size: 15px;" value="#{indexCountry+1} - #{personGroupCountry.key}"/>  	
    <p:separator/>  
    <x:group value="#{personGroupCountry.value}" var="personGroupState" 
             groupBy="city.state" rowIndexVar="indexState"  itemSortField="name">  
        <h:outputText style="font-style: italic;"  value="#{indexCountry+1}.#{indexState+1} - #{personGroupState.key}"/>  
        <p:separator/>  
        <p:dataTable value="#{personGroupState.value}" var="person" rowIndexVar="indexPerson" >
            <p:column>  
                 <h:outputText value="#{indexCountry+1}.#{indexState+1}.#{indexPerson+1}"/>  
            </p:column>  
            <p:column headerText="Name" >  
                 <h:outputText value="#{person.name}"/>  
            </p:column>                  
            <p:column headerText="City" >  
                 <h:outputText value="#{person.city.name}"/>  
	    </p:column>        
        </p:dataTable>  
        <br/>  
    </x:group>  
    <br/>  
</x:group>

Nesse exemplo ao acessar personGroupCountry.key vamos obter uma instância de país, ou seja o páis da iteração atual, e ao acessar personGroupCountry.value obtemos uma lista de pessoas que pertencem a esse país.

No segundo agrupamento temos personGroupState.key que será uma instância de estado e personGroupState.value que será as pessoas daquele estado, sendo assim tem 2 níveis de agrupamento, primeiro por país, depois por estado. O resultado do agrupamento acima seria algo parecido com o mostrado abaixo:

SortFunction

É possível definir uma função costumizável para a ordenação dos itens.

public int sortByCustom(Object o1, Object o2) {
   //return -1, 0 , 1 if o1 is less than, equal to or greater than co2
}

Na página, é necessário via EL o método de ordenação no atributo sortFunction:

<x:group value="#{groupComponentMB.people}" var="personGroupCountry" 
          groupBy="city.state.country" rowIndexVar="indexCountry"   
          sortFunction="#{countryMB.sortByCustom}"
          itemSortField="name" >   
 (..) 
</x:group>