concrete5 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).
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
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
The query should return only the record identifier: the full instance of the involved entities will be created by the
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
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
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
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
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
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.