Using mappers

Audience: Integrators, Developers

A form value can be mapped to a TypoScript constant, a site configuration property or a field from the configuration table from this extension. The mapping is defined in a php file located under Configuration/TCA/Overrides and assisted by helper functions from the extension TcaUtility class.

Basic TCA-file structure

<?php

use Buepro\Easyconf\Mapper\EasyconfMapper;
use Buepro\Easyconf\Mapper\SiteConfigurationMapper;
use Buepro\Easyconf\Mapper\TypoScriptConstantMapper;
use Buepro\Easyconf\Utility\TcaUtility;

defined('TYPO3') or die('Access denied.');

if (!\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::isLoaded('easyconf')) {
   return;
}

(static function () {
    $l10nFile = 'LLL:EXT:site_package/Resources/Private/Language/locallang_db.xlf';
    $tca = &$GLOBALS['TCA']['tx_easyconf_configuration'];

    /**
     * Define columns
     */
    $propertyMaps = [
        // ***************************
        // * Here we use the mappers *
        // ***************************
    ];
    $tca['columns'] = TcaUtility::getColumns($propertyMaps, $l10nFile);

    /**
     * Define palettes
     */
    // ...

    /**
     * Modify columns
     */
    // ...

    /**
     * Define type (tabs from the form with palettes and fields)
     */
    // ...

    unset($tca);
})();

Note

Replace site_package with the key from your extension key.

TypoScript constant mapper

Description

On each page where a template record is available TypoScript constants can be altered through form fields. This is achieved by creating a template related file holding the constant definitions and importing this file through the template constants definition.

Note

The inheritance hierarchy from TypoScript is maintained meaning if you set a field value on the root page it can be overwritten on subpages (if a template record exists for that subpage).

Note

The way the TypoScript file import is maintained in the template constants field can be adjusted by the TypoScript constant module.tx_easyconf.settings.typoScriptConstantMapper.importStatementHandling.

Definition

/**
* Define columns
*/
$propertyMaps = [
    TcaUtility::getPropertyMap(
        TypoScriptConstantMapper::class,
        'easyconf.demo',
        'company, domain, firstName, lastName',
        'owner'
    ),
]

Mapping result

Form field	TypoScript constant
owner_company	easyconf.demo.company
owner_domain	easyconf.demo.domain
owner_first_name	easyconf.demo.firstName
owner_last_name	easyconf.demo.lastName

Site configuration mapper

Description

This mapper relates form fields with the site configuration hence writes and reads from the site configuration yaml file.

Note

Since these fields have site scope a change on one page is shown on all other pages having a template record meaning no hierarchical configuration is possible as known from the TypoScript mapping.

Definition

/**
* Define columns
*/
$propertyMaps = [
    TcaUtility::getPropertyMap(
        SiteConfigurationMapper::class,
        'easyconf.data.demo',
        'company, contact, email, phone',
        'agency'
    ),
]

Mapping result

Form field	Site configuration property
agency_company	easyconf.data.demo.company
agency_contact	easyconf.data.demo.contact
agency_email	easyconf.data.demo.email
agency_phone	easyconf.data.demo.phone

Easyconf mapper

Description

This mapper relates form fields with the field fields from the table tx_easyconf_configuration. For each page a template record exists a record is created in the table tx_easyconf_configuration. As a result these form values have a template scope.

Definition

/**
* Define columns
*/
TcaUtility::getPropertyMap(
    EasyconfMapper::class,
    'demo',
    'showAllProperties',
    'easyconf'
),

Mapping result

Form field	Path from `fields` array
easyconf_demo	demo.showAllProperties

Complete code

<?php

use Buepro\Easyconf\Mapper\EasyconfMapper;
use Buepro\Easyconf\Mapper\SiteConfigurationMapper;
use Buepro\Easyconf\Mapper\TypoScriptConstantMapper;
use Buepro\Easyconf\Utility\TcaUtility;

defined('TYPO3') or die('Access denied.');

if (!\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::isLoaded('easyconf')) {
    return;
}

(static function () {
    $l10nFile = 'LLL:EXT:site_package/Resources/Private/Language/locallang_db.xlf';
    $tca = &$GLOBALS['TCA']['tx_easyconf_configuration'];

    /**
    * Define columns
    */
    $propertyMaps = [
        TcaUtility::getPropertyMap(
            TypoScriptConstantMapper::class,
            'easyconf.demo',
            'company, domain, firstName, lastName',
            'owner'
        ),
        TcaUtility::getPropertyMap(
            SiteConfigurationMapper::class,
            'easyconf.data.demo',
            'company, contact, email, phone',
            'agency'
        ),
        TcaUtility::getPropertyMap(
            EasyconfMapper::class,
            'demo',
            'showAllProperties',
            'easyconf'
        ),
    ];
    $tca['columns'] = TcaUtility::getColumns($propertyMaps, $l10nFile);

    /**
    * Define palettes
    */
    $tca['palettes'] = [
        'paletteCompany' => TcaUtility::getPalette(
            'company, domain',
            'owner'
        ),
    ];

    /**
    * Modify columns
    */
    TcaUtility::modifyColumns(
        $tca['columns'],
        'showAllProperties',
        [
            'onChange' => 'reload',
            'config' => ['type' => 'check', 'renderType' => 'checkboxToggle'],
        ],
        'easyconf'
    );
    TcaUtility::modifyColumns(
        $tca['columns'],
        'firstName, lastName',
        ['displayCond' => 'FIELD:easyconf_show_all_properties:REQ:true'],
        'owner'
    );

    /**
    * Define type (tabs from the form with palettes and fields)
    */
    $tabs = [
        'tabTypoScript' => implode(', ', [
            '--palette--;;paletteCompany',
            TcaUtility::getFieldList('firstName, lastName', 'owner'),
        ]),
        'tabSiteConfiguration' => TcaUtility::getFieldList('company, contact, email, phone', 'agency'),
        'tabEasyconf' => TcaUtility::getFieldList('showAllProperties', 'easyconf'),
    ];
    $tca['types'][0] = TcaUtility::getType($tabs, $l10nFile);

    unset($tca);
})();