PHPackages                             heimrichhannot/contao-list\_widget - 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. [Utility & Helpers](/categories/utility)
4. /
5. heimrichhannot/contao-list\_widget

ActiveContao-module[Utility & Helpers](/categories/utility)

heimrichhannot/contao-list\_widget
==================================

This simple module offers an input type for displaying a list of entities definable by a callback function.

2.2.0(4y ago)05.6k2LGPL-3.0-or-laterPHPPHP ~5.4 || ~7.0 || ^8.0

Since Dec 13Pushed 4y ago4 watchersCompare

[ Source](https://github.com/heimrichhannot/contao-list_widget)[ Packagist](https://packagist.org/packages/heimrichhannot/contao-list_widget)[ Docs](https://bitbucket.org/heimrichhannot/contao-list_widget)[ RSS](/packages/heimrichhannot-contao-list-widget/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (1)Dependencies (6)Versions (15)Used By (2)

Contao List Widget
==================

[](#contao-list-widget)

> For contao 4 please use [List Widget Bundle](https://github.com/heimrichhannot/contao-list-widget-bundle)

This simple module offers functionality for displaying a list in the Contao backend (either as a dca field or in a backend module).

For visualization the javascript library [DataTables](https://github.com/DataTables/DataTables) is used.

[![alt text](./docs/screenshot.png "Demo in the backend")](./docs/screenshot.png)

Features
--------

[](#features)

- inputType "listWidget" for usage as a dca field
- convenient functions for integrating a list in your backend module
- the list can display either model data or even arbitrary arrays
- support for datatables javascript library
    - filter the table
    - search the table
    - sort the table
- support for ajax reloading data using datatables -> currently only working for contao models since SQL-commands like LIMIT are used

### Technical instructions

[](#technical-instructions)

#### Usage as a widget in a dca field

[](#usage-as-a-widget-in-a-dca-field)

Use the inputType "listWidget" for your field.

```
'someField' => [
    'label'     => &$GLOBALS['TL_LANG']['tl_my_dca']['someField'],
    'exclude'   => true,
    'inputType' => 'listWidget',
    'eval'      => [
        'listWidget' => [
            'ajax'                   => true,
            'ajaxConfig'             => [
                'load_items_callback' => ['SomeClass', 'loadItems']
            ],
            'header_fields_callback' => function ()
            {
                $arrHeaderFields = [];

                foreach (['academicTitle', 'additionalTitle', 'gender', 'lastname', 'email'] as $strField)
                {
                    $arrHeaderFields[$strField] = \HeimrichHannot\Haste\Dca\General::getLocalizedFieldname($strField, 'tl_dca');
                }

                return $arrHeaderFields;
            },
            'table'                  => 'tl_dca'
        ]
    ]
]

```

#### Usage in a module

[](#usage-in-a-module)

Add the following code e.g. in the generate() method of your BackendModule:

```
static::$arrListConfig = [
    'identifier' => 'module_' . $this->id,
    'table' => 'tl_dca',
    'ajax' => true,
    'ajaxConfig' => [
        'load_items_callback' => function($arrConfig, $arrOptions = [], $objContext = null, $objDc = null) {
            return $this->loadItems($arrConfig, $arrOptions, $objContext, $objDc);
        },
        'prepare_items_callback' => function($objItems) {
            return $this->parseNewsletters($objItems);
        },
    ],
    'columns' => static::getColumns(),
    'language' => static::getLanguage()
];

static::$arrListConfig = ListWidget::prepareConfig(static::$arrListConfig, $this);

ListWidget::initAjaxLoading(static::$arrListConfig);

```

Call this in your module's compile method:

```
ListWidget::addToTemplate($this->Template, static::$arrListOptions);

```

Copy the content of list\_widget.html5 into your module's template.

#### Example load\_items\_callback

[](#example-load_items_callback)

Here you can see an example for overriding the core behavior of loadItems():

```
public static function loadItemsNew($arrConfig, $arrOptions = [], $objContext = null, $objDc = null)
{
    // set an initial filter using the contao options array
    $arrOptions = [
        'table'   => $arrConfig['table'],
        'columns' => $arrConfig['columns'],
        // filtering
        'column'  => 'pid',
        'value'   => $objDc->id
    ];

    // the rest of the function should also be called
    return ListWidget::loadItems($arrConfig, $arrOptions, $objContext, $objDc);
}

```

### Config (same structure for DCA -> eval -> listWidget and shortcut functions)

[](#config-same-structure-for-dca---eval---listwidget-and-shortcut-functions)

NamePossible valueDescriptionidentifierstringNeeded for distinguishing requests from multiple list widget implementations, e.g. `'module_' . $this->id`header\_fieldsarrayMust return an array containing the header fields. The keys must match the keys of the arrays/objects in items/items\_callback.header\_fields\_callbackcallback array, function closureMust return an array containing the header fields. The keys must match the keys of the arrays/objects in items/items\_callback.itemsarrayMust return an array containing the items to be displayed. The item keys must match those in header\_fields/header\_fields\_callback.items\_callbackcallback array, function closureMust return an array containing the items to be displayed. The item keys must match those in header\_fields/header\_fields\_callback.tablestring (e.g. "tl\_dca")This value is needed for useDbAsHeader and ajax handlinguseDbAsHeaderbooleanSet to true if the header should contain all fields of a certain database entity ("table" is used)templatestringSpecify a custom templatelanguagearraySpecify custom localizations (see ListWidget::getLanguage() for details)language\_callbackcallback array, function closureSpecify custom localizations (see ListWidget::getLanguage() for details)ajaxbooleanSet to true if ajax reloading should take place (no need for items\_callback in this case)ajaxConfig -> load\_itemsarrayOverride this if custom model options or methods are needed (see ListWidget::loadItems() for details)ajaxConfig -> load\_items\_callbackcallback array, function closureOverride this if custom model options or methods are needed (see ListWidget::loadItems() for details)ajaxConfig -> prepare\_itemsarrayOverride this if custom data preparation is needed (see ListWidget::prepareItems() for details)ajaxConfig -> prepare\_items\_callbackcallback array, function closureOverride this if custom data preparation is needed (see ListWidget::prepareItems() for details)### Callbacks

[](#callbacks)

NameArgumentsExpected return valueDescriptionheaderFields\_callback$objDc, $arrDca, $objWidgetarray containing field and label pairs (`['field1' => 'fieldLabel1', 'field2' => 'fieldLabel2', ...]`)This callback must return the headerFields to be displayed in the list. Array keys need to be the keys in items\_callback (see list\_widget.html5 for explanation).items\_callback$objDc, $arrDca, $objWidgetarray of entity arrays (`[['field1' => 'value1', 'field2' => 'value2'], ...]`)This callback must return the items to be displayed in the listload\_callback$arrOptions, \[\], $objDc, $arrDca, $objWidgetdata array (see ListWidget::loadItems for more details)Override this method if custom model options or methods are neededprepare\_items\_callback$objItems, $arrListOptions, $arrOptions, $objDc, $arrDca, $objWidgetdata array (see ListWidget::prepareItems for more details)Override this method if custom data preparation is needed

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 100% 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 ~132 days

Recently: every ~360 days

Total

14

Last Release

1761d ago

Major Versions

1.0.3 → 2.0.02017-03-06

PHP version history (3 changes)1.0.0PHP ~5.6 || ^7.0

2.1.2PHP ~5.4 || ~7.0

2.2.0PHP ~5.4 || ~7.0 || ^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 (2 commits)")

---

Tags

typelistcontaobackendinputinputtype

### Embed Badge

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

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

###  Alternatives

[terminal42/contao-inserttags

Contao extension to create custom insert tags.

1050.8k](/packages/terminal42-contao-inserttags)

PHPackages © 2026

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