LiaMultiColumnWizard

Extension key: lia_multicolumnwizard
Package name: lia/lia_multicolumnwizard
Version: 2.3
Language: en
Author: LOUIS TYPO3 Developers
License: This document is published under the GNU General Public License v2.0 or later.
Rendered: Fri, 04 Sep 2026 14:25:56 +0000

This extension adds an new TCA-Type that allows to group fields into rows that can be multiplied.

Installation

A quick introduction in how to install this extension.

Configuration

How to configure the MultiColumnWizard field.

ViewHelper

A documentation of provided ViewHelpers and how to use them.

Frequently Asked Questions

Answers to common questions regarding this extension.

Installation

Use the composer require command to install the extension:

composer require lia/lia_multicolumnwizard

You can also add the package to your composer.json and run the composer update and composer install commands.

Configuration

CType TCA Configuration

Here you can see a configuration with all the options for configuring the columns of the multicolumn wizard. The field level options are explained in Limiting the number of rows, Field length options and Reference index.

Implementation on parent elements

TCA field configuration

'multicolumnwizard' => [
    'exclude' => 1,
    'label' => 'MulticolumnField',
    'config' => [
        'type' => 'user',
        'renderType' => 'multiColumnWizard',
        'softref' => 'multiColumnWizardTypolink',
        'minitems' => 0,
        'maxitems' => 4,
        'columnFields' => [
            'exampleMultiColumnWizardTextInput' => [
                'divClass' => 'col-sm-2',
                'type' => 'text',
                'label' => 'Textfield'
                'showLabelAboveField' => true,
                'max' => 40,
                'min' => 3,
            ],
            'exampleMultiColumnWizardTextareaInput' => [
                'divClass' => 'col-sm-2',
                'type' => 'textarea',
                'label' => 'Textarea',
                'cols' => 40,
                'rows' => 5
                'showLabelAboveField' => true,
                'max' => 500,
            ],
            'exampleMultiColumnWizardCheckbox' => [
                'divClass' => 'col-sm-2',
                'type' => 'checkbox',
                'label' => 'Checkbox'
            ],
            'exampleMultiColumnWizardSelect' => [
                'divClass' => 'col-sm-2',
                'type' => 'select',
                'label' => 'Select',
                'options' => [
                    'value' => 'name',
                    'value2' => 'name2',
                    'value3' => 'name3',
                    'value4' => 'name4',
                    'value5' => 'name5'
                ]
            ],
            'exampleMultiColumnWizardSelectIcon' => [
                'divClass' => 'col-sm-2',
                'label' => 'Icon',
                'type' => 'select',
                'options' => '',
                'optionsFunction' => [LIA\LiaMulticolumnwizard\Utilities\IconFactory::class . '->getIcons', ['iconPath' => 'EXT:your_extension/Resources/Public/Icons.json']],
            ],
            'exampleMultiColumnWizardReference' => [
                'divClass' => 'col-sm-2',
                'label' => 'Reference',
                'type' => 'select',
                'options' => '',
                'optionsFunction' => [LIA\LiaMulticolumnwizard\Utilities\ReferenceFactory::class . '->getReference', ['tableName' => 'pages', 'valueField' => 'uid', 'outputNameField' => 'title']],
            ],
            'exampleMultiColumnWizardLanguage' => [
                'divClass' => 'col-sm-2',
                'label' => 'Languages',
                'type' => 'select',
                'options' => '',
                'optionsFunction' => [LIA\LiaMulticolumnwizard\Utilities\TCAFactory::class . '->getAvailableLanguagesForAllSites'],
            ],
            'exampleMultiColumnWizardLinkInput' => [
                'divClass' => 'col-sm-2',
                'type' => 'link',
                'label' => 'Link',
                'linkUseField' => 'fieldname_hidden_link_field',
            ],
        ]
    ]
],
'fieldname_hidden_link_field' = [
    'exclude' => 1,
    'label' => 'Hidden link field used by the link wizard of exampleMultiColumnWizardLinkInput',
    'config' => [
        'type' => 'link',
    ]
];

Limiting the number of rows

The field level options minitems and maxitems limit how many rows the wizard accepts. They are named and behave like their counterparts on the native TCA types inline, select and group. Both default to 0, which means "no limit".

TCA field configuration

'multicolumnwizard' => [
    'exclude' => 1,
    'label' => 'Buttons',
    'config' => [
        'type' => 'user',
        'renderType' => 'multiColumnWizard',
        'minitems' => 0,
        'maxitems' => 4,
        'columnFields' => [
            // ...
        ],
    ],
],

