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_
set to
sys_
, which had previously
usually been configured using the now deprecated API method
Extension
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
:collapse
,All expand
,Single create
,New Relation Link Title use
,Sortable enabled
,Controls header
,Thumbnail file
,Upload Allowed file
,By Url Allowed element
,Browser Enabled show
,Possible Localization Records show
,All Localization Link show
,Synchronization Link show
File Selectors behaviour
:allow
,Language Synchronization disable
,Moving Children With Parent enable
Cascading Delete disallowed
field
Information field
Wizard maxitems
minitems
override
Child Tca read
Only
Note
The option
show
can be used to define whether the
file selectors, such as "Select & upload files" are displayed. This is
similar to the
show
option, available
for TCA type
inline
.
The following column configuration can be overwritten by Page TSconfig:
appearance
behaviour
maxitems
minitems
read
Only
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-
placeholder for the
allowed
option. This placeholder is internally replaced and
helps to further reduce the usage of
$GLOBALS
. Further placeholders
are
common-
and
common-
. 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\ Custom File Controls Event \TYPO3\
CMS\ Backend\ Form\ Event\ Modify File Reference Controls Event \TYPO3\
CMS\ Backend\ Form\ Event\ Modify File Reference Enabled Controls Event
CustomFileControlsEvent
Listeners to this event will be able to add custom controls to a TCA type
file
field in FormEngine. This replaces the
custom
hook option, which is only available for TCA type
inline
.
The new event provides the following methods:
get
: Returns the whole result arrayResult Array () set
: Allows to overwrite the result array, e.g. to add additional JS modulesResult Array (array $result Array) get
: Returns all configured custom controlsControls () set
: Overwrites the custom controlsControls () add
: Adds a custom control. It's recommended to set the optionalControl () $identifier
argument.remove
: Removes a custom control. This only works in case the custom control was added with an identifier.Control () get
: Returns the table name in questionTable Name () get
: Returns the field name in questionField Name () get
: Returns the database row of the record in questionDatabase Row () get
: Returns the fields' TCA configurationField Config () get
: Returns the form elements' identifierForm Field Identifier () get
: Returns the form elements' nameForm Field 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
show
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
Modify
, 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
Modify
, 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.