Item lists

Concrete CMS offers a really powerful system to handle lists. It's used in many places inside the core: the member list page, the file list page, ...

This system can be used to persist ordering and searches, create paginated results, control complex queries with just a couple of lines of code, fine-tuning the data representation, ... and a lot more.

Let's assume that you want to build a package with handle handle is my_boats that lists boats in a dashboard page (you can get the full source code here).

We won't discuss here how you can create the package controller (manual), the dashboard single page (manual), and the Doctrine Entity called Boat (manual).

Ingredients

The item list system requires at minimum the following stuff:

• an Item List class that initializes the query and offers methods to filter the data
• a Column Set class that defines the columns to be shown
• a Search Controller, that coordinate the whole process

For an even more powerful system, you can optionally implement also:

• an Item class, that wraps every Boat entity and can, for instance, provide the CSS class of every result row
• a Result class, that defines your special Item class and can offer methods related to the whole result set.

The Item List

Let's consider the file packages/my_boats/src/Search/Lists/Boats.php.

The main purpose of this class is to define the database query that will be used to extract data (the createQuery method) and to offer the filters that can be applied to the result sets (the various filterBy... methods). The query should return only the record identifier: the full instance of the involved entities will be created by the getResult method). Another purpose of the ItemList class is to create a Pagination object (see the createPaginationObject method), that will be used to split the results in multiple pages.

You can also use this class to define the columns that users can sort by clicking the header cells, as well as the query string parameters used to represent the current page index, the currently sorting column and its order.

The Column Set

When we present the boats to the user, we need to define the columns to be shown, and we can define a custom way to present the data. This is the purpose of column sets. In the sample package, it's implemented in the packages/my_boats/src/Search/Columns/Sets/Boats.php file. There you can see that we define 3 columns, assign every column a key/identifier, a name, and the method to be called against the entity to get the value to be displayed. In case of special columns, you can create a custom column class: in out example we use a YesNoColumn that prints out boolean values as Yes or No .

Another purpose of the column sets is to define the default column to be used to sort the results.

The Search Controller

This controller is meant to control the process of reading the list state (that's persisted in a session variable as a StickyRequest instance), offers some data that can be useful (see the example getAllowedPaginationSizes and getDefaultPaginationSize methods), but above all it parses the content of the StickyRequest, apply the appropriate filters to the query and build the resulting object (see the search method).

The Result class

This is not strictly mandatory, but you'll almost always need to have some extra details that's not directly available from the underlying data you're showing (for instance, the CSS class of an item row). In order to be able to define such a custom item wrapper, you have to use a custom Result class: in our example it's the packages/my_boats/src/Search/Results/Boats.php class. This class should implement a getItemDetails methods which receives the entity instance (or what's returned by the getResult method of the Item List) and returns the final item wrapper that will be used when displaying the data.

The item wrapper

In our example, the Result class returns instances of the class defined in /packages/my_boats/src/Search/Results/Item/Boats.php. This entity wrapper class can then be used to build the final list, for instance by providing a custom CSS class for every result row.