maxitems counts rows. Once it is reached, the "Create new record after this record" button of every row is disabled. Records that already exceed the limit are still rendered - they are flagged instead of silently truncated, so no data is lost when a limit is lowered later on.
minitems counts filled rows. The wizard always keeps one row on screen, so a single untouched row counts as zero items.

Violations mark the field with the FormEngine error class. This blocks saving and raises the standard "fields missing" modal, the same way native TCA types do. Like those types, the limits are not enforced by the DataHandler.

Warning

minitems must not exceed maxitems, and both must be non-negative integers. Anything else throws an \LIA\LiaMulticolumnwizard\Exceptions\Backend\InvalidOptionValueException while rendering the form.

Field length options

Columns of type text and textarea accept max and min - named after the native TCA options for input and text - to limit the number of characters.

Column length options

'exampleMultiColumnWizardTextInput' => [
    'divClass' => 'col-sm-2',
    'type' => 'text',
    'label' => 'Textfield',
    'max' => 40,
    'min' => 3,
],

max renders as maxlength, so the browser stops further input. text columns default to 255; textarea columns stay uncapped unless max is set.
min renders as minlength and is additionally checked in JavaScript, because FormEngine submits the form itself and the browser therefore never runs its own minlength validation. Empty fields are never flagged - use minitems to require rows.

Reference index

A multiColumnWizard field stores its rows as a JSON string, which the typolink soft reference parser cannot read. Links maintained in the wizard are therefore invisible to sys_refindex by default: TYPO3 does not warn that a page is still referenced when it is deleted, and the info module does not list the reference.

The parser key multiColumnWizardTypolink closes that gap. It walks the rows, hands every value of a link column to the typolink parser and merges the results, so the links are indexed like the ones of a native link field.

TCA field configuration

'multicolumnwizard' => [
    'exclude' => 1,
    'label' => 'Buttons',
    'config' => [
        'type' => 'user',
        'renderType' => 'multiColumnWizard',
        'softref' => 'multiColumnWizardTypolink',
        'columnFields' => [
            // ...
        ],
    ],
],

Run typo3 referenceindex:update afterwards to index the existing records. All link types the typolink parser supports are covered, page and record links included.

Note

The link columns are read from columnFields of the field, unioned with the columnsOverrides of every record type - the reference index works on the raw record and does not resolve the type. A column name used as a link in one record type and as something else in another is consequently parsed as a link everywhere.

Set up the DatabaseFileds in your database tables:

EXT:/your_extension/ext_tables.sql

CREATE TABLE tx_yourextension_domain_model_item (
    multicolumnwizard mediumtext,
);

and expand your model with variable, getter and setters:

EXT:/your_extension/Domain/Model/Itenm.php

/**
* multicolumnwizard
*
* @var string
*/
protected string $multicolumnwizard = '';

[...]

/**
* Returns the multicolumnwizard list (as json)
*
* @return string
*/
public function getMulticolumnwizard(): string
{
    return $this->multicolumnwizard;
}

/**
* Sets the multicolumnwizard
*
* @param string $multicolumnwizard
* @return void
*/
public function setMulticolumnwizard(string $multicolumnwizard): void
{
    $this->multicolumnwizard = $multicolumnwizard;
}

IconFactory

This factory creates an icon selection from the icons in the JSON file. Your Icon.json file schould look like this.

Icons.json example

[
    {"name":"arrow-down","file":"arrow-down.svg"},
    {"name":"book","file":"book.svg"},
    {"name":"car","file":"car.svg"},
    {"name":"chevron-down","file":"chevron-down.svg"},
    {"name":"chevron-right","file":"chevron-right.svg"},
    {"name":"cloud-download","file":"cloud-download.svg"},
    {"name":"comment-alt-exclamation","file":"comment-alt-exclamation.svg"},
    {"name":"comment-alt","file":"comment-alt.svg"},
    {"name":"compass","file":"compass.svg"},
    {"name":"dollar-sign","file":"dollar-sign.svg"},
    {"name":"envelope","file":"envelope.svg"},
    {"name":"euro","file":"euro.svg"},
    {"name":"external-link","file":"external-link.svg"},
    {"name":"fax","file":"fax.svg"},
    {"name":"hands-helping","file":"hands-helping.svg"},
    {"name":"leaf","file":"leaf.svg"},
    {"name":"map-marker-alt-solid","file":"map-marker-alt-solid.svg"},
    {"name":"map-marker-alt","file":"map-marker-alt.svg"},
    {"name":"paper-plane","file":"paper-plane.svg"},
    {"name":"phone","file":"phone.svg"},
    {"name":"swatchbook","file":"swatchbook.svg"},
    {"name":"tasks","file":"tasks.svg"},
    {"name":"user-headset","file":"user-headset.svg"},
    {"name":"users","file":"users.svg"},
    {"name":"video","file":"video.svg"},
    {"name":"wrench","file":"wrench.svg"}
]

