diff --git a/core/modules/help_topics/help_topics.module b/core/modules/help_topics/help_topics.module index 7b860b5ea8..87d6f67fd7 100644 --- a/core/modules/help_topics/help_topics.module +++ b/core/modules/help_topics/help_topics.module @@ -24,7 +24,7 @@ function help_topics_help($route_name, RouteMatchInterface $route_match) { $output .= '
' . t('Providing help topics') . '
'; $output .= '
' . t("Modules and themes can provide help topics as YAML-file-based plugins in a project sub-directory called help_topics. The content of the topic is contained in a matching Twig file in help_topics/templates. Any file in a module or theme's help_topics directory with the suffix *.help_topic.yml will be discovered by the Help Topic module. Plugin-based help topics provided by modules and themes will automatically be updated when a module or theme is updated. Use the plugins in core/modules/help_topics/help_topics as a guide when writing and formatting a help topic plugin for your theme or module.") . '
'; $output .= '
' . t('Translating help topics') . '
'; - $output .= '
' . t('The title and body text of help topics provided by contributed modules and themes are translatable using the Interface Translation module. Topics provided by custom modules and themes are also translatable if they have been viewed at least once in a non-English language, which triggers putting their translatable text into the translation database.', [':locale_help' => (\Drupal::moduleHandler()->moduleExists('locale')) ? \Drupal::url('help.page', ['name' => 'locale']) : '#']) . '
'; + $output .= '
' . t('The title and body text of help topics provided by contributed modules and themes are translatable using the Interface Translation module. Topics provided by custom modules and themes are also translatable if they have been viewed at least once in a non-English language, which triggers putting their translatable text into the translation database.', [':locale_help' => (\Drupal::moduleHandler()->moduleExists('locale')) ? Url::fromRoute('help.page', ['name' => 'locale'])->toString() : '#']) . '
'; $output .= ''; return ['#markup' => $output]; diff --git a/core/modules/help_topics/src/Controller/HelpTopicPluginController.php b/core/modules/help_topics/src/Controller/HelpTopicPluginController.php index 37eb58a919..8e3a43ddf3 100644 --- a/core/modules/help_topics/src/Controller/HelpTopicPluginController.php +++ b/core/modules/help_topics/src/Controller/HelpTopicPluginController.php @@ -11,6 +11,11 @@ /** * Controller for help topic plugins. + * + * @internal + * Help Topic is currently experimental and should only be leveraged by + * experimental modules and development releases of contributed modules. + * See https://www.drupal.org/core/experimental for more information. */ class HelpTopicPluginController extends ControllerBase { diff --git a/core/modules/help_topics/src/HelpBreadcrumbBuilder.php b/core/modules/help_topics/src/HelpBreadcrumbBuilder.php index e1157c4b97..a98b05fbc2 100644 --- a/core/modules/help_topics/src/HelpBreadcrumbBuilder.php +++ b/core/modules/help_topics/src/HelpBreadcrumbBuilder.php @@ -11,6 +11,11 @@ /** * Provides a breadcrumb builder for help topic pages. + * + * @internal + * Help Topic is currently experimental and should only be leveraged by + * experimental modules and development releases of contributed modules. + * See https://www.drupal.org/core/experimental for more information. */ class HelpBreadcrumbBuilder implements BreadcrumbBuilderInterface { diff --git a/core/modules/help_topics/src/Plugin/HelpSection/HelpTopicSection.php b/core/modules/help_topics/src/Plugin/HelpSection/HelpTopicSection.php index 2b9b8f583d..8bf347df7d 100644 --- a/core/modules/help_topics/src/Plugin/HelpSection/HelpTopicSection.php +++ b/core/modules/help_topics/src/Plugin/HelpSection/HelpTopicSection.php @@ -16,6 +16,11 @@ * description = @Translation("Topics can be provided by modules or themes. Top-level help topics on your site:"), * permission = "access administration pages" * ) + * + * @internal + * Help Topic is currently experimental and should only be leveraged by + * experimental modules and development releases of contributed modules. + * See https://www.drupal.org/core/experimental for more information. */ class HelpTopicSection extends HelpSectionPluginBase implements ContainerFactoryPluginInterface { @@ -74,7 +79,7 @@ public static function create(ContainerInterface $container, array $configuratio */ public function getCacheTags() { if (!isset($this->topicList)) { - $this->calculateTopics(); + $this->setProperties(); } return $this->cacheTagList; @@ -85,29 +90,28 @@ public function getCacheTags() { */ public function listTopics() { if (!isset($this->topicList)) { - $this->calculateTopics(); + $this->setProperties(); } return $this->topicList; } /** - * Calculates the topic list and cache tags. + * Sets the topic list and cache tags properties. */ - protected function calculateTopics() { - /** @var \Drupal\help_topics\Plugin\HelpTopic\HelpTopicPluginInterface[] $plugins */ + protected function setProperties() { $plugins = $this->pluginManager->getTopLevelTopics(); $this->topicList = []; - $cache_tags = []; + $this->cacheTagList = []; foreach ($plugins as $plugin) { $this->topicList[$plugin->getPluginId()] = $plugin->toLink(); foreach ($plugin->getCacheTagsForList() as $tag) { - $cache_tags[] = $tag; + $this->cacheTagList[] = $tag; } } - $this->cacheTagList = array_unique($cache_tags); + $this->cacheTagList = array_unique($this->cacheTagList); } } diff --git a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginBase.php b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginBase.php index 644aa5aa59..68b83a620a 100644 --- a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginBase.php +++ b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginBase.php @@ -4,13 +4,20 @@ use Drupal\Core\Cache\Cache; use Drupal\Core\Link; +use Drupal\Core\Plugin\ContainerFactoryPluginInterface; use Drupal\Core\Plugin\PluginBase; use Drupal\Core\Url; +use Symfony\Component\DependencyInjection\ContainerInterface; /** * Base class for help topic plugins. + * + * @internal + * Help Topic is currently experimental and should only be leveraged by + * experimental modules and development releases of contributed modules. + * See https://www.drupal.org/core/experimental for more information. */ -abstract class HelpTopicPluginBase extends PluginBase implements HelpTopicPluginInterface { +abstract class HelpTopicPluginBase extends PluginBase implements HelpTopicPluginInterface, ContainerFactoryPluginInterface { /** * The help topic plugin manager. @@ -19,6 +26,35 @@ */ protected $pluginManager; + /** + * HelpTopicPluginBase constructor. + * + * @param array $configuration + * A configuration array containing information about the plugin instance. + * @param string $plugin_id + * The plugin_id for the plugin instance. + * @param mixed $plugin_definition + * The plugin implementation definition. + * @param \Drupal\help_topics\Plugin\HelpTopic\HelpTopicPluginManagerInterface $plugin_manager + * The help topic plugin manager. + */ + public function __construct(array $configuration, $plugin_id, $plugin_definition, HelpTopicPluginManagerInterface $plugin_manager) { + parent::__construct($configuration, $plugin_id, $plugin_definition); + $this->pluginManager = $plugin_manager; + } + + /** + * {@inheritdoc} + */ + public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) { + return new static( + $configuration, + $plugin_id, + $plugin_definition, + $container->get('plugin.manager.help_topic') + ); + } + /** * The name of the module or theme providing the help topic. */ @@ -68,37 +104,6 @@ public function getCacheContexts() { return []; } - /** - * Gets the help topic plugin manager. - * - * @return \Drupal\help_topics\Plugin\HelpTopic\HelpTopicPluginManagerInterface - * The help topic plugin manager. - */ - protected function getPluginManager() { - if (!isset($this->pluginManager)) { - $this->pluginManager = \Drupal::service('plugin.manager.help_topic'); - } - return $this->pluginManager; - } - - /** - * Makes a cache tag from a help topic plugin ID. - * - * @param string $id - * The plugin ID to make a cache tag from. - * - * @return string|null - * The main cache tag for the topic, or NULL if there is not one. - */ - protected function makeCacheTag($id) { - $definition = $this->getPluginManager()->getDefinition($id); - if (!$definition) { - return NULL; - } - - return $definition['cache_tag']; - } - /** * {@inheritdoc} */ @@ -109,12 +114,12 @@ public function getCacheTags() { } foreach ($this->pluginDefinition['related'] as $topic) { - $tag = $this->makeCacheTag($topic); + $tag = $this->pluginManager->getDefinition($topic)['cache_tag']; if ($tag) { $tags[] = $tag; } } - return $tags; + return array_unique($tags); } /** diff --git a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginInterface.php b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginInterface.php index f2d0c60747..c81a655992 100644 --- a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginInterface.php +++ b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginInterface.php @@ -14,6 +14,11 @@ * implementation relies on a corresponding Twig template. * * @see \Drupal\help_topics\Plugin\HelpTopic\HelpTopicTwig + * + * @internal + * Help Topic is currently experimental and should only be leveraged by + * experimental modules and development releases of contributed modules. + * See https://www.drupal.org/core/experimental for more information. */ interface HelpTopicPluginInterface extends PluginInspectionInterface, DerivativeInspectionInterface, CacheableDependencyInterface { diff --git a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginManager.php b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginManager.php index fa2ed0d642..573dac6366 100644 --- a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginManager.php +++ b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginManager.php @@ -17,6 +17,11 @@ * help_topics. * * @see \Drupal\help_topics\Plugin\HelpTopic\HelpTopicTwig + * + * @internal + * Help Topic is currently experimental and should only be leveraged by + * experimental modules and development releases of contributed modules. + * See https://www.drupal.org/core/experimental for more information. */ class HelpTopicPluginManager extends DefaultPluginManager implements HelpTopicPluginManagerInterface { @@ -180,7 +185,7 @@ public function getTopLevelTopics() { } ksort($topics); - return $topics; + return array_values($topics); } /** @@ -198,22 +203,6 @@ public function getAllListOn($id) { return $topics; } - /** - * {@inheritdoc} - */ - public function findMatches($text) { - $topics = []; - foreach ($this->getDefinitions() as $definition) { - if ((stripos($definition['id'], $text) !== FALSE) || - (stripos($definition['label'], $text) !== FALSE)) { - $topics[$definition['label']] = $definition['id']; - } - } - - ksort($topics); - return $topics; - } - /** * {@inheritdoc} */ diff --git a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginManagerInterface.php b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginManagerInterface.php index 0a7f327d98..dd616b1920 100644 --- a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginManagerInterface.php +++ b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicPluginManagerInterface.php @@ -6,6 +6,11 @@ /** * Defines an interface for managing help topics and storing their definitions. + * + * @internal + * Help Topic is currently experimental and should only be leveraged by + * experimental modules and development releases of contributed modules. + * See https://www.drupal.org/core/experimental for more information. */ interface HelpTopicPluginManagerInterface extends PluginManagerInterface { @@ -29,19 +34,6 @@ public function getTopLevelTopics(); */ public function getAllListOn($id); - /** - * Returns a list of autocomplete matches for the given text. - * - * @param string $text - * Text to match. - * - * @return string[] - * Array of matching topic IDs, keyed by topic title, where $text matches - * a substring of the title (in its base language) or ID, with case- - * insensitive matching. Returned in alphabetic order by title. - */ - public function findMatches($text); - /** * Gets information about theme implementations for help topics. * diff --git a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicTwig.php b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicTwig.php index 84a217076e..c67dc36c56 100644 --- a/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicTwig.php +++ b/core/modules/help_topics/src/Plugin/HelpTopic/HelpTopicTwig.php @@ -3,7 +3,6 @@ namespace Drupal\help_topics\Plugin\HelpTopic; use Drupal\Core\Plugin\ContainerFactoryPluginInterface; -use Symfony\Component\DependencyInjection\ContainerInterface; use Drupal\Core\StringTranslation\TranslatableMarkup; use Drupal\Component\Utility\Html; @@ -17,44 +16,14 @@ * topic ID used in the YAML file, with the underscores swapped for hyphens. * For example: help_topics/basic_pages.help_topic.yml would have a * corresponding help_topics/templates/help-topic-basic-pages.html.twig. + * + * @internal + * Help Topic is currently experimental and should only be leveraged by + * experimental modules and development releases of contributed modules. + * See https://www.drupal.org/core/experimental for more information. */ class HelpTopicTwig extends HelpTopicPluginBase implements ContainerFactoryPluginInterface { - /** - * Constructs a HelpTopicTwig. - * - * @param \Symfony\Component\DependencyInjection\ContainerInterface $container - * The dependency injection container. - * @param array $configuration - * The plugin configuration (not actually used). - * @param string $plugin_id - * The plugin ID. - * @param array $plugin_definition - * The plugin definition. - */ - public function __construct(ContainerInterface $container, array $configuration, $plugin_id, array $plugin_definition) { - $this->stringTranslation = $container->get('string_translation'); - parent::__construct($configuration, $plugin_id, $plugin_definition); - } - - /** - * Creates a HelpTopicDefaultPlugin. - * - * @param \Symfony\Component\DependencyInjection\ContainerInterface $container - * The dependency injection container. - * @param array $configuration - * The plugin configuration (not actually used). - * @param string $plugin_id - * The plugin ID. - * @param array $plugin_definition - * The plugin definition. - * - * @return static - */ - public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) { - return new static($container, $configuration, $plugin_id, $plugin_definition); - } - /** * {@inheritdoc} */ diff --git a/core/modules/help_topics/tests/src/Functional/HelpTopicTest.php b/core/modules/help_topics/tests/src/Functional/HelpTopicTest.php index bbd0e0ad94..344a4e84f0 100644 --- a/core/modules/help_topics/tests/src/Functional/HelpTopicTest.php +++ b/core/modules/help_topics/tests/src/Functional/HelpTopicTest.php @@ -91,7 +91,6 @@ public function testHelp() { $session->responseContains('

Topics

'); $session->pageTextContains('Topics can be provided by modules or themes'); - // Verify links for for help topics and order. $page_text = $this->getTextContent(); $start = strpos($page_text, 'Topics can be provided'); @@ -202,4 +201,5 @@ public function testBreadCrumb() { $this->assertBreadcrumb('admin/help/topic/help_test', $trail); } + }