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.
Table of contents:
Example: A basic link field
The link to the tickets of a conference
<?php
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
defined('TYPO3') or die();
ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
'ticket_link' => [
'label' => 'my_extension.db:conference.ticket_link',
'displayCond' => [
'AND' => [
'FIELD:registration_open:REQ:true',
'FIELD:seats:>:0',
],
],
'config' => [
'type' => 'link',
'allowedTypes' => ['page', 'url'],
'appearance' => [
'browserTitle' => 'my_extension.db:conference.ticket_link.browser_title',
],
],
],
]);
ExtensionManagementUtility::addToAllTCAtypes(
'tx_myextension_conference',
'ticket_link',
'',
'after:registration_deadline',
);
Properties of the TCA column type link
| Name | Type | Scope |
|---|---|---|
| array of keywords | Display / Proc. | |
| boolean | Proc. | |
| array | Display | |
| array | ||
| array | ||
| string, LLL | ||
| boolean | ||
| boolean | Display | |
| string | Display / Proc. | |
| array | ||
| array | ||
| array | ||
| string (keywords) | Display | |
| boolean | Proc. | |
| string | Display | |
| boolean | Display | |
| boolean | Display / Proc. | |
| boolean | Display | |
| integer | Display | |
| array | Display |
-
- Type
- array of keywords
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['allowedTypes']
- Scope
- Display / Proc.
- page
- Links to internal pages
- url
- Links to external pages
- file
- Links to a file
- folder
- Links to a folder
- 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.
EXT:my_extension/Configuration/TCA/Overrides/118-tx_myextension_conference-ticket_link.php<?php use TYPO3\CMS\Core\Utility\ExtensionManagementUtility; defined('TYPO3') or die(); ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [ 'ticket_link' => [ 'label' => 'my_extension.db:conference.ticket_link', 'displayCond' => [ 'AND' => [ 'FIELD:registration_open:REQ:true', 'FIELD:seats:>:0', ], ], 'config' => [ 'type' => 'link', 'allowedTypes' => ['page', 'url'], 'appearance' => [ 'browserTitle' => 'my_extension.db:conference.ticket_link.browser_title', ], ], ], ]); ExtensionManagementUtility::addToAllTCAtypes( 'tx_myextension_conference', 'ticket_link', '', 'after:registration_deadline', );'allowedTypes' => [ 'page', // A custom link handler, defined by its identifier 'my_handler', ],Copied!// Allow all link types (or skip this option) 'allowedTypes' => ['*'],Copied!
-
-
- Type
- boolean
- Default
- false
- TCA 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_. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.state EXT:my_extension/Configuration/TCA/Overrides/240-tx_myextension_talk-recording.php<?php use TYPO3\CMS\Core\Utility\ExtensionManagementUtility; defined('TYPO3') or die(); ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [ 'recording' => [ 'label' => 'my_extension.db:talk.recording', 'config' => [ 'type' => 'link', 'allowedTypes' => ['url'], 'appearance' => [ 'allowedOptions' => [], 'enableBrowser' => false, ], 'behaviour' => [ 'allowLanguageSynchronization' => true, ], 'searchable' => false, ], ], ]); ExtensionManagementUtility::addToAllTCAtypes( 'tx_myextension_talk', 'recording', 'talk,keynote', 'before:--div--;core.form.tabs:access', );
-
- Type
- array
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']
- Scope
- Display
Has information about the appearance, namely:
-
- Type
- array
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']['allowedOptions']
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[](emptyarray).- class
- Custom CSS classes for the link
- params
- Additional link parameters
- target
- Either empty,
_topor_blank - title
- The
titleattribute of the link - rel
-
The link relationship.
Changed in version 14.2
No longer limited to RTE-enabled fields.
For RTE-enabled fields, buttons.link.relAttribute.enabled, must be enabled.
The link to the recording of a talk shows no options:
EXT:my_extension/Configuration/TCA/Overrides/240-tx_myextension_talk-recording.php<?php use TYPO3\CMS\Core\Utility\ExtensionManagementUtility; defined('TYPO3') or die(); ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [ 'recording' => [ 'label' => 'my_extension.db:talk.recording', 'config' => [ 'type' => 'link', 'allowedTypes' => ['url'], 'appearance' => [ 'allowedOptions' => [], 'enableBrowser' => false, ], 'behaviour' => [ 'allowLanguageSynchronization' => true, ], 'searchable' => false, ], ], ]); ExtensionManagementUtility::addToAllTCAtypes( 'tx_myextension_talk', 'recording', 'talk,keynote', 'before:--div--;core.form.tabs:access', );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.
The email for feedback on a talk can have a subject and a text:
EXT:my_extension/Configuration/TCA/Overrides/257-tx_myextension_talk-feedback_email.php<?php use TYPO3\CMS\Core\Utility\ExtensionManagementUtility; defined('TYPO3') or die(); ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [ 'feedback_email' => [ 'label' => 'my_extension.db:talk.feedback_email', 'config' => [ 'type' => 'link', 'allowedTypes' => ['email'], 'appearance' => [ // The email can have a prepared subject and text 'allowedOptions' => ['subject', 'body'], ], ], ], ]); ExtensionManagementUtility::addToAllTCAtypes( 'tx_myextension_talk', 'feedback_email', '', 'after:comments', );
-
- Type
- array
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']['allowedFileExtensions']
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.The program of a conference links to a PDF file:
EXT:my_extension/Configuration/TCA/Overrides/137-tx_myextension_conference-program.php<?php use TYPO3\CMS\Core\Utility\ExtensionManagementUtility; defined('TYPO3') or die(); ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [ 'program' => [ 'label' => 'my_extension.db:conference.program', 'config' => [ 'type' => 'link', 'allowedTypes' => ['file'], 'appearance' => [ // The printed program is a PDF file 'allowedFileExtensions' => ['pdf'], ], ], ], ]); ExtensionManagementUtility::addToAllTCAtypes( 'tx_myextension_conference', 'program', '', 'after:website', );
-
- Type
- string, LLL
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']['browserTitle']
Allows to set a different
titleattribute for the Link Browser icon, defaults toLink.EXT:my_extension/Configuration/TCA/Overrides/118-tx_myextension_conference-ticket_link.php<?php use TYPO3\CMS\Core\Utility\ExtensionManagementUtility; defined('TYPO3') or die(); ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [ 'ticket_link' => [ 'label' => 'my_extension.db:conference.ticket_link', 'displayCond' => [ 'AND' => [ 'FIELD:registration_open:REQ:true', 'FIELD:seats:>:0', ], ], 'config' => [ 'type' => 'link', 'allowedTypes' => ['page', 'url'], 'appearance' => [ 'browserTitle' => 'my_extension.db:conference.ticket_link.browser_title', ], ], ], ]); ExtensionManagementUtility::addToAllTCAtypes( 'tx_myextension_conference', 'ticket_link', '', 'after:registration_deadline', );'appearance' => [ // Or a plain string 'browserTitle' => 'Link to the tickets', ],Copied!
-
- Type
- boolean
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['appearance']['enableBrowser']
The Link Browser is enabled by default. To disable the Link Browser altogether, set this option to
false.EXT:my_extension/Configuration/TCA/Overrides/240-tx_myextension_talk-recording.php<?php use TYPO3\CMS\Core\Utility\ExtensionManagementUtility; defined('TYPO3') or die(); ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [ 'recording' => [ 'label' => 'my_extension.db:talk.recording', 'config' => [ 'type' => 'link', 'allowedTypes' => ['url'], 'appearance' => [ 'allowedOptions' => [], 'enableBrowser' => false, ], 'behaviour' => [ 'allowLanguageSynchronization' => true, ], 'searchable' => false, ], ], ]); ExtensionManagementUtility::addToAllTCAtypes( 'tx_myextension_talk', 'recording', 'talk,keynote', 'before:--div--;core.form.tabs:access', );
-
- Type
- boolean
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['autocomplete']
- Scope
- Display
Controls the
autocompleteattribute of a given link field. If set to true (default false), adds attributeautocomplete="on"to the email input field allowing browser auto filling the field:'autocomplete' => true,Copied!
-
- Type
- string
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['default']
- Scope
- Display / Proc.
Default value set if a new record is created.
-
For details see fieldControl.
-
For details see fieldInformation.
-
-
- Type
- array
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']
For details see defaultLanguageDifferences.
-
- Type
- array
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']
For details see localizationStateSelector.
-
- Type
- array
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']
For details see otherLanguageContent.
-
- Type
- string (keywords)
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['mode']
- Scope
- Display
Possible keywords:
useOr Override Placeholder This property is related to the
placeholderproperty. 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 beNULL.Warning
In order for this property to apply properly, the DB column must be allowed to be
NULL, and propertynullablemust be set totrue.
-
- Type
- boolean
- Default
- false
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['nullable']
- 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
NULLin 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 aNULL.The database field must allow the
NULLvalue.
'nullable' => true,
-
- Type
- string
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['placeholder']
- Scope
- Display
Placeholder, containing a default value.
'placeholder' => 'https://example.org',Copied!Note
As the TCA is cached it is not possible to set dynamic values such as
now.()
-
- Type
- boolean
- TCA 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.
-
- Type
- boolean
- Default
- false
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['required']
- Scope
- Display / Proc.
If set to true a non-empty value is required in the field. Otherwise the form cannot be saved.
Changed in version 14.0 Breaking: #106976 - Removal of TCA search field configuration options
The following TCA field level search configuration options have been removed:
search.case search.pidonly search.and Where
They have not been supported by the Core or common Extensions.
-
- Type
- boolean
- Default
true- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['searchable']
- Scope
- Display
New in version 14.0
TYPO3 now automatically includes all fields of suitable types in backend search operations in the Content > Records module.
This option can be used to explicitly exclude fields from being searchable, instead of having to list them in the now removed option $GLOBALS['TCA'][$table]['ctrl']['searchFields'].
By default, all fields of type
linkare considered searchable. To exclude a field from being searchable, set the following in the field's TCA configuration:EXT:my_extension/Configuration/TCA/Overrides/240-tx_myextension_talk-recording.php<?php use TYPO3\CMS\Core\Utility\ExtensionManagementUtility; defined('TYPO3') or die(); ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [ 'recording' => [ 'label' => 'my_extension.db:talk.recording', 'config' => [ 'type' => 'link', 'allowedTypes' => ['url'], 'appearance' => [ 'allowedOptions' => [], 'enableBrowser' => false, ], 'behaviour' => [ 'allowLanguageSynchronization' => true, ], 'searchable' => false, ], ], ]); ExtensionManagementUtility::addToAllTCAtypes( 'tx_myextension_talk', 'recording', 'talk,keynote', 'before:--div--;core.form.tabs:access', );
-
- Type
- integer
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['size']
- 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.
-
- Type
- array
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['valuePicker']
- Scope
- Display
Renders a select box with static values next to the input field. When an item is selected, the value replaces the current input value.
Changed in version 14.0 Breaking: #107677 - Drop prepend and append modes from TCA value picker
It is now recommended to define associative array keys for
itemsusinglabelandvalue. Existing numeric arrays are automatically migrated during TCA processing.The
modeoption no longer supportsappendorprepend. The Value Picker always behaves like a replace operation. Legacymodesettings are ignored.- items (array)
- A list of selectable items. Each item should be an associative array:
['label' => 'Shown label', 'value' => 'stored. The label can be plain text or a label reference.Value']
Hint
In earlier TYPO3 versions, the
modeoption allowed you toprependorappendthe selected value to the current input. This option was removed in TYPO3 v14.0. The value picker now always replaces the current field value.If you previously used
mode => 'prepend'to insert a prefix (for example, to automatically addhttps://before a link), you can achieve a similar result with a custom FormEngine element or a small JavaScript hook that modifies the input value after selection.
The website of a speaker with its value picker
<?php
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
defined('TYPO3') or die();
ExtensionManagementUtility::addTCAcolumns('tx_myextension_speaker', [
'website' => [
'label' => 'my_extension.db:speaker.website',
'config' => [
'type' => 'link',
'valuePicker' => [
'items' => [
['label' => 'Profile page', 'value' => 'https://example.org/profile/'],
['label' => 'Code repository', 'value' => 'https://example.org/code/'],
],
],
'allowedTypes' => ['url'],
],
],
]);
ExtensionManagementUtility::addToAllTCAtypes(
'tx_myextension_speaker',
'website',
'',
'before:--div--;my_extension.db:tab.integration',
);
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: or
<f: view helper.
In PHP code, inject
Link
and call create or create on it. Both return a
Link. Its method
get returns the URL:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Frontend;
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;
use TYPO3\CMS\Frontend\Typolink\LinkFactory;
/**
* Creates the URL of the ticket link of a conference: a page of the site or
* the shop of a ticket provider
*/
final readonly class TicketUriBuilder
{
public function __construct(
private LinkFactory $linkFactory,
) {}
/**
* @param array<string, mixed> $conference
*/
public function getUri(array $conference, ContentObjectRenderer $contentObjectRenderer): string
{
return $this->linkFactory
->createUri((string)($conference['ticket_link'] ?? ''), $contentObjectRenderer)
->getUrl();
}
}