Sorting and Filtering

Often we need to process a collection of ffNodes before outputting it. We might need to filter, sort, group and/or slice them.

For that purpose we can use "ffCollection", which takes a plain array of nodes and provides an API to apply filter- and sorting rules to it. \It also provides a framework to ease the implementation of front-end tools and the persistent storage in back-end to implement filter and sorting interfaces.

getting started

ffCollection is (currently) maintained as a separate plugin, so you need to get hold of it and put it in your plugin directory.

creation of a collection

In the context of a presenter, when we handle arrays of nodes we can replace ffNode::getChildren() with ffNodeCollection::fromParentNode(ffNode $ffNode). [add more use cases for collections, such as carts]

$collection = ffNodeCollection::fromParentNode($this->me);

$collection->sortByAttribute('date', 'desc');
$collection->filterByAttribute('date')->isMin('2022-01-01')->isMax('2022-01-31');
$collection->filterByMetadatum('state')->is('published');
$collection->filterByBabel('name')->contains('a');

foreach($collection as $node){
    // processed nodes
}

[full reference]

interaction

ffCollection provides some pre-build traits that you can include in your ffListeners for filtering and sorting.

Read Reactive Websites in the Concepts section, if you need to learn more about the concept of callers and listeners and how you can set up an internal API.

file filterListener.php

class filterListener extends ffListener{
    use filterListenerActions
}

file sortListener.php

class sortListener extends ffListener{
    use sortListenerActions
}

file filterAPI.js

ffCaller.add({
  hook:'data-filter-api'
});

file template.html

<button
 data-filter-api='{"action":"set", "key":"meta--state", "is":"published"}'
>show published only</button>

<button
 data-sorter-api='{"action":"sortBy", "key":"babel--name--asc"}'
>A to Z</button>

persistence

$collection = ffNodeCollection::fromParentNode($this->me);
$storage = new filterStorage();
$collection->loadFilter($storage);

storage takes an optional id/namespace as argument to identify the storage.

$collection = ffNodeCollection::fromParentNode($this->me);

// stored filter will be unique for every path
$filterStorage = new filterStorage($this->me->get('trace'));
$collection->loadFilter($filterStorage);

// sort storage will be shared across website
$sortStorage = new sortStorage('foo');
$collection->loadSorter($sortStorage);

23 September 2024