flowpack/listable

Tiny extension for listing things

3.6.0 2023-10-09 17:13 UTC

Requires

• neos/neos: ^3.3 || ^4.0 || ^5.0 || ^7.0 || ^8.0 || dev-master

Replaces

• sfi/listable: v0.1

MIT

README

This Neos package solves one problem: help you list any nodes in Fusion. The idea is very simple: you often need to display list of things (e.g. news, articles etc), and the concern of listing items should better be separated from the concern of rendering items. This package provides a solid foundation for listing, while allowing you to take care of rendering stuff on your own.

TL;DR

1. Install the package with composer: composer require flowpack/listable Here it is on packagist.
2. If you want a paginated list, use Flowpack.Listable:PaginatedCollection.
3. If you just want a simple list, use Flowpack.Listable:Collection (or just Neos.Fusion:Collection!).
4. If you need a list with a header and an archive link, wrap you list into Flowpack.Listable:List
5. For each of your nodetypes create a new Fusion object of type NodeTypeName + '.Short', or manually define a rendering object.
6. Rely on public API keys when overriding settings.

Fusion objects

Keys documented here are considered public API and would be treated with semantic versioning in mind. Extend all other properties at your own risk.

Flowpack.Listable:Collection

This object is just a simple convienince wrapper around Neos.Fusion:Collection, use it if you want to save a few keystrokes. It wraps the list with UL and LI tags with a provided name and also set Flowpack.Listable:ContentCaseShort as a default for itemRenderer.

Configuration options:

Example:

prototype(My.Custom:Object) < prototype(Flowpack.Listable:Collection) {
  collection = ${q(site).find('[instanceof Something.Custom:Here]').sort('date', 'DESC').slice(0, 6).get()}
  listClass = 'MyList'
  itemClass = 'MyList-item'
}

It would use the object Something.Custom:Here.Short for rendering each item.

Make sure to correctly configure the cache.

Flowpack.Listable:PaginatedCollection

This object allows you to paginate either ElasticSearch results, FlowQuery result objects or pure Node arrays.

Configuration options:

When used with ElasticSearch, build the query, but don't execute it, the object will do it for you:

prototype(My.Custom:Object) < prototype(Flowpack.Listable:PaginatedCollection) {
  collection = ${Search.query(site).nodeType('Something.Custom:Here').sortDesc('date')}
  itemsPerPage = 12
  prototype(Flowpack.Listable:Collection) {
    listClass = 'MyPaginatedList'
    itemClass = 'MyPaginatedList-item'
  }
}

If you have additional URL parameters (e.g for a date filter) you have to register the argument and change the cache entryDiscriminator in order work accordingly. HINT: Do not forget to register a corresponding route for your custom argument.

prototype(My.Custom:Object) < prototype(Flowpack.Listable:PaginatedCollection) {
  ...

  prototype(Flowpack.Listable:PaginationParameters) {
    date = ${request.arguments.data}
  }

  @cache {
    entryDiscriminator = ${request.arguments.currentPage + request.arguments.date}
  }

}

This object is configured by default to dynamic cache mode for pagination to work. All you have to do is add correct entryTags and you are all set.

Flowpack.Listable:List

There's often a need to render a list with a header and an archive link. This object takes your list and wraps it with just that.

Configuration options:

Example:

prototype(My.Custom:Object) < prototype(Flowpack.Listable:PaginatedCollection) {
  @process.list = Flowpack.Listable:List {
    listTitle = 'My List'
    archiveLink = '~/page-path-or-identifier'
    archiveLinkTitle = 'See all news'
  }
  collection = ${q(site).find('[instanceof Something.Custom:Here]').sort('date', 'DESC').slice(0, 6).get()}
}

Flowpack.Listable:Pagination

You can also use pagination standalone from the PaginatedCollection.

Configuration options:

FlowQuery Helpers you can use

filterByDate

Filter nodes by properties of type date.

filterByReference

Filter nodes by properties of type reference or references.

sortRecursiveByIndex

Sort nodes recursively by their sorting property.

Example:

${q(site).find('[instanceof Neos.Neos:Document]').sortRecursiveByIndex('DESC').get()}