File

New in version 12.0

The type file supersedes the usage of TCA type inline with foreign_table set to sys_file_reference.

The TCA type file creates a field where files can be attached to the record.

Table of contents

Examples

EXT:my_extension/Configuration/TCA/some_table.php
<?php

return [
    // ...
    'columns' => [
        'my_image' => [
            'label' => 'My image',
            'config' => [
                'type' => 'file',
                'maxitems' => 6,
                'allowed' => 'common-image-types',
            ],
        ],
        // ...
    ],
];
Copied!

Properties of the TCA column type file

Name Type Scope
string / array Proc. / Display
array Display
boolean Proc.
boolean Proc.
boolean Proc.
array Proc. / Display
array Display
array
array
array
integer > 0 Display / Proc.
integer > 0 Display
array Display
boolean Display

allowed

allowed
Type
string / array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc. / Display

One or more (comma-separated) of the following reserved strings:

common-image-types
Gets replaced with the value from $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'] .
common-text-types
Gets replaced with the value from $GLOBALS['TYPO3_CONF_VARS']['SYS']['textfile_ext'] .
common-media-types
Gets replaced with the value from $GLOBALS['TYPO3_CONF_VARS']['SYS']['mediafile_ext'] .

Additionally, specific allowed file extensions can be added (comma separated), for example 'common-image-types, common-text-types, gz, zip.

You can also use the array notation of allowed file extensions, for example ['jpg','png','svg'] or ['common-image-types', 'gz', 'zip'].

New in version 12.4.14

Due to a bug, the array notation only properly works since TYPO3 v12.4.1 and upwards. Use the string notation for earlier versions instead.

appearance

appearance
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Has information about the appearance of child-records, namely:

collapseAll (boolean)
Show all child-records collapsed (if false, all are expanded)
expandSingle (boolean)
Show only one child-record expanded each time. If a collapsed record is clicked, the currently open one collapses and the clicked one expands.
createNewRelationLinkTitle (string or LLL reference)
Overrides the link text and title of the "Create new relation" button with a localized string. Only useful, if the element browser is enabled.
addMediaLinkTitle (string or LLL reference)

New in version 12.3

Overrides the link text and title of the "Add media by URL" button with a localized string. Only useful, if the element browser is enabled.

uploadFilesLinkTitle (string or LLL reference)

New in version 12.3

Overrides the link text and title of the "Select & upload files" button with a localized string. Only useful, if the element browser is enabled.

useSortable (boolean)
Activate drag & drop.
showPossibleLocalizationRecords (boolean)
Show unlocalized files which are in the original language, but not yet localized.
showAllLocalizationLink (boolean)
Defines whether to show the "localize all records" link to fetch untranslated records from the original language.
showSynchronizationLink (boolean)
Defines whether to show a "synchronize" link to update to a 1:1 translation with the original language.
enabledControls (array)
Associative array with the keys 'info', 'new', 'dragdrop', 'sort', 'hide', 'delete', 'localize'. If the accordant values are set to a boolean value (true or false), the control is shown or hidden in the header of each record.
headerThumbnail (array)

Defines whether a thumbnail should be rendered in the inline element's header. This is used by the file abstraction layer to render a preview of the related image. Can contain image processing instructions like width and height.

field (required)
The table column name, which contains the uid of the image reference. Usually this is uid_local.
width
The width of the thumbnail.
height
The height of the thumbnail.
fileUploadAllowed (boolean)

Defines whether the button "Select & upload file" should be rendered. This can be used for file fields to directly upload files and create a reference to the file. The button is limited to file fields using File Abstraction Layer. It will only appear to backend users which have write access to the user upload folder. By default this folder is fileadmin/user_upload but it can be changed in User TSconfig using options.defaultUploadFolder. See the TSconfig reference.

The button is shown by default unless this option is set to false.

