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.

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',
            ],
        ],
        // ...
    ],
];

Properties of the TCA column type `file`

Name	Type	Scope
allowed	string / array	Proc. / Display
appearance	array	Display
behaviour
allowLanguageSynchronization	boolean	Proc.
disableMovingChildrenWithParent	boolean	Proc.
enableCascadingDelete	boolean	Proc.
disallowed	array	Proc. / Display
fieldInformation	array	Display
fieldWizard
defaultLanguageDifferences	array
localizationStateSelector	array
otherLanguageContent	array
maxitems	integer > 0	Display / Proc.
minitems	integer > 0	Display
overrideChildTca	array	Display
readOnly	boolean	Display

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

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

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

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

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

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

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

defaultLanguageDifferences

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

For details see defaultLanguageDifferences.

localizationStateSelector

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

For details see localizationStateSelector.

otherLanguageContent

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

For details see otherLanguageContent.

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

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'
        ],
    ],
],

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

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.

Warning

This property affects only the display. It is still possible to write to those fields when using the DataHandler.

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'
+         ],
     ],
 ],

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',
            ],
        ],
    ],

File

Examples

Properties of the TCA column type file

allowed

appearance

behaviour

allowLanguageSynchronization

disableMovingChildrenWithParent

enableCascadingDelete

disallowed

fieldInformation

fieldWizard

defaultLanguageDifferences

localizationStateSelector

otherLanguageContent

maxitems

minitems

overrideChildTca

readOnly

Migration

Properties of the TCA column type `file`