Link

New in version 13.0

When using the link type, TYPO3 takes care of generating the according database field. A developer does not need to define this field in an extension's ext_tables.sql file.

The TCA type link should be used to input values representing typolinks.

The according database field is generated automatically.

Example: A basic link field

<?php

return [
    // ...
    'columns' => [
        'a_link_field' => [
            'label' => 'Link',
            'config' => [
                'type' => 'link',
                'allowedTypes' => ['page', 'url', 'record'],
            ],
        ],
    ],
];

Properties of the TCA column type `link`

Name	Type	Scope
allowedTypes	array of keywords	Display / Proc.
behaviour
allowLanguageSynchronization	boolean	Proc.
appearance	array	Display
autocomplete	boolean	Display
default	string	Display / Proc.
fieldControl
fieldInformation
fieldWizard
defaultLanguageDifferences	array
localizationStateSelector	array
otherLanguageContent	array
mode	string (keywords)	Display
nullable	boolean	Proc
placeholder	string	Display
readOnly	boolean	Display
required	boolean	Display / Proc.
search	array	Search
pidonly	boolean
case	boolean
andWhere	string
size	integer	Display
valuePicker	array	Display

allowedTypes

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

page

Links to internal pages

url

Links to external pages

file

Links to a file

folder

Links to a folder

email

Creates an email link

telephone

Creates a phone link

record

Enables any record link handler that is defined in the LinkHandler API. To enable only a specific custom LinkHandler, add the defined identifier instead.

// 'record' will match any custom link handler
'allowedTypes' => ['page', 'url', 'record']

// 'tx_news' and 'custom_identifier' are both custom link handlers
'allowedTypes' => ['page', 'url', 'tx_news', 'custom_identifier']

// Allow all types (or skip this option).
'allowedTypes' => ['*']

behaviour

allowLanguageSynchronization

Type: boolean
Default: false
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 link. 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.

EXT:my_extension/Configuration/TCA/Overrides/someTable.php

<?php

