heimrichhannot/contao-list-widget-bundle

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

1.3.0-alpha2 2024-03-04 15:49 UTC

Requires

• php: ^8.2
• ext-json: *
• contao/core-bundle: ^4.13 || ^5.0
• heimrichhannot/contao-ajax-bundle: ^1.0
• heimrichhannot/contao-utils-bundle: ^2.225 || ^3.0
• heimrichhannot/datatables: ^1.10
• heimrichhannot/datatables-additional: ^1.0
• symfony/http-kernel: ^3.4 || ^4.0 || ^5.0 || ^6.0

Replaces

• heimrichhannot/contao-list_widget: *

LGPL-3.0-or-later

• Heimrich & Hannot

README

This bundle 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 is used.

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

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

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

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)

Callbacks