PHPackages                             heimrichhannot/contao-list-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Search & Filtering](/categories/search)
4. /
5. heimrichhannot/contao-list-bundle

ActiveContao-bundle[Search & Filtering](/categories/search)

heimrichhannot/contao-list-bundle
=================================

This bundle offers a generic list module to use with arbitrary contao entities containing standard list handling like pagination, sorting, and filtering.

1.54.0(1y ago)37.4k[1 issues](https://github.com/heimrichhannot/contao-list-bundle/issues)[5 PRs](https://github.com/heimrichhannot/contao-list-bundle/pulls)7LGPL-3.0-or-laterPHPPHP ^7.4 || ^8.0CI failing

Since Feb 27Pushed 1y ago5 watchersCompare

[ Source](https://github.com/heimrichhannot/contao-list-bundle)[ Packagist](https://packagist.org/packages/heimrichhannot/contao-list-bundle)[ Docs](https://github.com/heimrichhannot/contao-list-bundle)[ RSS](/packages/heimrichhannot-contao-list-bundle/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (28)Versions (278)Used By (7)

Contao List Bundle
==================

[](#contao-list-bundle)

[![](https://camo.githubusercontent.com/d6778793b0ca63605e83d93404c8f00d59b654978d113068015ab5635295b41e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6865696d7269636868616e6e6f742f636f6e74616f2d6c6973742d62756e646c652e737667)](https://packagist.org/packages/heimrichhannot/contao-list-bundle)[![](https://camo.githubusercontent.com/d11490ce452b4d98b93b8ae197aa9f7b86303186b4fc850259524f7c2f908446/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6865696d7269636868616e6e6f742f636f6e74616f2d6c6973742d62756e646c652e737667)](https://packagist.org/packages/heimrichhannot/contao-list-bundle)[![Build Status](https://camo.githubusercontent.com/5ba6de3b32c0582f788d1b05f7db8db51067a3bc6d8d3e2d9c1578f0f096f671/68747470733a2f2f7472617669732d63692e6f72672f6865696d7269636868616e6e6f742f636f6e74616f2d6c6973742d62756e646c652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/heimrichhannot/contao-list-bundle)[![Coverage Status](https://camo.githubusercontent.com/5efbb7454729798b5898f8ce7e2dd4ff821222df4e9d242e17da03d5e1a20217/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6865696d7269636868616e6e6f742f636f6e74616f2d6c6973742d62756e646c652f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/heimrichhannot/contao-list-bundle?branch=master)

This bundle offers a generic list module to use with arbitrary contao entities containing standard list handling like pagination, sorting, and filtering.

It makes it possible to generate lists not only for events, news or faq's but with every DCA you like.

Features
--------

[](#features)

- generic list module to use with arbitrary contao entities
- support all form of standard list handling like pagination, sorting, filtering
- works together with filter bundle
- inheritable list configurations
- template are build in twig
- support for [Encore Bundle](https://github.com/heimrichhannot/contao-encore-bundle)

Usage
-----

[](#usage)

### Install

[](#install)

1. Install via composer (`composer require heimrichhannot/contao-list-bundle`) or contao manager
2. Update your database

Recommendations:

- use this bundle together with [Reader Bundle](https://github.com/heimrichhannot/contao-reader-bundle).
- use [Encore Bundle](https://github.com/heimrichhannot/contao-encore-bundle) for managing your frontend assets

### Usage

[](#usage-1)

> HINT: You can do the following steps for a basic list setup also in an interactive command. Simply run `vendor/bin/contao-console huh-list:make` in your contao root.

1. Setup a filter (see [Filter Bundle](https://github.com/heimrichhannot/contao-filter-bundle) setup)
2. Create a list config (System -> List config)
    - To add list elements like images, videos, slider etc, add list config elements (see Concepts -> List config elements for explanation)
    - Recommendation: for better performance, check "Limit formatted fields" in your list configuration and select only the fields you really need to have formatted
3. Create a list frontend module and output it, where you like it

Concepts
--------

[](#concepts)

### Inheritable list configuration

[](#inheritable-list-configuration)

Since list configuration can be lots of data sometimes we decided to outsource it into a dedicated DCA entity. These entities can be assigned to one or even multiple list modules in a reusable way.

In addition it's possible to create list configs that inherit from other list configs. Hence overriding a single option while keeping everything else is possible.

### The Item class

[](#the-item-class)

Every database record output in a list (e.g. an event) is modelled and wrapped by the `Item` class. The concrete class is `DefaultItem`. You can imagine the item as a kind of ORM (object-relational-mapping).

The most important properties of an item are the arrays `raw` and `formatted` which also can be iterated in the list item template:

- `raw`: contains the raw database values
- `formatted`: contains the formatted representation of the raw values

Example: Let's say a database record has a field `startDate` which holds a unix timestamp of the date chosen in the backend. Then `raw` contains this unix timestamp and `formatted` contains the pretty printed date according to the `dateFormat` set in the contao settings, i.e. "2020-09-12".

The list bundle uses the method `FormUtil::prepareSpecialValueForOutput()` in [heimrichhannot/contao-utils-bundle](https://github.com/heimrichhannot/contao-utils-bundle)for handling special values. It supports a wide range of types of special values:

- date/time fields
- arrays
- fields with `options`, `options_callback` and entries in the DCA's `reference` key
- binary fields (files, images, ...)
- ...

You can access both of these arrays in your list item twig template as you normally would in twig:

```
{% for field, value in raw %}
{% endfor %}

{% for field, value in formatted %}
{% endfor %}
```

**CAUTION:** By default all values of a database record are formatted and accessible in the item template. As you can imagine if some of the fields have thousands of options, the process of formatting can take some time and can reduce the peformance of your website. **Hence you always should limit the formatted fields and only format these you really need.** You can adjust that in the list configuration (field `limitFormattedFields`).

For convenience reasons you can also access the field values like so in your twig template:

```
{{ fieldname }}
```

If you configured the field `fieldname` to be formatted, it will contain the formatted value. If not, the raw one. If it's formatted, you can still access its raw value by using:

```
{{ raw.fieldname }}
```

### List config elements

[](#list-config-elements)

Every list config can have one or more list config elements. These are designed to specify things that can occur multiple times (e.g. because there are many fields of one type).

Currently available list config element types:

TypeDescriptionimageConfigure the output of one or more image fields separately (image size, placeholder handling, ...)tagsOutput one or more tag fields based on [codefog/tags-bundle](https://github.com/codefog/tags-bundle).related itemsOutput related items based on given tags (needs [codefog/tags-bundle](https://github.com/codefog/tags-bundle)) or categories (needs [heimrichhannot/contao-categories-bundle](https://github.com/heimrichhannot/contao-categories-bundle)).#### Image

[](#image)

You can add images either as formatted value of, if you also like to have additional features like image size processing or automatic placeholders if no image is set, you can use the *image list config element*.

After the configuration you can output it as follows in your item template:

```
{% if images|default and images.myImage|default %}
    {{ include('@HeimrichHannotContaoUtils/image.html.twig', images.myImage) }}
{% endif %}
```

**IMPORTANT:** Note that by default the generated picture elements are added to an array called `images`. If your DCA contains a field with the same name, you need to specify a different container name like e.g. `resizedImages`(using `overrideTemplateContainerVariable`).

Documentation
-------------

[](#documentation)

[Developer documentation](docs/developers.md)

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance33

Infrequent updates — may be unmaintained

Popularity25

Limited adoption so far

Community23

Small or concentrated contributor base

Maturity88

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 90% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~9 days

Recently: every ~68 days

Total

266

Last Release

516d ago

PHP version history (5 changes)1.0.0-betaPHP ~7.1

1.0.0-beta2PHP ^7.1

1.40.0PHP ^7.1|^8.0

1.40.1PHP ^7.1||^8.0

1.51.0PHP ^7.4 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/28ad3224d8727b622ebd229840eea6b9dbcb83eb0bd609e6ce65b614830ff538?d=identicon)[digitales@heimrich-hannot.de](/maintainers/digitales@heimrich-hannot.de)

---

Top Contributors

[![koertho](https://avatars.githubusercontent.com/u/12064642?v=4)](https://github.com/koertho "koertho (117 commits)")[![vvohh](https://avatars.githubusercontent.com/u/75325799?v=4)](https://github.com/vvohh "vvohh (7 commits)")[![Defcon0](https://avatars.githubusercontent.com/u/1485098?v=4)](https://github.com/Defcon0 "Defcon0 (2 commits)")[![davidsky7](https://avatars.githubusercontent.com/u/89909249?v=4)](https://github.com/davidsky7 "davidsky7 (1 commits)")[![AlexejKossmann](https://avatars.githubusercontent.com/u/32612134?v=4)](https://github.com/AlexejKossmann "AlexejKossmann (1 commits)")[![mirkogleibe](https://avatars.githubusercontent.com/u/850300?v=4)](https://github.com/mirkogleibe "mirkogleibe (1 commits)")[![salteax](https://avatars.githubusercontent.com/u/46114448?v=4)](https://github.com/salteax "salteax (1 commits)")

---

Tags

listcontao

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/heimrichhannot-contao-list-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/heimrichhannot-contao-list-bundle/health.svg)](https://phpackages.com/packages/heimrichhannot-contao-list-bundle)
```

###  Alternatives

[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[codefog/contao-haste

haste extension for Contao Open Source CMS

42650.8k139](/packages/codefog-contao-haste)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[shopware/storefront

Storefront for Shopware

684.2M148](/packages/shopware-storefront)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)