Issue #2263359 by jhodgdon: hook_help(): Top of page help sections can't link...

Issue #2263359 by jhodgdon: hook_help(): Top of page help sections can't link to help pages without a fatal error or checking for help module

core/modules/aggregator/src/Tests/ImportOpmlTest.php

@@ -19,7 +19,7 @@ class ImportOpmlTest extends AggregatorTestBase {
    *
    * @var array
    */
-  public static $modules = array('block');
+  public static $modules = array('block', 'help');
 
   protected function setUp() {
     parent::setUp();
@@ -33,7 +33,7 @@ protected function setUp() {
    */
   function openImportForm() {
     // Enable the help block.
-    $this->drupalPlaceBlock('system_help_block', array('region' => 'help'));
+    $this->drupalPlaceBlock('help_block', array('region' => 'help'));
 
     $this->drupalGet('admin/config/services/aggregator/add/opml');
     $this->assertText('A single OPML document may contain many feeds.', 'Found OPML help text.');

core/modules/block/src/Tests/BlockTest.php

@@ -215,7 +215,7 @@ public function testBlockThemeSelector() {
    */
   function testThemeName() {
     // Enable the help block.
-    $this->drupalPlaceBlock('system_help_block', array('region' => 'help'));
+    $this->drupalPlaceBlock('help_block', array('region' => 'help'));
     // Explicitly set the default and admin themes.
     $theme = 'block_test_specialchars_theme';
     \Drupal::service('theme_handler')->install(array($theme));

core/modules/block/src/Tests/BlockTestBase.php

@@ -19,7 +19,7 @@ abstract class BlockTestBase extends WebTestBase {
    *
    * @var array
    */
-  public static $modules = array('block', 'filter', 'test_page_test');
+  public static $modules = array('block', 'filter', 'test_page_test', 'help');
 
   /**
    * A list of theme regions to test.

core/modules/block/src/Tests/BlockUiTest.php

@@ -21,7 +21,7 @@ class BlockUiTest extends WebTestBase {
    *
    * @var array
    */
-  public static $modules = array('block', 'block_test');
+  public static $modules = array('block', 'block_test', 'help');
 
   protected $regions;
 
@@ -80,7 +80,7 @@ protected function setUp() {
    * Test block demo page exists and functions correctly.
    */
   public function testBlockDemoUiPage() {
-    $this->drupalPlaceBlock('system_help_block', array('region' => 'help'));
+    $this->drupalPlaceBlock('help_block', array('region' => 'help'));
     $this->drupalGet('admin/structure/block');
     $this->clickLink(t('Demonstrate block regions (@theme)', array('@theme' => 'Classy')));
     $elements = $this->xpath('//div[contains(@class, "region-highlighted")]/div[contains(@class, "block-region") and contains(text(), :title)]', array(':title' => 'Highlighted'));

core/modules/forum/src/Tests/ForumTest.php

@@ -99,7 +99,7 @@ protected function setUp() {
       'skip comment approval',
       'access comments',
     ));
-    $this->drupalPlaceBlock('system_help_block', array('region' => 'help'));
+    $this->drupalPlaceBlock('help_block', array('region' => 'help'));
   }
 
   /**

core/modules/help/help.api.php

+/**
+ * @file
+ * Hooks for the Help system.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Provide online user help.
+ *
+ * By implementing hook_help(), a module can make documentation available to
+ * the user for the module as a whole, or for specific pages. Help for
+ * developers should usually be provided via function header comments in the
+ * code, or in special API example files.
+ *
+ * The page-specific help information provided by this hook appears in the
+ * Help block (provided by the core Help module), if the block is displayed on
+ * that page. The module overview help information is displayed by the Help
+ * module. It can be accessed from the page at admin/help or from the Extend
+ * Extend page.
+ *
+ * For detailed usage examples of:
+ * - Module overview help, see content_translation_help(). Module overview
+ *   help should follow
+ *   @link https://drupal.org/node/632280 the standard help template. @endlink
+ * - Page-specific help using only routes, see book_help().
+ * - Page-specific help using routes and $request, see block_help().
+ *
+ * @param string $route_name
+ *   For page-specific help, use the route name as identified in the
+ *   module's routing.yml file. For module overview help, the route name
+ *   will be in the form of "help.page.$modulename".
+ * @param Drupal\Core\Routing\RouteMatchInterface $route_match
+ *   The current route match. This can be used to generate different help
+ *   output for different pages that share the same route.
+ *
+ * @return string
+ *   A localized string containing the help text.
+ */
+function hook_help($route_name, \Drupal\Core\Routing\RouteMatchInterface $route_match) {
+  switch ($route_name) {
+    // Main module help for the block module.
+    case 'help.page.block':
+      return '<p>' . t('Blocks are boxes of content rendered into an area, or region, of a web page. The default theme Bartik, for example, implements the regions "Sidebar first", "Sidebar second", "Featured", "Content", "Header", "Footer", etc., and a block may appear in any one of these areas. The <a href="!blocks">blocks administration page</a> provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions.', array('!blocks' => \Drupal::url('block.admin_display'))) . '</p>';
+
+    // Help for another path in the block module.
+    case 'block.admin_display':
+      return '<p>' . t('This page provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions. Since not all themes implement the same regions, or display regions in the same way, blocks are positioned on a per-theme basis. Remember that your changes will not be saved until you click the <em>Save blocks</em> button at the bottom of the page.') . '</p>';
+  }
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */

core/modules/help/help.module

@@ -6,6 +6,7 @@
  */
 
 use Drupal\Core\Routing\RouteMatchInterface;
+use Drupal\Core\Block\BlockPluginInterface;
 
 /**
  * Implements hook_help().
@@ -30,11 +31,13 @@ function help_help($route_name, RouteMatchInterface $route_match) {
     case 'help.page.help':
       $output = '';
       $output .= '<h3>' . t('About') . '</h3>';
-      $output .= '<p>' . t('The Help module provides <a href="!help-page">Help reference pages</a> to guide you through the use and configuration of modules. It is 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>.', array('!help' => 'https://drupal.org/documentation/modules/help/', '!handbook' => 'https://drupal.org/documentation', '!help-page' => \Drupal::url('help.main'))) . '</p>';
+      $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>.', array('!help' => 'https://drupal.org/documentation/modules/help/', '!handbook' => 'https://drupal.org/documentation', '!help-page' => \Drupal::url('help.main'))) . '</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>.', array('!help' => \Drupal::url('help.main'))) . '</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>.', array('!blocks' => (\Drupal::moduleHandler()->moduleExists('block')) ? \Drupal::url('block.admin_display') : '#')) . '</dd>';
       $output .= '</dl>';
       return $output;
   }
@@ -44,7 +47,16 @@ function help_help($route_name, RouteMatchInterface $route_match) {
  * Implements hook_preprocess_HOOK() for block templates.
  */
 function help_preprocess_block(&$variables) {
-  if ($variables['plugin_id'] == 'system_help_block') {
+  if ($variables['plugin_id'] == 'help_block') {
     $variables['attributes']['role'] = 'complementary';
   }
 }
+
+/**
+ * Implements hook_block_view_BASE_BLOCK_ID_alter().
+ */
+function help_block_view_help_block_alter(array &$build, BlockPluginInterface $block) {
+  // Assume that most users do not need or want to perform contextual actions on
+  // the help block, so don't needlessly draw attention to it.
+  unset($build['#contextual_links']);
+}

core/modules/system/src/Plugin/Block/SystemHelpBlock.php → core/modules/help/src/Plugin/Block/HelpBlock.php

@@ -2,10 +2,10 @@
 
 /**
  * @file
- * Contains \Drupal\system\Plugin\Block\SystemHelpBlock.
+ * Contains \Drupal\help\Plugin\Block\HelpBlock.
  */
 
-namespace Drupal\system\Plugin\Block;
+namespace Drupal\help\Plugin\Block;
 
 use Drupal\Core\Block\BlockBase;
 use Drupal\Core\Extension\ModuleHandlerInterface;
@@ -16,14 +16,14 @@
 use Symfony\Component\HttpFoundation\Request;
 
 /**
- * Provides a 'System Help' block.
+ * Provides a 'Help' block.
  *
  * @Block(
- *   id = "system_help_block",
- *   admin_label = @Translation("System Help")
+ *   id = "help_block",
+ *   admin_label = @Translation("Help")
  * )
  */
-class SystemHelpBlock extends BlockBase implements ContainerFactoryPluginInterface {
+class HelpBlock extends BlockBase implements ContainerFactoryPluginInterface {
 
   /**
    * Stores the help text associated with the active menu item.
@@ -54,7 +54,7 @@ class SystemHelpBlock extends BlockBase implements ContainerFactoryPluginInterfa
   protected $routeMatch;
 
   /**
-   * Creates a SystemHelpBlock instance.
+   * Creates a HelpBlock instance.
    *
    * @param array $configuration
    *   A configuration array containing information about the plugin instance.
@@ -128,8 +128,8 @@ public function build() {
    * {@inheritdoc}
    */
   public function defaultConfiguration() {
-    // Modify the default max age for the System Help block: help text is static
-    // for a given URL, except when a module is updated, in which case
+    // Modify the default max age for the Help block: help text is
+    // static for a given URL, except when a module is updated, in which case
     // update.php must be run, which clears all caches. Thus it's safe to cache
     // the output for this block forever on a per-URL basis.
     return array('cache' => array('max_age' => \Drupal\Core\Cache\Cache::PERMANENT));
@@ -139,7 +139,7 @@ public function defaultConfiguration() {
    * {@inheritdoc}
    */
   protected function getRequiredCacheContexts() {
-    // The "System Help" block must be cached per URL: help is defined for a
+    // The "Help" block must be cached per URL: help is defined for a
     // given path, and does not come with any access restrictions.
     return array('cache_context.url');
   }

core/modules/node/src/Tests/NodeHelpTest.php

@@ -51,7 +51,7 @@ protected function setUp() {
     ));
 
     $this->drupalLogin($admin_user);
-    $this->drupalPlaceBlock('system_help_block');
+    $this->drupalPlaceBlock('help_block');
 
     $this->testType = 'type';
     $this->testText = t('Help text to find on node forms.');

core/modules/node/src/Tests/NodeTranslationUITest.php

@@ -23,7 +23,7 @@ class NodeTranslationUITest extends ContentTranslationUITest {
    *
    * @var array
    */
-  public static $modules = array('block', 'language', 'content_translation', 'node', 'datetime', 'field_ui');
+  public static $modules = array('block', 'language', 'content_translation', 'node', 'datetime', 'field_ui', 'help');
 
   /**
    * The profile to install as a basis for testing.
@@ -38,7 +38,7 @@ protected function setUp() {
     parent::setUp();
 
     // Ensure the help message is shown even with prefixed paths.
-    $this->drupalPlaceBlock('system_help_block', array('region' => 'content'));
+    $this->drupalPlaceBlock('help_block', array('region' => 'content'));
 
     // Display the language selector.
     $this->drupalLogin($this->administrator);

core/modules/system/system.api.php

@@ -375,49 +375,6 @@ function hook_system_breadcrumb_alter(array &$breadcrumb, \Drupal\Core\Routing\R
   $breadcrumb[] = Drupal::l(t('Text'), 'example_route_name');
 }
 
-/**
- * Provide online user help.
- *
- * By implementing hook_help(), a module can make documentation available to
- * the user for the module as a whole, or for specific pages. Help for
- * developers should usually be provided via function header comments in the
- * code, or in special API example files.
- *
- * The page-specific help information provided by this hook appears as a system
- * help block on that page. The module overview help information is displayed
- * by the Help module. It can be accessed from the page at admin/help or from
- * the Extend page.
- *
- * For detailed usage examples of:
- * - Module overview help, see content_translation_help(). Module overview
- *   help should follow
- *   @link https://drupal.org/node/632280 the standard help template. @endlink
- * - Page-specific help using only routes, see book_help().
- * - Page-specific help using routes and $request, see block_help().
- *
- * @param string $route_name
- *   For page-specific help, use the route name as identified in the
- *   module's routing.yml file. For module overview help, the route name
- *   will be in the form of "help.page.$modulename".
- * @param Drupal\Core\Routing\RouteMatchInterface $route_match
- *   The current route match. This can be used to generate different help
- *   output for different pages that share the same route.
- *
- * @return string
- *   A localized string containing the help text.
- */
-function hook_help($route_name, \Drupal\Core\Routing\RouteMatchInterface $route_match) {
-  switch ($route_name) {
-    // Main module help for the block module.
-    case 'help.page.block':
-      return '<p>' . t('Blocks are boxes of content rendered into an area, or region, of a web page. The default theme Bartik, for example, implements the regions "Sidebar first", "Sidebar second", "Featured", "Content", "Header", "Footer", etc., and a block may appear in any one of these areas. The <a href="!blocks">blocks administration page</a> provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions.', array('!blocks' => \Drupal::url('block.admin_display'))) . '</p>';
-
-    // Help for another path in the block module.
-    case 'block.admin_display':
-      return '<p>' . t('This page provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions. Since not all themes implement the same regions, or display regions in the same way, blocks are positioned on a per-theme basis. Remember that your changes will not be saved until you click the <em>Save blocks</em> button at the bottom of the page.') . '</p>';
-  }
-}
-
 /**
  * Prepare a message based on parameters; called from drupal_mail().
  *

core/modules/system/system.module

@@ -87,11 +87,9 @@ function system_help($route_name, RouteMatchInterface $route_match) {
       $output .= '<dd>' . t('In order for the site and its modules to continue to operate well, a set of routine administrative operations must run on a regular basis. The System module manages this task by making use of a system cron job. You can verify the status of cron tasks by visiting the <a href="@status">Status report page</a>. For more information, see the online handbook entry for <a href="@handbook">configuring cron jobs</a>. You can set up cron job by visiting <a href="@cron">Cron configuration</a> page', array('@status' => \Drupal::url('system.status'), '@handbook' => 'http://drupal.org/cron', '@cron' => \Drupal::url('system.cron_settings'))) . '</dd>';
       $output .= '<dt>' . t('Configuring basic site settings') . '</dt>';
       $output .= '<dd>' . t('The System module also handles basic configuration options for your site, including <a href="@date-time-settings">Date and time settings</a>, <a href="@file-system">File system settings</a>, <a href="@site-info">Site name and other information</a>, and a <a href="@maintenance-mode">Maintenance mode</a> for taking your site temporarily offline.', array('@date-time-settings' => \Drupal::url('system.date_format_list'), '@file-system' => \Drupal::url('system.file_system_settings'), '@site-info' => \Drupal::url('system.site_information_settings'), '@maintenance-mode' => \Drupal::url('system.site_maintenance_mode'))) . '</dd>';
-      $output .= '<dt>' . t('Providing administrative help') . '</dt>';
-      $output .= '<dd>' . t('Page-specific administrative help text that is provided by the System module and other modules is displayed in the System Help block. This block can be placed and configured on the <a href="!blocks">Block layout page</a>.', array('!blocks' => (\Drupal::moduleHandler()->moduleExists('block')) ? \Drupal::url('block.admin_display') : '#')) . '</dd>';
-      $output .= '</dl>';
       $output .= '<dt>' . t('Disabling drag-and-drop functionality') . '</dt>';
       $output .= '<dd>' . t('The default drag-and-drop user interface for ordering tables in Drupal presents a challenge for some users, including users of screen readers and other assistive technology. The drag-and-drop interface can be disabled in a table by clicking a link labeled "Show row weights" above the table. The replacement interface allows users to order the table by choosing numerical weights instead of dragging table rows.') . '</dd>';
+      $output .= '</dl>';
       return $output;
 
     case 'system.admin_index':
@@ -761,10 +759,6 @@ function system_preprocess_block(&$variables) {
     case 'system_powered_by_block':
       $variables['attributes']['role'] = 'complementary';
       break;
-
-    case 'system_help_block':
-      $variables['attributes']['role'] = 'complementary';
-      break;
   }
 }
 
@@ -1338,15 +1332,6 @@ function system_block_view_system_main_block_alter(array &$build, BlockPluginInt
   unset($build['#contextual_links']);
 }
 
-/**
- * Implements hook_block_view_BASE_BLOCK_ID_alter().
- */
-function system_block_view_system_help_block_alter(array &$build, BlockPluginInterface $block) {
-  // Assume that most users do not need or want to perform contextual actions on
-  // the help block, so don't needlessly draw attention to it.
-  unset($build['#contextual_links']);
-}
-
 /**
  * Implements hook_path_update().
  */

core/profiles/standard/config/install/block.block.bartik_help.yml

@@ -4,15 +4,15 @@ weight: 0
 status: true
 langcode: en
 region: help
-plugin: system_help_block
+plugin: help_block
 settings:
-  id: system_help_block
-  label: 'System Help'
-  provider: system
+  id: help_block
+  label: 'Help'
+  provider: help
   label_display: '0'
 dependencies:
   module:
-    - system
+    - help
   theme:
     - bartik
 visibility: {  }

core/profiles/standard/config/install/block.block.seven_help.yml

@@ -4,15 +4,15 @@ weight: 0
 status: true
 langcode: en
 region: help
-plugin: system_help_block
+plugin: help_block
 settings:
-  id: system_help_block
-  label: 'System Help'
-  provider: system
+  id: help_block
+  label: 'Help'
+  provider: help
   label_display: '0'
 dependencies:
   module:
-    - system
+    - help
   theme:
     - seven
 visibility: {  }

core/profiles/standard/src/Tests/StandardTest.php

@@ -48,7 +48,7 @@ function testStandard() {
     $this->drupalGet('');
     $this->assertText('Main navigation');
 
-    // Verify we have role = aria on system_powered_by and system_help_block
+    // Verify we have role = aria on system_powered_by and help_block
     // blocks.
     $this->drupalGet('admin/structure/block');
     $elements = $this->xpath('//div[@role=:role and @id=:id]', array(