Create a custom link browser

1. Register the custom link browser tab in page TSconfig

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

The following options are of note here:

handler

The backend link handler that we create in step 2.

configuration

Some configuration, available to the backend link handler. This information is not available in the frontend. Therefore in the frontend rendering of the link the information must be stored in another way. In this example we hardcoded it. But you could also make it available by TypoScript Setup or as part of the link that is saved.

For a complete list of available option see Link handler configuration.

2. Create a link browser tab

To create a link browser tab we implement the interface \TYPO3\CMS\Backend\LinkHandler\LinkHandlerInterface .

All backend link handlers provided by the Core extend the abstract class \TYPO3\CMS\Backend\LinkHandler\AbstractLinkHandler . However, this class is marked as @internal and therefore can be changed by the Core Team at any time.

You have the choice of implementing the LinkHandlerInterface yourself by having a look at the AbstractLinkHandler for best practices or to extend the AbstractLinkHandler. In the latter case your code might break on updates though.

In this tutorial, we implement the LinkHandlerInterface directly, as it is best practice not to rely on internal classes.

You can find the complete class in the extension EXT:examples on GitHub: GitHubLinkHandler.

We will explain some of the important methods below:

use TYPO3\CMS\Backend\Controller\AbstractLinkBrowserController;
use TYPO3\CMS\Core\Page\PageRenderer;
use TYPO3\CMS\Core\View\ViewInterface;

class GitHubLinkHandler implements LinkHandlerInterface
{
    protected array $linkAttributes = ['target', 'title', 'class', 'params', 'rel'];

    protected array $linkParts = [];

    protected ViewInterface $view;

    protected array $configuration;

    public function __construct(
        // The page renderer is needed to register the JavaScript
        private readonly PageRenderer $pageRenderer,
    ) {}

    public function initialize(AbstractLinkBrowserController $linkBrowser, $identifier, array $configuration)
    {
        $this->configuration = $configuration;
    }

    public function setView(ViewInterface $view): void
    {
        $this->view = $view;
    }
}

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  T3docs\Examples\LinkHandler\GitHubLinkHandler:
    public: true
    # The link handler keeps a state and can therefore be no singleton
    shared: false

use Psr\Http\Message\ServerRequestInterface;

class GitHubLinkHandler implements LinkHandlerInterface
{
    public function render(ServerRequestInterface $request): string
    {
        $this->pageRenderer->loadJavaScriptModule('@t3docs/examples/github_link_handler.js');
        $this->view->assign('project', $this->configuration['project']);
        $this->view->assign('action', $this->configuration['action']);
        $this->view->assign('linkParts', $this->linkParts);
        $this->view->assign('issue', $this->linkParts['issue'] ?? '');

        return $this->view->render('LinkBrowser/GitHub');
    }
}

/*
 * This file is part of the TYPO3 CMS project.
 *
 * It is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License, either version 2
 * of the License, or any later version.
 *
 * For the full copyright and license information, please read the
 * LICENSE.txt file that was distributed with this source code.
 *
 * The TYPO3 project - inspiring people to share!
 */

import LinkBrowser
	from "@typo3/backend/link-browser.js";

/**
 * Module: @t3docs/examples/github_link_handler.js
 * Github issue link interaction
 */

class GitHubLinkHandler {
	constructor() {
		var form_el = document.getElementById("lgithubform");
		form_el.addEventListener("submit", function(event) {
			event.preventDefault();
			var value = document.getElementById('lgithub').value;
			if (value === 't3://github?issue=') {
				return;
			}
			if (value.indexOf('t3://github?issue=') === 0) {
				value = value.substring(18);
			}
			LinkBrowser.finalizeFunction('t3://github?issue=' + value);
		});
	}
}

export default new GitHubLinkHandler();

<?php

return [
    'dependencies' => ['backend'],
    'imports' => [
        '@t3docs/examples/' => 'EXT:examples/Resources/Public/JavaScript/',
    ],
];

class GitHubLinkHandler implements LinkHandlerInterface
{
    public function canHandleLink(array $linkParts): bool
    {
        if ($linkParts['type'] !== 'github') {
            return false;
        }
        $this->linkParts = $linkParts['url'] ?? [];
        return true;
    }
}

3. Introduce the custom link format

You can find the complete class in the extension EXT:examples on GitHub: GitHubLinkHandling.

Our backend link handler implementation from step 1 saves the link in the custom format t3://github?issue=123 via JavaScript.

This format is only an arbitrary string until we tell TYPO3 how to handle links of the new format by a second class which implements the \TYPO3\CMS\Core\LinkHandling\LinkHandlingInterface .

/**
 * Resolves GitHub Links
 */
class GitHubLinkHandling implements LinkHandlingInterface
{
    protected $baseUrn = 't3://github';

    public function asString(array $parameters): string
    {
        $githubIssue = (int)$parameters['issue'];
        return $this->baseUrn . '?issue=' . $githubIssue;
    }

    public function resolveHandlerData(array $data): array
    {
        return [
            'issue' => (int)$data['issue'],
        ];
    }
}

The method LinkHandlingInterface::asString() creates a string representation from the parameter array.

LinkHandlingInterface::resolveHandlerData() receives the string representation of the link and creates the parameter array from it. For convenience the parameters are already parsed and stored as key-value pairs in an array for you. You can perform further processing here if needed.

4. Render the custom link format in the frontend

The link builder, a class extending the abstract class \TYPO3\CMS\Frontend\Typolink\AbstractTypolinkBuilder is called whenever a link is rendered in the frontend, for example via TypoScript .typolink, by the \TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer::typoLink function or by the \TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder .

use TYPO3\CMS\Frontend\Typolink\LinkResult;
use TYPO3\CMS\Frontend\Typolink\LinkResultInterface;
use TYPO3\CMS\Frontend\Typolink\UnableToLinkException;

/**
 * Builds a TypoLink to a Github issue
 */
class GithubLinkBuilder extends AbstractTypolinkBuilder
{
    private const TYPE_GITHUB = 'github';

    public function build(
        array &$linkDetails,
        string $linkText,
        string $target,
        array $conf
    ): LinkResultInterface {
        $issueId = (int)$linkDetails['issue'];
        if ($issueId < 1) {
            throw new UnableToLinkException(
                '"' . $issueId . '" is not a valid GitHub issue number.',
                // Use the Unix timestamp of the time of creation of this message
                1665304602,
                null,
                $linkText
            );
        }
        $url = 'https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/issues/' . $issueId;

        return (new LinkResult(self::TYPE_GITHUB, $url))
            ->withTarget($target)
            ->withLinkConfiguration($conf)
            ->withLinkText($linkText);
    }
}

The link builder must be registered in ext_localconf.php, so that the correct link builder for the new type can be determined by the calling API:

$GLOBALS['TYPO3_CONF_VARS']['FE']['typolinkBuilder']['github'] =
    \T3docs\Examples\LinkHandler\GithubLinkBuilder::class;

The function AbstractTypolinkBuilder::build() is called with the link configuration and data from the typolink function. If the link can be rendered, it returns a new \TYPO3\CMS\Frontend\Typolink\LinkResultInterface . The actual rendering of the link depends on the context the link is rendered in (for example HTML or JSON).

If the link cannot be built it should throw a \TYPO3\CMS\Frontend\Typolink\UnableToLinkException .