Issue #3087499 by andypost, smustgrave, Amber Himes Matz: Merge Help Topics classes into Help with BC layer

core/modules/forum/tests/src/Functional/migrate_drupal/d6/Upgrade6Test.php

@@ -48,7 +48,7 @@ class Upgrade6Test extends MigrateUpgradeExecuteTestBase {
    */
   protected function getEntityCounts() {
     return [
-      'block' => 32,
+      'block' => 33,
       'block_content' => 1,
       'block_content_type' => 1,
       'comment' => 4,
@@ -63,7 +63,7 @@ class Upgrade6Test extends MigrateUpgradeExecuteTestBase {
       'image_style' => 6,
       'node' => 2,
       'node_type' => 7,
-      'search_page' => 2,
+      'search_page' => 3,
       'shortcut' => 2,
       'shortcut_set' => 1,
       'action' => 27,

core/modules/forum/tests/src/Functional/migrate_drupal/d7/Upgrade7Test.php

@@ -61,7 +61,7 @@ class Upgrade7Test extends MigrateUpgradeExecuteTestBase {
    */
   protected function getEntityCounts() {
     return [
-      'block' => 25,
+      'block' => 26,
       'block_content' => 1,
       'block_content_type' => 1,
       'comment' => 0,
@@ -76,7 +76,7 @@ class Upgrade7Test extends MigrateUpgradeExecuteTestBase {
       'image_style' => 7,
       'node' => 2,
       'node_type' => 4,
-      'search_page' => 2,
+      'search_page' => 3,
       'shortcut' => 2,
       'shortcut_set' => 1,
       'action' => 27,

core/modules/help/config/optional/search.page.help_search.yml

@@ -2,7 +2,7 @@ langcode: en
 status: true
 dependencies:
   module:
-    - help_topics
+    - help
 id: help_search
 label: Help
 path: help

core/modules/help/help.api.php

@@ -7,6 +7,36 @@
 
 use Drupal\Core\Url;
 
+/**
+ * @defgroup help_docs Help and documentation
+ * @{
+ * Documenting modules, themes, and install profiles
+ *
+ * @section sec_topics Help Topics
+ * Modules, themes, and install profiles can have a subdirectory help_topics
+ * that contains one or more Help Topics, to provide help to administrative
+ * users. These are shown on the main admin/help page. See
+ * @link https://www.drupal.org/docs/develop/documenting-your-project/help-topic-standards Help Topic Standards @endlink
+ * for more information.
+ *
+ * @section sec_hook hook_help
+ * Modules can implement hook_help() to provide a module overview (shown on the
+ * main admin/help page). This hook implementation can also provide help text
+ * that is shown in the Help block at the top of administrative pages. See the
+ * hook_help() documentation and
+ * @link https://www.drupal.org/docs/develop/documenting-your-project/help-text-standards Help text standards @endlink
+ * for more information.
+ *
+ * @section sec_tour Tours
+ * Modules can provide tours of administrative pages by creating tour config
+ * files and placing them in their config/optional subdirectory. See
+ * @link https://www.drupal.org/docs/8/api/tour-api/overview Tour API overview @endlink
+ * for more information. The contributed
+ * @link https://www.drupal.org/project/tour_ui Tour UI module @endlink
+ * can also be used to create tour config files.
+ * @}
+ */
+
 /**
  * @addtogroup hooks
  * @{
@@ -79,6 +109,17 @@ function hook_help_section_info_alter(array &$info) {
   $info['hook_help']['weight'] = 500;
 }
 
+/**
+ * Perform alterations on help topic definitions.
+ *
+ * @param array $info
+ *   Array of help topic plugin definitions keyed by their plugin ID.
+ */
+function hook_help_topics_info_alter(array &$info) {
+  // Alter the help topic to be displayed on admin/help.
+  $info['example.help_topic']['top_level'] = TRUE;
+}
+
 /**
  * @} End of "addtogroup hooks".
  */

core/modules/help/help.install

@@ -0,0 +1,98 @@
+<?php
+
+/**
+ * @file
+ * Install and uninstall functions for help module.
+ */
+
+/**
+ * Implements hook_schema().
+ */
+function help_schema() {
+  $schema['help_search_items'] = [
+    'description' => 'Stores information about indexed help search items',
+    'fields' => [
+      'sid' => [
+        'description' => 'Numeric index of this item in the search index',
+        'type' => 'serial',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+      ],
+      'section_plugin_id' => [
+        'description' => 'The help section the item comes from',
+        'type' => 'varchar_ascii',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => '',
+      ],
+      'permission' => [
+        'description' => 'The permission needed to view this item',
+        'type' => 'varchar_ascii',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => '',
+      ],
+      'topic_id' => [
+        'description' => 'The topic ID of the item',
+        'type' => 'varchar_ascii',
+        'length' => 255,
+        'not null' => TRUE,
+        'default' => '',
+      ],
+    ],
+    'primary key' => ['sid'],
+    'indexes' => [
+      'section_plugin_id' => ['section_plugin_id'],
+      'topic_id' => ['topic_id'],
+    ],
+  ];
+
+  return $schema;
+}
+
+/**
+ * Install search index table for help topics.
+ */
+function help_update_10200(&$sandbox = NULL) {
+  $connection = \Drupal::database();
+  if (!$connection->schema()->tableExists('help_search_items')) {
+    $table = [
+      'description' => 'Stores information about indexed help search items',
+      'fields' => [
+        'sid' => [
+          'description' => 'Numeric index of this item in the search index',
+          'type' => 'serial',
+          'unsigned' => TRUE,
+          'not null' => TRUE,
+        ],
+        'section_plugin_id' => [
+          'description' => 'The help section the item comes from',
+          'type' => 'varchar_ascii',
+          'length' => 255,
+          'not null' => TRUE,
+          'default' => '',
+        ],
+        'permission' => [
+          'description' => 'The permission needed to view this item',
+          'type' => 'varchar_ascii',
+          'length' => 255,
+          'not null' => TRUE,
+          'default' => '',
+        ],
+        'topic_id' => [
+          'description' => 'The topic ID of the item',
+          'type' => 'varchar_ascii',
+          'length' => 255,
+          'not null' => TRUE,
+          'default' => '',
+        ],
+      ],
+      'primary key' => ['sid'],
+      'indexes' => [
+        'section_plugin_id' => ['section_plugin_id'],
+        'topic_id' => ['topic_id'],
+      ],
+    ];
+    $connection->schema()->createTable('help_search_items', $table);
+  }
+}

core/modules/help/help.module

@@ -30,17 +30,35 @@ function help_help($route_name, RouteMatchInterface $route_match) {
       return ['#markup' => $output];
 
     case 'help.page.help':
-      $output = '';
-      $output .= '<h3>' . t('About') . '</h3>';
-      $output .= '<p>' . t('The Help module generates <a href=":help-page">Help reference pages</a> to guide you through the use and configuration of modules, and provides a Help block with page-level help. The reference pages are a starting point for <a href=":handbook">Drupal.org online documentation</a> pages that contain more extensive and up-to-date information, are annotated with user-contributed comments, and serve as the definitive reference point for all Drupal documentation. For more information, see the <a href=":help">online documentation for the Help module</a>.', [':help' => 'https://www.drupal.org/documentation/modules/help/', ':handbook' => 'https://www.drupal.org/documentation', ':help-page' => Url::fromRoute('help.main')->toString()]) . '</p>';
+      $help_home = Url::fromRoute('help.main')->toString();
+      $module_handler = \Drupal::moduleHandler();
+      $locale_help = ($module_handler->moduleExists('locale')) ? Url::fromRoute('help.page', ['name' => 'locale'])->toString() : '#';
+      $search_help = ($module_handler->moduleExists('search')) ? Url::fromRoute('help.page', ['name' => 'search'])->toString() : '#';
+      $output = '<h3>' . t('About') . '</h3>';
+      $output .= '<p>' . t('The Help module generates <a href=":help-page">Help topics and reference pages</a> to guide you through the use and configuration of modules, and provides a Help block with page-level help. The reference pages are a starting point for <a href=":handbook">Drupal.org online documentation</a> pages that contain more extensive and up-to-date information, are annotated with user-contributed comments, and serve as the definitive reference point for all Drupal documentation. For more information, see the <a href=":help">online documentation for the Help module</a>.', [':help' => 'https://www.drupal.org/documentation/modules/help/', ':handbook' => 'https://www.drupal.org/documentation', ':help-page' => Url::fromRoute('help.main')->toString()]) . '</p>';
+      $output .= '<p>' . t('Help topics provided by modules and themes are also part of the Help module. If the core Search module is enabled, these topics are searchable. For more information, see the <a href=":online">online documentation for Help Topics</a>.', [':online' => 'https://www.drupal.org/documentation/modules/help_topics']) . '</p>';
       $output .= '<h3>' . t('Uses') . '</h3>';
       $output .= '<dl>';
       $output .= '<dt>' . t('Providing a help reference') . '</dt>';
       $output .= '<dd>' . t('The Help module displays explanations for using each module listed on the main <a href=":help">Help reference page</a>.', [':help' => Url::fromRoute('help.main')->toString()]) . '</dd>';
       $output .= '<dt>' . t('Providing page-specific help') . '</dt>';
       $output .= '<dd>' . t('Page-specific help text provided by modules is displayed in the Help block. This block can be placed and configured on the <a href=":blocks">Block layout page</a>.', [':blocks' => (\Drupal::moduleHandler()->moduleExists('block')) ? Url::fromRoute('block.admin_display')->toString() : '#']) . '</dd>';
+      $output .= '<dt>' . t('Viewing help topics') . '</dt>';
+      $output .= '<dd>' . t('The top-level help topics are listed on the main <a href=":help_page">Help page</a>. Links to other topics, including non-top-level help topics, can be found under the "Related" heading when viewing a topic page.', [':help_page' => $help_home]) . '</dd>';
+      $output .= '<dt>' . t('Providing help topics') . '</dt>';
+      $output .= '<dd>' . t("Modules and themes can provide help topics as Twig-file-based plugins in a project sub-directory called <em>help_topics</em>; plugin meta-data is provided in YAML front matter within each Twig file. Plugin-based help topics provided by modules and themes will automatically be updated when a module or theme is updated. Use the plugins in <em>core/modules/help_topics/help_topics</em> as a guide when writing and formatting a help topic plugin for your theme or module.") . '</dd>';
+      $output .= '<dt>' . t('Translating help topics') . '</dt>';
+      $output .= '<dd>' . t('The title and body text of help topics provided by contributed modules and themes are translatable using the <a href=":locale_help">Interface Translation module</a>. 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' => $locale_help]) . '</dd>';
+      $output .= '<dt>' . t('Configuring help search') . '</dt>';
+      $output .= '<dd>' . t('To search help, you will need to install the core Search module, configure a search page, and add a search block to the Help page or another administrative page. (A search page is provided automatically, and if you use the core Claro administrative theme, a help search block is shown on the main Help page.) Then users with search permissions, and permission to view help, will be able to search help. See the <a href=":search_help">Search module help page</a> for more information.', [':search_help' => $search_help]) . '</dd>';
       $output .= '</dl>';
       return ['#markup' => $output];
+
+    case 'help.help_topic':
+      $help_home = Url::fromRoute('help.main')->toString();
+      return '<p>' . t('See the <a href=":help_page">Help page</a> for more topics.', [
+        ':help_page' => $help_home,
+      ]) . '</p>';
   }
 }
 
@@ -57,6 +75,12 @@ function help_theme($existing, $type, $theme, $path) {
         'empty' => NULL,
       ],
     ],
+    'help_topic' => [
+      'variables' => [
+        'body' => [],
+        'related' => [],
+      ],
+    ],
   ];
 }
 
@@ -77,3 +101,56 @@ function help_block_view_help_block_alter(array &$build, BlockPluginInterface $b
   // the help block, so don't needlessly draw attention to it.
   unset($build['#contextual_links']);
 }
+
+/**
+ * Implements hook_modules_uninstalled().
+ */
+function help_modules_uninstalled(array $modules) {
+  _help_search_update($modules);
+}
+
+/**
+ * Implements hook_themes_uninstalled().
+ */
+function help_themes_uninstalled(array $themes) {
+  _help_search_update();
+}
+
+/**
+ * Implements hook_modules_installed().
+ */
+function help_modules_installed(array $modules, $is_syncing) {
+  _help_search_update();
+}
+
+/**
+ * Implements hook_themes_installed().
+ */
+function help_themes_installed(array $themes) {
+  _help_search_update();
+}
+
+/**
+ * Ensure that search is updated when extensions are installed or uninstalled.
+ *
+ * @param string[] $extensions
+ *   (optional) If modules are being uninstalled, the names of the modules
+ *   being uninstalled. For themes being installed/uninstalled, or modules
+ *   being installed, omit this parameter.
+ */
+function _help_search_update(array $extensions = []): void {
+  // Early return if search is not installed or if we're uninstalling this
+  // module.
+  if (!\Drupal::hasService('plugin.manager.search') ||
+    in_array('help', $extensions)) {
+    return;
+  }
+
+  if (\Drupal::service('update.update_hook_registry')->getInstalledVersion('help') >= 10100) {
+    // Ensure that topics for extensions that have been uninstalled are removed
+    // and that the index state variable is updated.
+    $help_search = \Drupal::service('plugin.manager.search')->createInstance('help_search');
+    $help_search->updateTopicList();
+    $help_search->updateIndexState();
+  }
+}

core/modules/help/help.post_update.php

@@ -0,0 +1,97 @@
+<?php
+
+/**
+ * @file
+ * Post update functions for the Help module.
+ */
+
+use Drupal\search\Entity\SearchPage;
+
+/**
+ * Install or update config for help topics if the search module installed.
+ */
+function help_post_update_help_topics_search() {
+  $module_handler = \Drupal::moduleHandler();
+  if (!$module_handler->moduleExists('search')) {
+    // No dependencies to update or install.
+    return;
+  }
+  if ($module_handler->moduleExists('help_topics')) {
+    if ($page = SearchPage::load('help_search')) {
+      // Resave to update module dependency.
+      $page->save();
+    }
+  }
+  else {
+    $factory = \Drupal::configFactory();
+    // Install optional config for the search page.
+    $config = $factory->getEditable('search.page.help_search');
+    $config->setData([
+      'langcode' => 'en',
+      'status' => TRUE,
+      'dependencies' => [
+        'module' => [
+          'help',
+        ],
+      ],
+      'id' => 'help_search',
+      'label' => 'Help',
+      'path' => 'help',
+      'weight' => 0,
+      'plugin' => 'help_search',
+      'configuration' => [],
+    ])->save(TRUE);
+    if (\Drupal::service('theme_handler')->themeExists('claro') && $factory->get('block.block.claro_help_search')->isNew()) {
+      // Optional block only if it's not created manually earlier.
+      $config = $factory->getEditable('block.block.claro_help_search');
+      $config->setData([
+        'langcode' => 'en',
+        'status' => TRUE,
+        'dependencies' => [
+          'module' => [
+            'search',
+            'system',
+          ],
+          'theme' => [
+            'claro',
+          ],
+          'enforced' => [
+            'config' => [
+              'search.page.help_search',
+            ],
+          ],
+        ],
+        'id' => 'claro_help_search',
+        'theme' => 'claro',
+        'region' => 'help',
+        'weight' => -4,
+        'provider' => NULL,
+        'plugin' => 'search_form_block',
+        'settings' => [
+          'id' => 'search_form_block',
+          'label' => 'Search help',
+          'label_display' => 'visible',
+          'provider' => 'search',
+          'page_id' => 'help_search',
+        ],
+        'visibility' => [
+          'request_path' => [
+            'id' => 'request_path',
+            'negate' => FALSE,
+            'context_mapping' => [],
+            'pages' => '/admin/help',
+          ],
+        ],
+      ])->save(TRUE);
+    }
+  }
+}
+
+/**
+ * Uninstall the help_topics module if installed.
+ */
+function help_post_update_help_topics_uninstall() {
+  if (\Drupal::moduleHandler()->moduleExists('help_topics')) {
+    \Drupal::service('module_installer')->uninstall(['help_topics'], FALSE);
+  }
+}

core/modules/help/help.routing.yml

@@ -13,3 +13,10 @@ help.page:
     _title: 'Help'
   requirements:
     _permission: 'access administration pages'
+
+help.help_topic:
+  path: '/admin/help/topic/{id}'
+  defaults:
+    _controller: '\Drupal\help\Controller\HelpTopicPluginController::viewHelpTopic'
+  requirements:
+    _permission: 'access administration pages'

core/modules/help/help.services.yml

@@ -2,3 +2,28 @@ services:
   plugin.manager.help_section:
     class: Drupal\help\HelpSectionManager
     parent: default_plugin_manager
+    calls:
+      - [setSearchManager, ['@?plugin.manager.search']]
+    tags:
+      - { name: plugin_manager_cache_clear }
+  help.breadcrumb:
+    class: Drupal\help\HelpBreadcrumbBuilder
+    tags:
+      - { name: breadcrumb_builder, priority: 900 }
+    public: false
+  plugin.manager.help_topic:
+    class: Drupal\help\HelpTopicPluginManager
+    arguments: ['@module_handler', '@theme_handler', '@cache.discovery', '%app.root%']
+  Drupal\help\HelpTopicPluginManagerInterface: '@plugin.manager.help_topic'
+  help.twig.loader:
+    class: Drupal\help\HelpTopicTwigLoader
+    arguments: ['%app.root%', '@module_handler', '@theme_handler']
+    # Lowest core priority because loading help topics is not the usual case.
+    tags:
+      - { name: twig.loader, priority: -200 }
+    public: false
+  help_twig.extension:
+    class: Drupal\help\HelpTwigExtension
+    arguments: ['@access_manager', '@plugin.manager.help_topic', '@string_translation']
+    tags:
+      - { name: twig.extension }

core/modules/help/help_topics/help.overview.html.twig

@@ -0,0 +1,26 @@
+---
+label: 'Working with help topics'
+top_level: true
+related:
+- help.help_topic_search
+- locale.translate_strings
+---
+{% set help_link_text %}{% trans %}Help{% endtrans %}{% endset %}
+{% set help_link = render_var(help_route_link(help_link_text, 'help.main')) %}
+{% set translate_text %}{% trans %}User interface translation{% endtrans %}{% endset %}
+{% set translate_link = render_var(help_route_link(translate_text, 'locale.translate_page')) %}
+{% set help_search_topic = render_var(help_topic_link('help.help_topic_search')) %}
+<h2>{% trans %}What is a help topic?{% endtrans %}</h2>
+<p>{% trans %}A help topic describes a concept, or steps to accomplish a task, related to a feature provided by one or more modules or themes. If the core Search module is enabled, these topics are also searchable.{% endtrans %}</p>
+<h2>{% trans %}Where are help topics listed?{% endtrans %}</h2>
+<p>{% trans %}The top-level help topics are listed at {{ help_link }}. Links to other topics, including non-top-level help topics, can be found under the "Related" heading when viewing a topic page.{% endtrans %}</p>
+<h2>{% trans %}How are help topics provided?{% endtrans %}</h2>
+<p>{% trans %}Modules and themes can provide help topics as Twig-file-based plugins in a project sub-directory called <em>help_topics</em>; plugin metadata is provided in YAML front matter within each Twig file. Plugin-based help topics provided by modules and themes will automatically be updated when a module or theme is updated. Use the plugins in <em>core/modules/help/help_topics</em> as a guide when writing and formatting a help topic plugin for your theme or module.{% endtrans %}</p>
+<h2>{% trans %}How are help topics translated?{% endtrans %}</h2>
+<p>{% trans %}The title and body text of help topics provided by contributed modules and themes are translatable using {{ translate_link }} (provided by 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.{% endtrans %}</p>
+<h2>{% trans %}How can users search for help topics?{% endtrans %}</h2>
+<p>{% trans %}To enable users to search help, including help topics, you will need to install the core Search module, configure a search page, and add a search block to the Help page or another administrative page. (A search page is provided automatically, and if you use the core Claro administrative theme, a help search block is shown on the main Help page.) Then users with search permissions, and permission to view help, will be able to search help. See the related topic, {{ help_search_topic }}, for step-by-step instructions.{% endtrans %}</p>
+<h2>{% trans %}Additional resources{% endtrans %}</h2>
+<ul>
+  <li><a href="https://www.drupal.org/node/3074421">{% trans %}Help Topics Standards{% endtrans %}</a></li>
+</ul>