Feature: #98479 - New TCA type "file"¶
See forge#98479
Description¶
A new TCA field type called 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 inline
with foreign_table
set to sys_file_reference
, which had previously
usually been configured using the now deprecated API method
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 file
features the following column configuration:
allowed
appearance
:collapseAll
,expandSingle
,createNewRelationLinkTitle
,useSortable
,enabledControls
,headerThumbnail
,fileUploadAllowed
,fileByUrlAllowed
,elementBrowserEnabled
,showPossibleLocalizationRecords
,showAllLocalizationLink
,showSynchronizationLink
,showFileSelectors
behaviour
:allowLanguageSynchronization
,disableMovingChildrenWithParent
,enableCascadingDelete
disallowed
fieldInformation
fieldWizard
maxitems
minitems
overrideChildTca
readOnly
Note
The option showFileSelectors
can be used to define whether the
file selectors, such as "Select & upload files" are displayed. This is
similar to the the showPossibleRecordsSelector
option, available
for TCA type inline
.
The following column configuration can be overwritten by Page TSconfig:
appearance
behaviour
maxitems
minitems
readOnly
A possible migration using the API method therefore looks like the following:
// 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 common-image-types
placeholder for the
allowed
option. This placeholder is internally replaced and
helps to further reduce the usage of $GLOBALS
. Further placeholders
are common-text-types
and 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:
// 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:
TYPO3\CMS\Backend\Form\Event\CustomFileControlsEvent
TYPO3\CMS\Backend\Form\Event\ModifyFileReferenceControlsEvent
TYPO3\CMS\Backend\Form\Event\ModifyFileReferenceEnabledControlsEvent
CustomFileControlsEvent¶
Listeners to this event will be able to add custom controls to a TCA type
file
field in FormEngine. This replaces the customControls
hook option, which is only available for TCA type inline
.
The new event provides the following methods:
getResultArray()
: Returns the whole result arraysetResultArray(array $resultArray)
: Allows to overwrite the result array, e.g. to add additional JS modulesgetControls()
: Returns all configured custom controlssetControls()
: Overwrites the custom controlsaddControl()
: Adds a custom control. It's recommended to set the optional$identifier
argument.removeControl()
: Removes a custom control. This only works in case the custom control was added with an identifier.getTableName()
: Returns the table name in questiongetFieldName()
: Returns the field name in questiongetDatabaseRow()
: Returns the database row of the record in questiongetFieldConfig()
: Returns the fields' TCA configurationgetFormFieldIdentifier()
: Returns the form elements' identifiergetFormFieldName()
: 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 readonly
and 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
ModifyInlineElementControlsEvent
, which is only available for TCA
type inline
. See corresponding PHP class or the other
changelog
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 ModifyInlineElementEnabledControlsEvent
, which
is only available for TCA type inline
. See corresponding PHP class or the
other changelog
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.