Link Field

In order to use the link feature you need to also create a field of type link in the current TCA and reference it in the multicolumnwizard link field in the linkUseField attribute. This field will be automatically hidden by Javascript.

Link Field Example

$ctype = &$GLOBALS['TCA']['tt_content']['types']['lia_ctypes_mcw_test'];

$ctype['columnsOverrides']['multicolumnwizard']['config']['columnFields'] = [
    'exampleMultiColumnWizardLinkInput' => [
        'divClass' => 'col-sm-2',
        'type' => 'link',
        'label' => 'Link',
        'linkUseField' => 'fieldname_hidden_link_field',
    ],
];

// the hidden link field for exampleMultiColumnWizardLinkInput
$ctype['columnsOverrides']['fieldname_hidden_link_field'] = [
    'exclude' => 1,
    'label' => 'Link',
    'config' => [
        'type' => 'link',
    ]
];

$ctype['types'][1]['showitem'] = '... , tx_lia_multicolumnwizard, fieldname_hidden_link_field, ...';

Warning

The fieldname_hidden_link_field Field has to be added to showItems to be rendered in the Form, otherwise the linkwizard will not be shown.

Implementation on child elements

you can use the option 'showLabelAboveField' => true, if this is set the label will be shown in every row

Useage of showLabelAboveField

$tca_columns['tx_lia_multicolumnwizard']['config']['columnFields'] = [
    'fieldName_1' => [
        'divClass' => 'col-sm-2',
        'type' => 'text',
        'label' => 'Textxfield'
        'showLabelAboveField' => true,
        'max' => 40,
        'min' => 3,
    ],
    'fieldName_2' => [
        'divClass' => 'col-sm-2',
        'type' => 'textarea',
        'label' => 'Textarea',
        'showLabelAboveField' => true,
        'cols' => 40,
        'rows' => 5
        'max' => 500,
    ],
    'fieldName_3' => [
        'divClass' => 'col-sm-2',
        'type' => 'checkbox',
        'label' => 'Checkbox'
    ],
    'fieldName_4' => [
        'divClass' => 'col-sm-2',
        'type' => 'select',
        'label' => 'Select',
        'options' => [
            'value' => 'name',
            'value2' => 'name2',
            'value3' => 'name3',
            'value4' => 'name4',
            'value5' => 'name5'
        ]
    ],
    'fieldName_5' => [
        'divClass' => 'col-sm-2',
        'label' => 'Icon',
        'type' => 'select',
        'options' => '',
        'optionsFunction' => [LIA\LiaMulticolumnwizard\Utilities\IconFactory::class . '->getIcons', ['iconPath' => 'EXT:your_extension/Resources/Public/Icons.json']],
    ],
    'fieldName_6' => [
        'divClass' => 'col-sm-2',
        'label' => 'Reference',
        'type' => 'select',
        'options' => '',
        'optionsFunction' => [LIA\LiaMulticolumnwizard\Utilities\ReferenceFactory::class . '->getReference', ['tableName' => 'pages', 'valueField' => 'uid', 'outputNameField' => 'title']],
    ],
    'fieldName_7' => [
        'divClass' => 'col-sm-2',
        'label' => 'Languages',
        'type' => 'select',
        'options' => '',
        'optionsFunction' => [LIA\LiaMulticolumnwizard\Utilities\TCAFactory::class . '->getAvailableLanguagesForAllSites'],
    ],
    'fieldName_8' => [
        'divClass' => 'col-sm-2',
        'type' => 'link',
        'label' => 'Link',
        'linkUseField' => 'fieldname_hidden_link_field',
    ],
];

$tca_columns['fieldname_hidden_link_field'] = [
    'exclude' => 1,
    'label' => 'Hidden link field for the link wizard of fieldName_8',
    'config' => [
        'type' => 'link',
    ]
];

$overrideChildTca['types'][1]['showitem'] = '... ,tx_lia_multicolumnwizard, fieldname_hidden_link_field, ...';

Override Backend-Template Paths

Backendtemplates can be overridden using the general backend template override feature

Example

