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/
.
Changed in version 12.0
Due to the integration of EXT:recordlist into EXT:backend the path has
changed from
typo3/
to
typo3/
.
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\
,
which is marked as @internal
and subject to change without further notice.
You should therefore implement the interface
\TYPO3\
in your custom
LinkHandlers:
<?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;
}
}
The LinkHandler then has to be registered via 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
}
}
}
And the JavaScript, depending on RequireJS (Deprecated), has to be added in a file
Resources/
:
/**
* 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;
});
This would create a link looking like this:
<a href="github:123">Example Link</a>
Which could, for example, be interpreted by a custom protocol handler on a company computer's operating system.