求TYPO3 CMS 11可用自定义LinkHandler示例，官方示例报错

问题描述 #

我在寻找适用于TYPO3 CMS 11的可用自定义LinkHandler示例，但核心文档以及t3docs/examples扩展11.1.1版本中的示例均无法正常运行，报错信息如下：

尝试解析控制器动作"Standard->linkBrowser"的.html格式模板文件，但所有路径中均未找到预期的模板文件（Standard/LinkBrowser.html），已检查路径：/var/www/html/www/typo3/sysext/recordlist/Resources/Private/Templates/LinkBrowser/

以下是涉及的代码文件EXT:some_extension/Classes/LinkHandler/GitHubLinkHandler.php内容：

<?php
namespace T3docs\Examples\LinkHandler;

# use ...
use TYPO3\CMS\Recordlist\LinkHandler\LinkHandlerInterface;

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

   /**
   * 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;
   }
}

问题根源 #

报错核心是LinkHandler的视图配置错误，导致系统试图在核心扩展的模板路径中查找不存在的模板，而非加载自定义扩展的模板。具体问题点：

1. initialize方法中设置的扩展名称与实际使用的扩展不符
2. 模板路径指向了官方示例扩展，而非当前自定义扩展
3. 缺失必要的类引入语句

修复步骤 #

1. 修正视图的扩展名称与模板路径 #

将视图配置指向当前自定义扩展（示例中为some_extension），修改initialize方法中的视图设置部分：

// 替换原视图配置代码
$this->view = GeneralUtility::makeInstance(StandaloneView::class);
// 设置为当前扩展的key，比如'some_extension'
$this->view->getRequest()->setControllerExtensionName('some_extension');
// 模板路径指向当前扩展的LinkBrowser目录
$this->view->setTemplateRootPaths([
    GeneralUtility::getFileAbsFileName('EXT:some_extension/Resources/Private/Templates/LinkBrowser')
]);

2. 补全类引入语句 #

将代码中注释的# use ...替换为完整的依赖引入：

use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Fluid\View\StandaloneView;
use TYPO3\CMS\Recordlist\Controller\AbstractLinkBrowserController;
use TYPO3\CMS\Core\Page\PageRenderer;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Imaging\IconFactory;

3. 创建对应模板文件 #

在自定义扩展目录下创建模板文件EXT:some_extension/Resources/Private/Templates/LinkBrowser/GitHub.html，示例内容：

<div class="form-group">
    <label for="github-link">GitHub链接</label>
    <input type="text" id="github-link" name="github" value="{github}" class="form-control" />
    <p class="help-block">输入GitHub项目或Issue链接，例如：https://github.com/typo3/typo3/issues/12345</p>
</div>

4. 验证Page TSconfig配置 #

确保Page TSconfig中正确注册该LinkHandler，注意命名空间与类路径一致：

TCEMAIN.linkHandler.github {
    handler = T3docs\Examples\LinkHandler\GitHubLinkHandler
    label = GitHub链接
    configuration {
        project = typo3/typo3
        action = issues
    }
    scanAfter = page
}

5. 清除缓存 #

完成上述修改后，清除TYPO3系统缓存，重新打开链接浏览器即可验证修复效果。

内容的提问来源于stack exchange，提问作者Heinz Schilling