$linkField = [
    'config' => [
        'type' => 'link',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];

appearance

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

Has information about the appearance, namely:

allowedOptions (array)

Display certain options in the link browser. To allow all options in the Link Browser, skip this configuration or set it to ['*']. To deny all options in the Link Browser, set this configuration to [] (empty array).

class

Custom CSS classes for the link

params

Additional link parameters

target

Either empty, _top or _blank

title

The title attribute of the link

rel

The link relationship. Only available for RTE enabled fields and if buttons.link.relAttribute.enabled is enabled in the RTE YAML configuration.
// Display only 'class' and 'params'
'appearance' => [
    'allowedOptions' => ['class', 'params'],
],
Copied!
// Allow all options (or skip this option).
'appearance' => [
    'allowedOptions' => ['*'],
],
Copied!
// Deny all options
'appearance' => [
    'allowedOptions' => [],
],
Copied!
For custom email links, the options can be restricted:

body

The body of an email can be pre-filled.

cc

The "cc" field can be pre-filled.

bcc:

The "bcc" field can be pre-filled.

subject:

The subject of an email can be pre-filled.
'appearance' => [
    'allowedOptions' => ['body', 'cc'],
],
Copied!

allowedFileExtensions (array)

An array of allowed file extensions. To allow all extensions, skip this configuration or set it to ['*']. It's not possible to deny all extensions.
// Allow only jpg and png file extensions
'appearance' => [
    'allowedFileExtensions' => ['jpg', 'png'],
],
Copied!
// Allow all file extensions (or skip this option).
'appearance' => [
    'allowedFileExtensions' => ['*'],
],
Copied!

browserTitle (string, LLL)

Allows to set a different title attribute for the Link Browser icon, defaults to Link.

// Either provide a LLL-reference (recommended)
'appearance' => [
    'browserTitle' => 'LLL:EXT:Resources/Private/Language/locallang.xlf:my_custom_title',
],

// Or a simple string value
'appearance' => [
    'browserTitle' => 'My custom title',
],

enableBrowser (boolean)

The Link Browser is enabled by default. To disable the Link Browser altogether, set this option to false.
// Disable the link browser
'appearance' => [
    'enableBrowser' => false,
],
Copied!

autocomplete

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

Controls the autocomplete attribute of a given link field. If set to true (default false), adds attribute autocomplete="on" to the email input field allowing browser auto filling the field:

EXT:some_extension/Configuration/TCA/Overrides/tx_sometable.php

<?php

$myLinkField = [
    'label' => 'A link with autocomplete',
    'config' => [
        'type' => 'link',
        'size' => 20,
        'nullable' => 'true',
        'autocomplete' => true,
    ],
];

default

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

Default value set if a new record is created.

fieldControl: For details see fieldControl.

fieldInformation: For details see fieldInformation.

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.

mode

Type: string (keywords)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['mode']
Scope: Display

Possible keywords: useOrOverridePlaceholder

This property is related to the placeholder property. When defined, a checkbox will appear above the field. If that box is checked, the field can be used to enter whatever the user wants as usual. If the box is not checked, the field becomes read-only and the value saved to the database will be NULL.

Warning

In order for this property to apply properly, the DB column must be allowed to be NULL, and property nullable must be set to true.

nullable

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Default: false
Scope: Proc

If set to true, a checkbox will appear, which by default deactivates the field. In the deactivated state the field is saved as NULL in the database. By activating the checkbox it is possible to set a value. If nothing is entered into the field, then an empty string will be saved and not a NULL.

The database field must allow the NULL value.

Example: a nullable link field

EXT:some_extension/Configuration/TCA/Overrides/tx_sometable.php

<?php

$myLinkField = [
    'title' => 'A nullable field',
    'config' => [
        'type' => 'link',
        'nullable' => true,
    ],
];

placeholder

Type: string
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['placeholder']
Scope: Display

Placeholder, containing a default value.

EXT:my_extension/Configuration/TCA/Overrides/some-table.php

<?php

$temporaryColumns['alinkField'] = [
    'title' => 'My link field',
    'config' => [
        'type' => 'link',
        'placeholder' => '#FF8700',
        'mode' => 'useOrOverridePlaceholder',
    ],
];

Note

As the TCA is cached it is not possible to set dynamic values such as now().

readOnly

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

Renders the field in a way that the user can see the value but cannot edit it.

Warning

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

required

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.
Default: false

If set to true a non-empty value is required in the field. Otherwise the form cannot be saved.

search

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['search']
Scope: Search

Defines additional search-related options for a given field.

pidonly

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['pidonly']

Searches in the column only if search happens on the single page, does not search the field if searching in the whole table.

case

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['case']

Makes the search case-sensitive. This requires a proper database collation for the field, see your database documentation.

andWhere

Type: string
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['andWhere']

Additional SQL WHERE statement without 'AND'. With this it is possible to place an additional condition on the field when it is searched

EXT:some_extension/Configuration/TCA/tx_sometable.php

$temporaryColumns['some_date'] => [
    'config' => [
        'search' => [
            'andWhere' => '{#CType}=\'type_x\' OR {#CType}=\'type_y\'',
        ],
        // ...
    ],
];

This means that the "some_date" field of the "tt_content" table will be searched in only for elements of type X and Y. This helps making any search more relevant.

The above example uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible.

size

Type: integer
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display

Abstract value for the width of the <input> field. To set the link field to the full width of the form area, use the value 50. Minimum is 10. Default is 30.

valuePicker

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

Renders a select box with static values next to the input field. When a value is selected in the box, the value is transferred to the field. Keys:

mode (keyword)

blank (or not set): The selected value substitutes the value in the input field
append: The selected value is appended to an existing value of the input field
prepend: The selected value is prepended to an existing value of the input field

Changed in version 14.0

It is now recommended to define associative array keys for the items configuration of the TCA configuration valuePicker. The recommended keys are: label and value. Existing numeric array configurations will be automatically migrated to the new associative format during TCA processing.

items (array): An array with selectable items. Each item is an array with the first value being the label in the select drop-down (LLL reference possible) the second being the value transferred to the input field.

Example: A link field with value picker

<?php

$myLinkField = [
    'label' => 'input_33',
    'config' => [
        'type' => 'link',
        'mode' => 'prepend',
        'valuePicker' => [
            'items' => [
                [
                    'value' => 'HTTPS',
                    'label' => 'https://',
                ],
                [
                    'value' => 'HTTP',
                    'label' => 'http://',
                ],
            ],
        ],
    ],
];

Note

The softref definition softref=typolink is automatically applied to all TCA type link columns.

Create an URL

To create a URL from such a link field in a Fluid template, use the <f:link.typolink> or <f:uri.typolink> view helper.

In PHP code, use LinkFactory::create() or LinkFactory::createUri():

EXT:my_extension/Classes/Service/MyService.php

<?php

namespace MyVendor\MyExtension\Service;

use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;
use TYPO3\CMS\Frontend\Typolink\LinkFactory;

class SomeService
{
    public function __construct(
        private readonly LinkFactory $linkFactory,
    ) {}

    public function getUri(string $tcaLinkValue, ContentObjectRenderer $contentObjectRenderer): string
    {
        return $this->linkFactory->createUri(
            $tcaLinkValue,
            $contentObjectRenderer
        );
    }
}

Link

Example: A basic link field

Properties of the TCA column type link

allowedTypes

behaviour

allowLanguageSynchronization

appearance

autocomplete

default

fieldControl

fieldInformation

fieldWizard

defaultLanguageDifferences

localizationStateSelector

otherLanguageContent

mode

nullable

placeholder

readOnly

required

search

pidonly

case

andWhere

size

valuePicker

Create an URL

Properties of the TCA column type `link`