Commit 4cd9d457 authored by catch's avatar catch

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
parent ad555fa8
......@@ -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.');
......
......@@ -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));
......
......@@ -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.
......
......@@ -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'));
......
......@@ -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'));
}
/**
......
/**
* @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".
*/
......@@ -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']);
}
......@@ -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');
}
......
......@@ -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.');
......
......@@ -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);
......
......@@ -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().
*
......
......@@ -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().
*/
......
......@@ -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: { }
......@@ -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: { }
......@@ -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(
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment