Item Lists

This is a community-contributed tutorial. This tutorial is over a year old and may not apply to your version of Concrete CMS.
Jun 4, 2017

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).


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.

Recent Tutorials
Using the Concrete Migration Tool Addon
Apr 27, 2023

How to use the Concrete CMS Migration Tool

How To Add Page Last Updated To Your Concrete CMS Pages
Mar 7, 2023

Concrete CMS has a page attribute you can add to a global area called "Page Date Modified." Here's how to add it

How To Exclude Subpages from Navigation
Dec 24, 2022

How to exclude subpages from navigation - useful for a news or blog link in your main navigation where you don't want all the subpages to appear in a drop down menu.

How Can I Change The Maximum Size Of Uploaded files
Dec 13, 2022

This tutorial explains how to update your php settings.

Updating Concrete Themes from Version 8 to Version 9
Nov 24, 2022

This tutorial covers commonly encountered issues when upgrading a Concrete CMS theme from version 8 to version 9

Transferring ownership of an add-on and a theme
Nov 15, 2022
By katzueno.

If you encounter a Concrete CMS add-on or theme that you love but not being maintained, you may want to ask the author to help or take over the add-on or theme. Here is the quick step-by-step guide of how to transfer the ownership.

Was this information useful?
Thank you for your feedback.