The LinkHandler API

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

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 mail
  • TelephoneLinkHandler: for linking phone numbers

The following LinkHandlers are of interest:

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\Recordlist\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\Recordlist\LinkHandler\RecordLinkHandler
    label = News
    configuration {
        table = tx_news_domain_model_news
        storagePid = 123
        hidePageTree = 1
    }
    displayAfter = mail
}
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\Recordlist\LinkHandler\RecordLinkHandler
    label = Book Reports
    configuration {
        table = tx_news_domain_model_news
        storagePid = 42
        pageTreeMountPoints = 42
        hidePageTree = 0
    }
}
Copied!

The PageTSconfig of the LinkHandler is being used in sysext recordlist in class \TYPO3\CMS\Recordlist\LinkHandler\RecordLinkHandler which does not contain Hooks or Slots.

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!