To overwrite the partial for text-input, place a Partials into the directory:

extensions/your_extension/Resources/Private/Backend/Partials/Fields/text.html

and define this in your TSConfig:

templates.lia/lia_multicolumnwizard.1721919321 = your_vendor/your_extension:Resources/Private/Extensions/LiaMulticolumnWizard/Backend

Options function

Here you can also use your own function to generate the selection options. The function must return an array, otherwise you will receive an exception. Enter the complete class name as the first parameter. The second parameter is the function name followed by an array with all the parameters required to execute your function.

ViewHelpers

Rendered: Fri, 04 Sep 2026 14:25:56 +0000

This is a complete reference of all available Fluid ViewHelpers. This documentation is generated from PHP Source code.

Content

MultiColumnWizard

Backend

Backend.getSelectValues ViewHelper `<mwc:backend.getSelectValues>`

ViewHelper to retrieve select values from a MultiColumnWizard configuration or a callable function.

This ViewHelper can either return the configuration array directly or call a specified method to retrieve the select values dynamically.

Caution

This ViewHelper can be used in the backend context only. In all other context it will just return the configuration array.

Example usage:

Example ViewHelper usage

<lia:getSelectValues configuration="{data.configuration}" optionsFunction="{data.function}" />

Arguments

The following arguments are available for the backend.getSelectValues ViewHelper:

configuration

Type: string

The json string of the MultiColumnWizard field.

optionsFunction

Type: string

This array has to contain the full classname, the method to call and all the parameter that are needed to call this method.

GetMultiColumnWizardValues ViewHelper `<mwc:getMultiColumnWizardValues>`

ViewHelper for parsing the multicolumnwizard json string. Use this to prepare the data from a multicolumnwizard-field into an array.

Examples

Field-data is found in: data.multicolumnwizard

<f:variable name="mcwArray" value="{mcw:getMultiColumnWizardValues(json: '{data.multicolumnwizard}', associative: true)}" />`

Content of mcwArray:

array(3) {
  'field1' => 'value',
  'field2' => 'value',
  'field3' => 'value',
}

So it can be used like:

<span>{mcwArray.field1}</span>

Depending on the current value of {data.multicolumnwizard} and the associative argument.

Arguments

The following arguments are available for the getMultiColumnWizardValues ViewHelper:

associative

Type: bool
Default: false

If the array should be associative

json

Type: string
Required: 1

The multicolumn wizard json string.

IsEmpty ViewHelper `<mwc:isEmpty>`

Check if the given MultiColumnWizard field has any values. Checks every field in every row and returns true if every value is empty.

Examples

Usage in a condition like this:

<f:if condition="!{mcw:isEmpty(json: data.tx_lia_multicolumnwizard)}">
    <!-- Your content -->
</f:if>

Arguments

The following arguments are available for the isEmpty ViewHelper:

json

Type: string
Required: 1

The MultiColumnWizard-json string.

FAQ

ViewHelper

The ViewHelper doesn't work / can't be found

In order to use the ViewHelpers of the MultiColumnWizard you need to import the namespace.

Import the namespace in the beginning html-Tag of your Template like this:

<div  xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
        xmlns:mcw="http://typo3.org/ns/LIA/LiaMulticolumnwizard/ViewHelpers"
        data-namespace-typo3-fluid="true"
>

Use this line in your template before using any MulticolumnWizard-ViewHelper:

{namespace mcw=LIA\LiaMulticolumnwizard\ViewHelpers}

LiaMultiColumnWizard

Installation

Configuration

ViewHelper

Frequently Asked Questions

Installation

Configuration

CType TCA Configuration

Implementation on parent elements

Limiting the number of rows

Field length options

Reference index

IconFactory

Link Field

Implementation on child elements

Override Backend-Template Paths

Example

Options function

ViewHelpers

Content

MultiColumnWizard

Backend

Backend.getSelectValues ViewHelper <mwc:backend.getSelectValues>

Example usage:

Arguments

configuration

optionsFunction

GetMultiColumnWizardValues ViewHelper <mwc:getMultiColumnWizardValues>

Examples

Arguments

associative

json

IsEmpty ViewHelper <mwc:isEmpty>

Examples

Arguments

json

FAQ

ViewHelper

The ViewHelper doesn't work / can't be found

Backend.getSelectValues ViewHelper `<mwc:backend.getSelectValues>`

GetMultiColumnWizardValues ViewHelper `<mwc:getMultiColumnWizardValues>`

IsEmpty ViewHelper `<mwc:isEmpty>`