Contao Multicolumnwizard Laravel Package

Getting Started

First Steps

1. Installation:

   • For Contao 4, use the MCW Bundle via Composer:

     composer require menatwork/contao-multicolumnwizard-bundle
     

   • For Contao 3, install via Composer:

     composer require menatwork/contao-multicolumnwizard
     

   • Enable the bundle in config/bundles.php (Contao 4) or include the autoloader (Contao 3).

2. Basic Setup:

   • Register the input type in config/autoload.php (Contao 4) or system/config/config.php (Contao 3):

     $GLOBALS['TL_CONFIG']['includeDCA'][] = 'system/modules/multicolumnwizard/dca.php';
     

3. First Use Case:

   • Define a multi-column field in a DCA (Data Container Array) to group related form inputs (e.g., filters, metadata, or conditional logic).
   • Example: Add a templateSelection field to tl_theme with columns for client OS and browser (as shown in the README).

Implementation Patterns

Common Workflows

1. Static Column Definitions:

   • Use columnFields to define fixed columns with nested input types (e.g., select, text, checkbox).
   • Example:

     'eval' => [
         'columnFields' => [
             'filter_date' => [
                 'inputType' => 'text',
                 'eval' => ['style' => 'width:100px'],
             ],
             'filter_status' => [
                 'inputType' => 'select',
                 'options' => ['active', 'inactive'],
             ],
         ],
     ],
     

2. Dynamic Columns via Callback:

   • Use columnsCallback to generate columns dynamically (e.g., fetch options from a database or API).
   • Example:

     'eval' => [
         'columnsCallback' => ['MyClass', 'getDynamicColumns'],
     ],
     

   • Implement getDynamicColumns() to return an array of column definitions:

     public static function getDynamicColumns()
     {
         return [
             'dynamic_field' => [
                 'inputType' => 'select',
                 'options' => self::getOptionsFromDatabase(),
             ],
         ];
     }
     

3. Drag-and-Drop Reordering:

   • Enable dragAndDrop to let editors reorder columns via GUI.
   • Example:

     'eval' => [
         'dragAndDrop' => true,
         'columnFields' => [...],
     ],
     

4. Conditional Logic:

   • Combine with Contao’s eval rules (e.g., mandatory, tl_class) to enforce validation or styling.
   • Example:

     'eval' => [
         'mandatory' => true,
         'tl_class' => 'w50',
     ],
     

5. Integration with Backend Modules:

   • Use the MCW in custom backend modules by extending BackendModule and injecting the field into your template.
   • Example:

     $this->Template->mcwField = $this->generateMultiColumnWizard('tl_my_table', 'my_mcw_field');
     

Advanced Patterns

1. Nested MCWs:

   • Embed a MCW inside another MCW column for hierarchical data (e.g., nested filters).
   • Example:

     'columnFields' => [
         'advanced_filters' => [
             'inputType' => 'multiColumnWizard',
             'eval' => [
                 'columnFields' => [...],
             ],
         ],
     ],
     

2. Data Persistence:

   • Serialize/deserialize MCW data using serialize()/unserialize() or JSON encode/decode for storage.
   • Example:

     $data = unserialize($record['my_mcw_field']);
     

3. Frontend Rendering:

   • Decode MCW data in templates to render dynamic content (e.g., display filters or metadata).
   • Example (Twig):

     {% set mcwData = data.my_mcw_field|serialize|json_decode %}
     {% for column, fields in mcwData %}
         {{ column }}: {{ fields.filter_date }}
     {% endfor %}
     

4. Validation:

   • Add custom validation via validate() in a DCA callback or use Contao’s built-in eval rules.
   • Example:

     'eval' => [
         'validate' => ['mcwCustomValidator'],
     ],
     

Gotchas and Tips

Common Pitfalls

1. Deprecated Dependencies:

   • Contao 4: Use the bundle (not the standalone package). The standalone package is for Contao 3.
   • Contao 3: Ensure DC_General is not required (removed in v3.3.14+).

2. Drag-and-Drop Issues:

   • If DnD fails, ensure:
     • dragAndDrop is set to true.
     • No JavaScript errors in the browser console (check Contao’s asset pipeline).
     • The field is saved at least once to initialize the DnD state.

3. Data Serialization:

   • MCW fields store data as serialized arrays. Avoid manual serialize()/unserialize() if using Contao’s ORM (e.g., Model::find() handles this automatically).
   • Tip: Use json_encode()/json_decode() for cleaner debugging:

     $decoded = json_decode(json_encode(unserialize($record['my_mcw_field'])), true);
     

4. Performance:

   • Avoid overly complex columnsCallback methods that query the database on every page load. Cache results or use lazy loading.
   • Tip: Pre-fetch dynamic options in a prepareDataContainer callback.

5. Contao 4 Compatibility:

   • The bundle requires Contao 4.4+. Test with the latest stable version.
   • Tip: Override bundle templates in vendor/menatwork/contao-multicolumnwizard-bundle/src/Resources/contao/templates/ to customize UI.

6. Localization:

   • Translate column labels via TL_LANG:

     'label' => &$GLOBALS['TL_LANG']['DCA']['tl_my_table']['my_column'],
     

   • Ensure language files are updated after adding new columns.

Debugging Tips

1. Inspect Field Data:

   • Dump the serialized data in a DCA callback:

     public function loadDataContainer($dc)
     {
         if ($dc->id == 'tl_my_table') {
             $objModel = Model::findByPk($dc->id);
             var_dump(unserialize($objModel->my_mcw_field));
         }
     }
     

2. Check JavaScript Errors:

   • Disable Contao’s debug mode temporarily to isolate MCW-related JS issues:

     define('TL_DEBUG', false);
     

3. Clear Cache:

   • After modifying DCA or templates, clear Contao’s cache:

     php bin/contao-console cache:clear
     

4. Verify Bundle Activation:

   • Ensure the bundle is loaded in config/bundles.php (Contao 4):

     return [
         // ...
         Menatwork\MultiColumnWizardBundle\MenatworkMultiColumnWizardBundle::class => ['all' => true],
     ];
     

Extension Points

1. Custom Column Types:

   • Extend the MCW to support custom input types by overriding the multiColumnWizard widget in Contao’s backend.
   • Tip: Study Contao’s widget system (System/Widgets/).

2. Backend Templates:

   • Override templates in templates/be_wizards/ (Contao 3) or templates/backend/ (Contao 4).
   • Example override path (Contao 4):

     /path/to/project/templates/backend/mcw/
     

3. Hooks:

   • Use Contao’s getColumnFields hook to modify column definitions dynamically:

     $GLOBALS['TL_HOOKS']['getColumnFields'][] = ['MyClass', 'modifyColumnFields'];
     

4. Frontend Widgets:

   • Build frontend widgets to render MCW data (e.g., as a filter UI) by decoding the serialized data and using Contao’s form builder.