From 172abb19b9bd0a7c4a74cde5f22288a65c3868e1 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Tue, 10 Sep 2024 15:22:13 +0200 Subject: [PATCH] [TASK] Move linkhandler code snippets to own files. (#4746) In preparation for documenting https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1005 Releases: main, 12.4 (cherry picked from commit a18e40fb69b12f5ab1f5d5a390b930cc65318b4d) --- .../Linkhandler/CustomLinkHandlers.rst | 195 ++---------------- .../_CustomLinkHandlers/_GitHubLinkHandler.js | 31 +++ .../_GitHubLinkHandler.php | 120 +++++++++++ .../_CustomLinkHandlers/_page.tsconfig | 12 ++ 4 files changed, 183 insertions(+), 175 deletions(-) create mode 100644 Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_GitHubLinkHandler.js create mode 100644 Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_GitHubLinkHandler.php create mode 100644 Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_page.tsconfig diff --git a/Documentation/ApiOverview/LinkHandling/Linkhandler/CustomLinkHandlers.rst b/Documentation/ApiOverview/LinkHandling/Linkhandler/CustomLinkHandlers.rst index 0819fa4fc1..897de11f39 100644 --- a/Documentation/ApiOverview/LinkHandling/Linkhandler/CustomLinkHandlers.rst +++ b/Documentation/ApiOverview/LinkHandling/Linkhandler/CustomLinkHandlers.rst @@ -1,6 +1,6 @@ -.. include:: /Includes.rst.txt -.. index:: LinkHandlers; CustomLinkHandlers -.. _customlinkhandler: +.. include:: /Includes.rst.txt +.. index:: LinkHandlers; CustomLinkHandlers +.. _customlinkhandler: ================================= Implementing a custom LinkHandler @@ -16,6 +16,8 @@ The example below is part of the TYPO3 Documentation Team extension `examples and adjust the texts https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/issues/2298 +.. _customlinkhandler-implementation: + Implementing the LinkHandler ============================ @@ -31,188 +33,31 @@ You can have a look at the existing LinkHandler in the system extension 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 :php:`AbstractLinkHandler`, +However please note that all these extensions extend the +:php:`\TYPO3\CMS\Backend\LinkHandler\AbstractLinkHandler`, which is marked as :php:`@internal` and subject to change without further notice. -You should therefore implement the interface :php:`LinkHandlerInterface` in your -custom LinkHandlers: - - -.. code-block:: php - :caption: EXT:some_extension/Classes/LinkHandler/GitHubLinkHandler.php - - 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: - +You should therefore implement the interface +:php:`\TYPO3\CMS\Backend\LinkHandler\LinkHandlerInterface` in your custom +LinkHandlers: -.. code-block:: typoscript - :caption: EXT:some_extension/Configuration/page.tsconfig +.. literalinclude:: _CustomLinkHandlers/_GitHubLinkHandler.php + :caption: EXT:my_extension/Classes/LinkHandler/GitHubLinkHandler.php - 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 - } - } - } +The LinkHandler then has to be registered via page TSconfig: +.. literalinclude:: _CustomLinkHandlers/_page.tsconfig + :caption: EXT:my_extension/Configuration/page.tsconfig And the JavaScript, depending on :ref:`requirejs`, has to be added in a file -:file:`examples/Resources/Public/JavaScript/GitHubLinkHandler.js`: - -.. code-block:: javascript - - /** - * 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; - }); +:file:`Resources/Public/JavaScript/GitHubLinkHandler.js`: + +.. literalinclude:: _CustomLinkHandlers/_GitHubLinkHandler.js + :caption: EXT:my_extension/Resources/Public/JavaScript/GitHubLinkHandler.js This would create a link looking like this: -.. code-block:: html +.. code-block:: html Example Link diff --git a/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_GitHubLinkHandler.js b/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_GitHubLinkHandler.js new file mode 100644 index 0000000000..0541b5b904 --- /dev/null +++ b/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_GitHubLinkHandler.js @@ -0,0 +1,31 @@ +/** + * 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; +}); diff --git a/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_GitHubLinkHandler.php b/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_GitHubLinkHandler.php new file mode 100644 index 0000000000..ef1a3b5b64 --- /dev/null +++ b/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_GitHubLinkHandler.php @@ -0,0 +1,120 @@ +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; + } +} diff --git a/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_page.tsconfig b/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_page.tsconfig new file mode 100644 index 0000000000..6387f4e8db --- /dev/null +++ b/Documentation/ApiOverview/LinkHandling/Linkhandler/_CustomLinkHandlers/_page.tsconfig @@ -0,0 +1,12 @@ +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 + } + } +}