This new method groupMap() is available in all CollectionResult objects (like QueryResult and NavigatorResult).

CollectionResult.groupMap(function[, desc])

This method returns a sorted map keyed by the return value of a user defined function where its value is a list of TMLContext objects evaluating to the same key.

If the return value of the function is null, the entry is ignored and not contained in the resulting map. This feature can be used to filter entries.

The optional boolean parameter "desc" can be used to retrieve a reversed entry set.

Sample:

WGA.nav("name:home").children().groupMap(function(doc){
    return doc.MODIFIED.year + 1900
})

The map in this example is keyed by the creation year of the documents.

This new method can be used as alternative for <tml:goupchange> using nested <tml:foreach>s. (See also #00005509: iterating through entrysets)

Sample:

<tml:script>
    _map = WGA.nav("name:home").children().groupMap(function(doc){
        return doc.MODIFIED.year + 1900
    }, true)
</tml:script>
<tml:foreach item="_map" currentvalue="_entry">
    <h2><tml:item name="_entry.key" format="0"/></h2>
    <tml:foreach item="_entry.value" wrap="ul">
        <li><tml:meta name="title"/></li>
    </tml:foreach>          
</tml:foreach>

Returns something like

<h2>2022</h2>
<ul>
    <li>Products</li>
    <li>Services</li>
</ul>           
<h2>2020</h2>
<ul>
    <li>References</li>
</ul>           
<h2>2019</h2>
...

The equivalence using <tml:groupchange> is not easy to produce because you carefully have to maintain your <ul>s ...

<tml:foreach ... sortexpression="MODIFIED" sortorder="descending">

    <tml:groupchange id="gc" expression="MODIFIED.year">
        <tml:case isfirstloop="false">
            </ul>
        </tml:case>
        <h2><tml:meta name="MODIFIED" format="yyyy"/></h2>
        <ul>
    </tml:groupchange>

    <li>...</li>

    <tml:case islastloop="true">
        </ul>
    </tml:case>

</tml:foreach>

Note:

To generate this group-map the system has to iterate over the complete result set. This therefore should not be used with large result sets.