Implementing a custom LinkHandler

It is possible to implement a custom LinkHandler if links are to be created and handled that cannot be handled by any of the Core LinkHandlers.

The example below is part of the TYPO3 Documentation Team extension examples.

Implementing the LinkHandler

You can have a look at the existing LinkHandler in the system extension "backend", found at typo3/sysext/backend/Classes/LinkHandler.

Changed in version 12.0

Due to the integration of EXT:recordlist into EXT:backend the path has changed from typo3/sysext/recordlist/Classes/LinkHandler to typo3/sysext/backend/Classes/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.

However please note that all these extensions extend the \TYPO3\CMS\Backend\LinkHandler\AbstractLinkHandler , which is marked as @internal and subject to change without further notice.

You should therefore implement the interface \TYPO3\CMS\Backend\LinkHandler\LinkHandlerInterface in your custom LinkHandlers:

EXT:my_extension/Classes/LinkHandler/GitHubLinkHandler.php
<?php

namespace T3docs\Examples\LinkHandler;

// use ...
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Backend\Controller\AbstractLinkBrowserController;
use TYPO3\CMS\Backend\LinkHandler\LinkHandlerInterface;
use TYPO3\CMS\Core\Imaging\IconFactory;
use TYPO3\CMS\Core\Page\PageRenderer;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Fluid\View\StandaloneView;

class GitHubLinkHandler implements LinkHandlerInterface
{
    protected $linkAttributes = ['target', 'title', 'class', 'params', 'rel'];
    protected StandaloneView $view;
    protected $configuration;
    private IconFactory $iconFactory;
    private AbstractLinkBrowserController $linkBrowser;
    private array $linkParts;

    /**
     * Initialize the handler
     *
     * @param AbstractLinkBrowserController $linkBrowser
     * @param string $identifier
     * @param array $configuration Page TSconfig
     */
    public function initialize(AbstractLinkBrowserController $linkBrowser, $identifier, array $configuration)
    {
        $this->linkBrowser = $linkBrowser;
        $this->iconFactory = GeneralUtility::makeInstance(IconFactory::class);
        $this->view = GeneralUtility::makeInstance(StandaloneView::class);
        $this->view->getRequest()->setControllerExtensionName('examples');
        $this->view->setTemplateRootPaths([GeneralUtility::getFileAbsFileName('EXT:examples/Resources/Private/Templates/LinkBrowser')]);
        $this->configuration = $configuration;
    }

    /**
     * Checks if this is the handler for the given link
     *
     * Also stores information locally about currently linked issue
     *
     * @param array $linkParts Link parts as returned from TypoLinkCodecService
     *
     * @return bool
     */
    public function canHandleLink(array $linkParts)
    {
        if (isset($linkParts['url']['github'])) {
            $this->linkParts = $linkParts;
            return true;
        }
        return false;
    }

    /**
     * Format the current link for HTML output
     *
     * @return string
     */
    public function formatCurrentUrl(): string
    {
        return $this->linkParts['url']['github'];
    }

    /**
     * Render the link handler
     *
     * @param ServerRequestInterface $request
     *
     * @return string
     */
    public function render(ServerRequestInterface $request): string
    {
        GeneralUtility::makeInstance(PageRenderer::class)
            ->loadRequireJsModule('TYPO3/CMS/Examples/GitHubLinkHandler');

        $this->view->assign('project', $this->configuration['project']);
        $this->view->assign('action', $this->configuration['action']);
        $this->view->assign('github', !empty($this->linkParts) ? $this->linkParts['url']['github'] : '');
        return $this->view->render('GitHub');
    }

    /**
     * @return string[] Array of body-tag attributes
     */
    public function getBodyTagAttributes(): array
    {
        return [];
    }

    /**
     * @return array
     */
    public function getLinkAttributes()
    {
        return $this->linkAttributes;
    }

    /**
     * @param string[] $fieldDefinitions Array of link attribute field definitions
     * @return string[]
     */
    public function modifyLinkAttributes(array $fieldDefinitions)
    {
        return $fieldDefinitions;
    }

    /**
     * We don't support updates since there is no difference to simply set the link again.
     *
     * @return bool
     */
    public function isUpdateSupported()
    {
        return false;
    }
}
Copied!

The LinkHandler then has to be registered via page TSconfig:

EXT:my_extension/Configuration/page.tsconfig
TCEMAIN.linkHandler {
  github {
    handler = T3docs\\Examples\\LinkHandler\\GitHubLinkHandler
    label = LLL:EXT:examples/Resources/Private/Language/locallang_browse_links.xlf:github
    displayAfter = url
    scanBefore = url
    configuration {
      project = TYPO3-Documentation/TYPO3CMS-Reference-CoreApi
      action = issues
    }
  }
}
Copied!

And the JavaScript, depending on RequireJS (Deprecated), has to be added in a file Resources/Public/JavaScript/GitHubLinkHandler.js:

EXT:my_extension/Resources/Public/JavaScript/GitHubLinkHandler.js
/**
 * Module: TYPO3/CMS/Examples/GitHubLinkHandler
 * GitHub issue link interaction
 */
define(['jquery', 'TYPO3/CMS/Recordlist/LinkBrowser'], function($, LinkBrowser) {
  'use strict';

  /**
   *
   * @type {{}}
   * @exports T3docs/Examples/GitHubLinkHandler
   */
  var GitHubLinkHandler = {};

  $(function() {
    $('#lgithubform').on('submit', function(event) {
      event.preventDefault();

      var value = $(this).find('[name="lgithub"]').val();
      if (value === 'github:') {
        return;
      }
      if (value.indexOf('github:') === 0) {
        value = value.substr(7);
      }
      LinkBrowser.finalizeFunction('github:' + value);
    });
  });

  return GitHubLinkHandler;
});
Copied!

This would create a link looking like this:

<a href="github:123">Example Link</a>
Copied!

Which could, for example, be interpreted by a custom protocol handler on a company computer's operating system.