The LinkHandler API

The LinkHandler API currently consists of 7 LinkHandler classes and the TYPO3\CMS\Backend\LinkHandler\LinkHandlerInterface. The LinkHandlerInterface can be implemented to create custom LinkHandlers.

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.

Most LinkHandlers cannot receive additional configuration, they are marked as @internal and contain neither hooks nor events. They are therefore of interest to Core developers only.

Current LinkHandlers:

  • The PageLinkHandler: for linking pages and content
  • The RecordLinkHandler: for linking any kind of record
  • UrlLinkHandler: for linking external urls
  • FileLinkHandler: for linking files in the File abstraction layer (FAL)
  • FolderLinkHandler: for linking to directories
  • MailLinkHandler: for linking email addresses
  • TelephoneLinkHandler: for linking phone numbers

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

  1. TypoScript is used to generate the actual link 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!

LinkHandler 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!

See Link handler configuration for all available options.

Example: news records from one storage pid

The following configuration hides the page tree and shows news records only from the defined storage page:

EXT:some_extension/Configuration/page.tsconfig
TCEMAIN.linkHandler.news {
    handler = TYPO3\CMS\Backend\LinkHandler\RecordLinkHandler
    label = News
    configuration {
        table = tx_news_domain_model_news
        storagePid = 123
        hidePageTree = 1
    }
    displayAfter = email
}
Copied!

It is possible to have another configuration using another storagePid which also contains news records.

This configuration shows a reduced page tree starting at page with uid 42:

EXT:some_extension/Configuration/page.tsconfig
TCEMAIN.linkHandler.bookreports {
    handler = TYPO3\CMS\Backend\LinkHandler\RecordLinkHandler
    label = Book Reports
    configuration {
        table = tx_news_domain_model_news
        storagePid = 42
        pageTreeMountPoints = 42
        hidePageTree = 0
    }
}
Copied!

The page TSconfig of the LinkHandler is being used in sysext backend in class \TYPO3\CMS\Backend\LinkHandler\RecordLinkHandler which does not contain Hooks.

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.

Example: news records displayed on fixed detail page

The following displays the link to the news on a detail page:

EXT:some_extension/Configuration/TypoScript/setup.typoscript
config.recordLinks.news {
   typolink {
      parameter = 123
      additionalParams.data = field:uid
      additionalParams.wrap = &tx_news_pi1[controller]=News&tx_news_pi1[action]=detail&tx_news_pi1[news]=|
   }
}
Copied!

Once more if the book reports that are also saved as tx_news_domain_model_news record should be displayed on their own detail page you can do it like this:

EXT:some_extension/Configuration/TypoScript/setup.typoscript
config.recordLinks.bookreports  {
   typolink {
      parameter = 987
      additionalParams.data = field:uid
      additionalParams.wrap = &tx_news_pi1[controller]=News&tx_news_pi1[action]=detail&tx_news_pi1[news]=|
   }
}
Copied!