===================================== Feature: #98479 - New TCA type "file"

See :issue:98479

Description

A new TCA field type called :php:file has been added to TYPO3 Core. Its main purpose is to simplify the TCA configuration for adding file reference fields to records. It therefore supersedes the usage of TCA type :php:inline with :php:foreign_table set to :php:sys_file_reference, which had previously usually been configured using the now deprecated API method :php:ExtensionManagementUtility->getFileFieldTCAConfig() for this use case.

This helps on determination of the semantic meaning and also allows to reduce internal cross dependencies between TCA type inline and FAL.

The new TCA type :php:file features the following column configuration:

:php:allowed
:php:appearance: :php:collapseAll, :php:expandSingle, :php:createNewRelationLinkTitle, :php:useSortable, :php:enabledControls, :php:headerThumbnail, :php:fileUploadAllowed, :php:fileByUrlAllowed, :php:elementBrowserEnabled, :php:showPossibleLocalizationRecords, :php:showAllLocalizationLink, :php:showSynchronizationLink, :php:showFileSelectors
:php:behaviour: :php:allowLanguageSynchronization, :php:disableMovingChildrenWithParent, :php:enableCascadingDelete
:php:disallowed
:php:fieldInformation
:php:fieldWizard
:php:maxitems
:php:minitems
:php:overrideChildTca
:php:readOnly

.. note::

The option :php:`showFileSelectors` can be used to define whether the
file selectors, such as "Select & upload files" are displayed. This is
similar to the the :php:`showPossibleRecordsSelector` option, available
for TCA type :php:`inline`.

The following column configuration can be overwritten by Page TSconfig:

:typoscript:appearance
:typoscript:behaviour
:typoscript:maxitems
:typoscript:minitems
:typoscript:readOnly

A possible migration using the API method therefore looks like the following:

.. code-block:: php

// Before
'columns' => [
    'image' => [
        'label' => 'My image',
        'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(
            'image',
            [
                'maxitems' => 6,
            ],
            $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']
        ),
    ],
],

// After
'columns' => [
    'image' => [
        'label' => 'My image',
        'config' => [
            'type' => 'file',
            'maxitems' => 6,
            'allowed' => 'common-image-types'
        ],
    ],
],

The example uses the :php:common-image-types placeholder for the :php:allowed option. This placeholder is internally replaced and helps to further reduce the usage of :php:$GLOBALS. Further placeholders are :php:common-text-types and :php:common-media-types. It's possible to use multiple placeholders. It's also possible to mix them with single file extensions. Additionally, it's also possible to define the file extensions as array.

Another example without usage of the API method would therefore look like this:

.. code-block:: php

// Before
'columns' => [
    'image' => [
        'label' => 'My image',
        'config' => [
            'type' => 'inline',
            'foreign_table' => 'sys_file_reference',
            'foreign_field' => 'uid_foreign',
            'foreign_sortby' => 'sorting_foreign',
            'foreign_table_field' => 'tablenames',
            'foreign_match_fields' => [
                'fieldname' => 'image',
            ],
            'foreign_label' => 'uid_local',
            'foreign_selector' => 'uid_local',
            'overrideChildTca' => [
                'columns' => [
                    'uid_local' => [
                        'config' => [
                            'appearance' => [
                                'elementBrowserType' => 'file',
                                'elementBrowserAllowed' => 'jpg,png,gif',
                            ],
                        ],
                    ],
                ],
            ],
        ]
    ],
],

// After
'columns' => [
    'image' => [
        'label' => 'My image',
        'config' => [
            'type' => 'file',
            'allowed' => ['jpg','png','gif'],
        ],
    ],
],

Together with the new TCA type, three new PSR-14 events have been introduced:

:php:TYPO3\CMS\Backend\Form\Event\CustomFileControlsEvent
:php:TYPO3\CMS\Backend\Form\Event\ModifyFileReferenceControlsEvent
:php:TYPO3\CMS\Backend\Form\Event\ModifyFileReferenceEnabledControlsEvent

CustomFileControlsEvent

Listeners to this event will be able to add custom controls to a TCA type :php:file field in FormEngine. This replaces the :php:customControls hook option, which is only available for TCA type :php:inline.

The new event provides the following methods:

:php:getResultArray(): Returns the whole result array
:php:setResultArray(array $resultArray): Allows to overwrite the result array, e.g. to add additional JS modules
:php:getControls(): Returns all configured custom controls
:php:setControls(): Overwrites the custom controls
:php:addControl(): Adds a custom control. It's recommended to set the optional :php:$identifier argument.
:php:removeControl(): Removes a custom control. This only works in case the custom control was added with an identifier.
:php:getTableName(): Returns the table name in question
:php:getFieldName(): Returns the field name in question
:php:getDatabaseRow(): Returns the database row of the record in question
:php:getFieldConfig(): Returns the fields' TCA configuration
:php:getFormFieldIdentifier(): Returns the form elements' identifier
:php:getFormFieldName(): Returns the form elements' name

.. note::

Custom controls are always displayed below the file references. In contrast
to the selectors, e.g. "Select & upload files" are custom controls
independent of the :php:`readonly` and :php:`showFileSelectors` options.
This means, you have full control in which scenario your custom controls
are being displayed.

ModifyFileReferenceControlsEvent

Listeners to this event will be able to modify the controls of a single file reference of a TCA type file field. This event is similar to the :php:ModifyInlineElementControlsEvent, which is only available for TCA type inline. See corresponding PHP class or the other :doc:changelog <../12.0/Feature-97231-PSR-14EventsForModifyingInlineElementControls> for more information about available methods and their usage.

ModifyFileReferenceEnabledControlsEvent

Listeners to this event will be able to modify the state (enabled or disabled) for the controls of a single file reference of a TCA type file field. This event is similar to the :php:ModifyInlineElementEnabledControlsEvent, which is only available for TCA type inline. See corresponding PHP class or the other :doc:changelog <../12.0/Feature-97231-PSR-14EventsForModifyingInlineElementControls> for more information about available methods and their usage.

Impact

It's now possible to simplify the TCA configuration for file reference fields, using the new TCA type file. Three new PSR-14 events allow to modify available controls of the TCA field as well as the related file references.

.. index:: Backend, FAL, PHP-API, TCA, ext:backend

sabbelasichon / typo3-rector