fileByUrlAllowed (boolean)
Defines whether the button "Add media by URL" should be rendered. This button is used to include media URLs from e.g. Vimeo or YouTube. In addition to this, a valid online media identifier must be listed in the allowed list of elementBrowserAllowed.
elementBrowserEnabled (boolean)
Hides or displays the element browser button in inline records

This property can also be overridden by page TSconfig.

behaviour

behaviour

allowLanguageSynchronization

allowLanguageSynchronization
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
Scope
Proc.

Allows an editor to select in a localized record whether the value is copied over from default or source language record, or if the field has an own value in the localization. If set to true and if the table supports localization and if a localized record is edited, this setting enables FieldWizard LocalizationStateSelector: Two or three radio buttons shown below the field input. The state of this is stored in a json encoded array in the database table called l10n_state. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.

This property can also be overridden by page TSconfig.

disableMovingChildrenWithParent

disableMovingChildrenWithParent
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['disableMovingChildrenWithParent']
Scope
Proc.

Default false. Disables that child records get moved along with their parent records. Usually if in a parent-child relation a parent record is moved to a different page (eg. via cut+paste from clipboard), the children are relocated along with the parent. This flag disables the child move.

This property can also be overridden by page TSconfig.

enableCascadingDelete

enableCascadingDelete
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['enableCascadingDelete']
Scope
Proc.
Default
true

Usually when the parent record is deleted all attached sys_file_references are deleted. This default behaviour can be disabled here.

This property can also be overridden by page TSconfig.

disallowed

disallowed
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc. / Display

An array of file extensions that are not allowed even though they are listed in the property allowed, for example ['doc','docx'].

fieldInformation

fieldInformation
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Show information between an element label and the main element input area. Configuration works identical to the "fieldWizard" property, no default configuration in the core exists (yet). In contrast to "fieldWizard", HTML returned by fieldInformation is limited, see FormEngine docs for more details.

fieldWizard

fieldWizard

defaultLanguageDifferences

defaultLanguageDifferences
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']

For details see defaultLanguageDifferences.

localizationStateSelector

localizationStateSelector
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']

For details see localizationStateSelector.

otherLanguageContent

otherLanguageContent
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']

For details see otherLanguageContent.

maxitems

maxitems
Type
integer > 0
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.

Maximum number of files that can be attached. Defaults to a high value. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

This property can also be overridden by page TSconfig.

minitems

minitems
Type
integer > 0
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display
Types
group, inline
Default
0

Minimum number of attached files. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

This property can also be overridden by page TSconfig.

Example, exactly one image has to be attached:

// After
'columns' => [
    'image' => [
        'label' => 'My one and only image',
        'config' => [
            'type' => 'file',
            'minitems' => 1,
            'maxitems' => 1,
            'allowed' => 'common-image-types'
        ],
    ],
],
Copied!

overrideChildTca

overrideChildTca
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Override the TCA of the sys_file_reference records representing the files attached to this record.

readOnly

readOnly
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

The files attached to this record are displayed but cannot be changed in the backend form.

This property can also be overridden by page TSconfig.

Migration

 'columns' => [
     'image' => [
         'label' => 'My image',
-        'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(
-            'image',
-            [
-                'maxitems' => 6,
-            ],
-            $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']
-        ),
+         'config' => [
+             'type' => 'file',
+             'maxitems' => 6,
+             'allowed' => 'common-image-types'
+         ],
     ],
 ],
Copied!

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


 'columns' => [
     'image' => [
         'label' => 'My image',
         'config' => [
+            'type' => 'file',
-            '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',
+            // Can also be an array of file extensions as of TYPO3 v12.4.14+
+            'allowed' => 'jpg,png,gif',
-                                'elementBrowserAllowed' => 'jpg,png,gif',
-                            ],
-                        ],
-                    ],
-                ],
-            ],
         ]
     ],
 ],

    // After
    'columns' => [
        'image' => [
            'label' => 'My image',
            'config' => [
                'type' => 'file',
                // Can also be an array of file extensions as of TYPO3 v12.4.14+
                'allowed' => 'jpg,png,gif',
            ],
        ],
    ],
Copied!