The RecordLinkHandler

The RecordLinkHandler enables editors to link to single records, for example the detail page of a news record.

You can find examples here:

The handler is implemented in class \TYPO3\CMS\Backend\LinkHandler\RecordLinkHandler of the system extension backend. The class is marked as @internal and contains neither hooks nor events.

Changed in version 12.0

Due to the integration of EXT:recordlist into EXT:backend the namespace of LinkHandlers has changed from TYPO3\CMS\Recordlist\LinkHandler to TYPO3\CMS\Backend\LinkHandler. For TYPO3 v12 the moved classes are available as an alias under the old namespace to allow extensions to be compatible with TYPO3 v11 and v12.

In order to use the RecordLinkHandler it can be configured as following:

  1. Page TSconfig is used to create a new tab in the LinkBrowser to be able to select records.

    TCEMAIN.linkHandler.anIdentifier {
        handler = TYPO3\CMS\Backend\LinkHandler\RecordLinkHandler
        label = LLL:EXT:extension/Resources/Private/Language/locallang.xlf:link.customTab
        configuration {
            table = tx_example_domain_model_item
        }
        scanAfter = page
    }
    Copied!

    You can position your own handlers in order as defined in the LinkBrowser API.

    The links are now stored in the database with the syntax <a href="t3://record?identifier=anIdentifier&amp;uid=456">A link</a>.

  2. TypoScript configures how the link will be displayed in the frontend.

    config.recordLinks.anIdentifier {
        // Do not force link generation when the record is hidden
        forceLink = 0
        typolink {
            parameter = 123
            additionalParams.data = field:uid
            additionalParams.wrap = &tx_example_pi1[item]=|&tx_example_pi1[controller]=Item&tx_example_pi1[action]=show
        }
    }
    Copied!

RecordLinkHandler page TSconfig options

The minimal page TSconfig configuration is:

EXT:some_extension/Configuration/page.tsconfig
TCEMAIN.linkHandler.anIdentifier {
    handler = TYPO3\CMS\Backend\LinkHandler\RecordLinkHandler
    label = LLL:EXT:extension/Resources/Private/Language/locallang.xlf:link.customTab
    configuration {
        table = tx_example_domain_model_item
    }
}
Copied!

The following optional configuration is available:

configuration.hidePageTree = 1
Hide the page tree in the link browser
configuration.storagePid = 84
The link browser starts with the given page
configuration.pageTreeMountPoints = 123,456
Only records on these pages and their children will be displayed

Furthermore the following options are available from the LinkBrowser Api:

configuration.scanAfter = page or configuration.scanBefore = page
Define the order in which handlers are queried when determining the responsible tab for an existing link
configuration.displayBefore = page or configuration.displayAfter = page
Define the order of how the various tabs are displayed in the link browser.

LinkHandler TypoScript options

A configuration could look like this:

EXT:some_extension/Configuration/TypoScript/setup.typoscript
config.recordLinks.anIdentifier {
    forceLink = 0

    typolink {
        parameter = 123
        additionalParams.data = field:uid
        additionalParams.wrap = &tx_example_pi1[item]=|
    }
}
Copied!

The TypoScript Configuration of the LinkHandler is being used in sysext frontend in class TYPO3\CMS\Frontend\Typolink\DatabaseRecordLinkBuilder.