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

Note

In the system extension core there are also classes ending on "LinkHandler". However those implement the interface LinkHandlingInterface and are part of the LinkHandling API, not the LinkHandler API.

The following LinkHandlers are of interest:

• The PageLinkHandler
• The RecordLinkHandler
• Implementing a custom LinkHandler

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
       }
   }
   

   Important

   Do not change the identifier after links have been created using the LinkHandler. The identifier will be stored as part of the link in the database.

LinkHandler page TSconfig options

The minimal PageTSconfig 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
    }
}

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:

scanAfter = page or scanBefore = page

define the order in which handlers are queried when determining the responsible tab for an existing link

displayBefore = page or displayAfter = page

define the order how the various tabs are displayed in the link browser.

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
}

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
    }
}

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.

Enable page id field

It is possible to enable an additional field in the link browser to enter the uid of a page. The uid will be used directly instead of selecting it from the page tree.

This only works for the PageLinkHandler. It will not work for custom added LinkHandler configurations.

Enable the field with the following page TSConfig:

EXT:some_extension/Configuration/page.tsconfig

TCEMAIN.linkHandler.page.configuration.pageIdSelector.enabled = 1

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]=|
    }
}

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]=|
   }
}

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]=|
   }
}