Commit b5110387 authored by alexpott's avatar alexpott

Issue #2661200 by jhodgdon, Wim Leers, Cottser, Mile23, vijaycs85, larowlan,...

Issue #2661200 by jhodgdon, Wim Leers, Cottser, Mile23, vijaycs85, larowlan, andypost, tim.plunkett, dawehner: Make admin/help page more flexible, and list tours on it
parent b69517a8
......@@ -21,9 +21,9 @@
* 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. If a module implements hook_help() the help system expects
* module overview help to be provided.
* module. It can be accessed from the page at /admin/help or from the Extend
* page. If a module implements hook_help() the help system expects module
* overview help to be provided.
*
* For detailed usage examples of:
* - Module overview help, see content_translation_help(). Module overview
......@@ -56,6 +56,25 @@ function hook_help($route_name, \Drupal\Core\Routing\RouteMatchInterface $route_
}
}
/**
* Perform alterations on help page section plugin definitions.
*
* Sections for the page at /admin/help are provided by plugins. This hook
* allows modules to alter the plugin definitions.
*
* @param array $info
* Array of plugin information exposed by hook page section plugins, altered
* by reference.
*
* @see \Drupal\help\HelpSectionPluginInterface
* @see \Drupal\help\Annotation\HelpSection
* @see \Drupal\help\HelpSectionManager
*/
function hook_help_section_info_alter(&$info) {
// Alter the header for the module overviews section.
$info['hook_help']['header'] = t('Overviews of modules');
}
/**
* @} End of "addtogroup hooks".
*/
......@@ -5,8 +5,8 @@
* Manages displaying online help.
*/
use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\Core\Block\BlockPluginInterface;
use Drupal\Core\Routing\RouteMatchInterface;
/**
* Implements hook_help().
......@@ -25,7 +25,7 @@ function help_help($route_name, RouteMatchInterface $route_match) {
$output .= '<li>' . t('<strong>Start posting content</strong> Finally, you may <a href=":content">add new content</a> to your website.', array(':content' => \Drupal::url('node.add_page'))) . '</li>';
}
$output .= '</ol>';
$output .= '<p>' . t('For more information, refer to the subjects listed in the Help Topics section or to the <a href=":docs">online documentation</a> and <a href=":support">support</a> pages at <a href=":drupal">drupal.org</a>.', array(':docs' => 'https://www.drupal.org/documentation', ':support' => 'https://www.drupal.org/support', ':drupal' => 'https://www.drupal.org')) . '</p>';
$output .= '<p>' . t('For more information, refer to the help listed on this page or to the <a href=":docs">online documentation</a> and <a href=":support">support</a> pages at <a href=":drupal">drupal.org</a>.', array(':docs' => 'https://www.drupal.org/documentation', ':support' => 'https://www.drupal.org/support', ':drupal' => 'https://www.drupal.org')) . '</p>';
return ['#markup' => $output];
case 'help.page.help':
......@@ -43,6 +43,22 @@ function help_help($route_name, RouteMatchInterface $route_match) {
}
}
/**
* Implements hook_theme().
*/
function help_theme($existing, $type, $theme, $path) {
return [
'help_section' => [
'variables' => [
'title' => NULL,
'description' => NULL,
'links' => NULL,
'empty' => NULL,
],
],
];
}
/**
* Implements hook_preprocess_HOOK() for block templates.
*/
......
services:
plugin.manager.help_section:
class: Drupal\help\HelpSectionManager
parent: default_plugin_manager
<?php
/**
* @file
* Contains \Drupal\help\Annotation\HelpSection.
*/
namespace Drupal\help\Annotation;
use Drupal\Component\Annotation\Plugin;
/**
* Defines a Plugin annotation object for help page section plugins.
*
* Plugin Namespace: Plugin\HelpSection
*
* For a working example, see \Drupal\help\Plugin\HelpSection\HookHelpSection.
*
* @see \Drupal\help\HelpSectionPluginInterface
* @see \Drupal\help\Plugin\HelpSection\HelpSectionPluginBase
* @see \Drupal\help\HelpSectionManager
* @see hook_help_section_info_alter()
* @see plugin_api
*
* @Annotation
*/
class HelpSection extends Plugin {
/**
* The plugin ID.
*
* @var string
*/
public $id;
/**
* The text to use as the title of the help page section.
*
* @var \Drupal\Core\Annotation\Translation
*
* @ingroup plugin_translatable
*/
public $title;
/**
* The description of the help page section.
*
* @var \Drupal\Core\Annotation\Translation
*
* @ingroup plugin_translatable
*/
public $description;
/**
* The (optional) permission needed to view the help section.
*
* Only set if this section needs its own permission, beyond the generic
* 'access administration pages' permission needed to see the /admin/help
* page itself.
*
* @var string
*/
public $permission = '';
}
......@@ -7,9 +7,10 @@
namespace Drupal\help\Controller;
use Drupal\Core\Cache\CacheableMetadata;
use Drupal\Core\Controller\ControllerBase;
use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\Core\Url;
use Drupal\help\HelpSectionManager;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
......@@ -25,14 +26,24 @@ class HelpController extends ControllerBase {
*/
protected $routeMatch;
/**
* The help section plugin manager.
*
* @var \Drupal\help\HelpSectionManager
*/
protected $helpManager;
/**
* Creates a new HelpController.
*
* @param \Drupal\Core\Routing\RouteMatchInterface $route_match
* The current route match.
* @param \Drupal\help\HelpSectionManager $help_manager
* The help section manager.
*/
public function __construct(RouteMatchInterface $route_match) {
public function __construct(RouteMatchInterface $route_match, HelpSectionManager $help_manager) {
$this->routeMatch = $route_match;
$this->helpManager = $help_manager;
}
/**
......@@ -40,62 +51,57 @@ public function __construct(RouteMatchInterface $route_match) {
*/
public static function create(ContainerInterface $container) {
return new static(
$container->get('current_route_match')
$container->get('current_route_match'),
$container->get('plugin.manager.help_section')
);
}
/**
* Prints a page listing a glossary of Drupal terminology.
* Prints a page listing various types of help.
*
* The page has sections defined by \Drupal\help\HelpSectionPluginInterface
* plugins.
*
* @return string
* An HTML string representing the contents of help page.
* @return array
* A render array for the help page.
*/
public function helpMain() {
$output = array(
'#markup' => '<h2>' . $this->t('Help topics') . '</h2><p>' . $this->t('Help is available on the following items:') . '</p>',
'links' => $this->helpLinksAsList(),
);
return $output;
}
$output = [];
/**
* Provides a formatted list of available help topics.
*
* @return string
* A string containing the formatted list.
*/
protected function helpLinksAsList() {
$modules = array();
foreach ($this->moduleHandler()->getImplementations('help') as $module) {
$modules[$module] = $this->moduleHandler->getName($module);
}
asort($modules);
// Output pretty four-column list.
$count = count($modules);
$break = ceil($count / 4);
$column = array(
'#type' => 'container',
'links' => array('#theme' => 'item_list'),
'#attributes' => array('class' => array('layout-column', 'layout-column--quarter')),
);
$output = array(
'#prefix' => '<div class="clearfix">',
'#suffix' => '</div>',
0 => $column,
);
// We are checking permissions, so add the user.permissions cache context.
$cacheability = new CacheableMetadata();
$cacheability->addCacheContexts(['user.permissions']);
$i = 0;
$current_column = 0;
foreach ($modules as $module => $name) {
$output[$current_column]['links']['#items'][] = $this->l($name, new Url('help.page', array('name' => $module)));
if (($i + 1) % $break == 0 && ($i + 1) != $count) {
$current_column++;
$output[$current_column] = $column;
$plugins = $this->helpManager->getDefinitions();
$cacheability->addCacheableDependency($this->helpManager);
foreach ($plugins as $plugin_id => $plugin_definition) {
// Check the provided permission.
if (!empty($plugin_definition['permission']) && !$this->currentuser()->hasPermission($plugin_definition['permission'])) {
continue;
}
// Add the section to the page.
/** @var \Drupal\help\HelpSectionPluginInterface $plugin */
$plugin = $this->helpManager->createInstance($plugin_id);
$this_output = [
'#theme' => 'help_section',
'#title' => $plugin->getTitle(),
'#description' => $plugin->getDescription(),
'#empty' => $this->t('There is currently nothing in this section.'),
'#links' => [],
];
$links = $plugin->listTopics();
if (is_array($links) && count($links)) {
$this_output['#links'] = $links;
}
$i++;
$cacheability->addCacheableDependency($plugin);
$output[$plugin_id] = $this_output;
}
$cacheability->applyTo($output);
return $output;
}
......
<?php
/**
* @file
* Contains \Drupal\help\HelpSectionManager.
*/
namespace Drupal\help;
use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Plugin\DefaultPluginManager;
/**
* Manages help page section plugins.
*
* @see \Drupal\help\HelpSectionPluginInterface
* @see \Drupal\help\Plugin\HelpSection\HelpSectionPluginBase
* @see \Drupal\help\Annotation\HelpSection
* @see hook_help_section_info_alter()
*/
class HelpSectionManager extends DefaultPluginManager {
/**
* Constructs a new HelpSectionManager.
*
* @param \Traversable $namespaces
* An object that implements \Traversable which contains the root paths
* keyed by the corresponding namespace to look for plugin implementations.
* @param \Drupal\Core\Cache\CacheBackendInterface $cache_backend
* Cache backend instance to use.
* @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
* The module handler for the alter hook.
*/
public function __construct(\Traversable $namespaces, CacheBackendInterface $cache_backend, ModuleHandlerInterface $module_handler) {
parent::__construct('Plugin/HelpSection', $namespaces, $module_handler, 'Drupal\help\HelpSectionPluginInterface', 'Drupal\help\Annotation\HelpSection');
$this->alterInfo('help_section_info');
$this->setCacheBackend($cache_backend, 'help_section_plugins');
}
}
<?php
/**
* @file
* Contains \Drupal\help\HelpSectionPluginInterface.
*/
namespace Drupal\help;
use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\Core\Cache\CacheableDependencyInterface;
/**
* Provides an interface for a plugin for a section of the /admin/help page.
*
* Plugins of this type need to be annotated with
* \Drupal\help\Annotation\HelpSection annotation, and placed in the
* Plugin\HelpSection namespace directory. They are managed by the
* \Drupal\help\HelpSectionManager plugin manager class. There is a base
* class that may be helpful:
* \Drupal\help\Plugin\HelpSection\HelpSectionPluginBase.
*/
interface HelpSectionPluginInterface extends PluginInspectionInterface, CacheableDependencyInterface {
/**
* Returns the title of the help section.
*
* @return string
* The title text, which could be a plain string or an object that can be
* cast to a string.
*/
public function getTitle();
/**
* Returns the description text for the help section.
*
* @return string
* The description text, which could be a plain string or an object that
* can be cast to a string.
*/
public function getDescription();
/**
* Returns a list of topics to show in the help section.
*
* @return array
* A sorted list of topic links or render arrays for topic links. The links
* will be shown in the help section; if the returned array of links is
* empty, the section will be shown with some generic empty text.
*/
public function listTopics();
}
<?php
/**
* @file
* Contains \Drupal\help\Plugin\HelpSection\HelpSectionPluginBase.
*/
namespace Drupal\help\Plugin\HelpSection;
use Drupal\Core\Cache\UnchangingCacheableDependencyTrait;
use Drupal\Core\Plugin\PluginBase;
use Drupal\help\HelpSectionPluginInterface;
/**
* Provides a base class for help section plugins.
*
* @see \Drupal\help\HelpSectionPluginInterface
* @see \Drupal\help\Annotation\HelpSection
* @see \Drupal\help\HelpSectionManager
*/
abstract class HelpSectionPluginBase extends PluginBase implements HelpSectionPluginInterface {
use UnchangingCacheableDependencyTrait;
/**
* {@inheritdoc}
*/
public function getTitle() {
return $this->getPluginDefinition()['title'];
}
/**
* {@inheritdoc}
*/
public function getDescription() {
return $this->getPluginDefinition()['description'];
}
}
<?php
/**
* @file
* Contains \Drupal\help\Plugin\HelpSection\HookHelpSection.
*/
namespace Drupal\help\Plugin\HelpSection;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Link;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;
/**
* Provides the module topics list section for the help page.
*
* @HelpSection(
* id = "hook_help",
* title = @Translation("Module overviews"),
* description = @Translation("Module overviews are provided by modules. Overviews available for your installed modules:"),
* )
*/
class HookHelpSection extends HelpSectionPluginBase implements ContainerFactoryPluginInterface {
/**
* The module handler.
*
* @var \Drupal\Core\Extension\ModuleHandlerInterface
*/
protected $moduleHandler;
/**
* Constructs a HookHelpSection object.
*
* @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\Core\Extension\ModuleHandlerInterface $module_handler
* The module handler service.
*/
public function __construct(array $configuration, $plugin_id, $plugin_definition, ModuleHandlerInterface $module_handler) {
parent::__construct($configuration, $plugin_id, $plugin_definition);
$this->moduleHandler = $module_handler;
}
/**
* {@inheritdoc}
*/
public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
return new static(
$configuration,
$plugin_id,
$plugin_definition,
$container->get('module_handler')
);
}
/**
* {@inheritdoc}
*/
public function listTopics() {
$topics = [];
foreach ($this->moduleHandler->getImplementations('help') as $module) {
$title = $this->moduleHandler->getName($module);
$topics[$title] = Link::createFromRoute($title, 'help.page', ['name' => $module]);
}
// Sort topics by title, which is the array key above.
ksort($topics);
return $topics;
}
}
......@@ -20,11 +20,12 @@ class HelpTest extends WebTestBase {
* Modules to enable.
*
* The help_test module implements hook_help() but does not provide a module
* overview page.
* overview page. The help_page_test module has a page section plugin that
* returns no links.
*
* @var array.
*/
public static $modules = array('help_test');
public static $modules = array('help_test', 'help_page_test');
/**
* Use the Standard profile to test help implementations of many core modules.
......@@ -52,7 +53,7 @@ protected function setUp() {
}
/**
* Logs in users, creates dblog events, and tests dblog functionality.
* Logs in users, tests help pages.
*/
public function testHelp() {
// Login the root user to ensure as many admin links appear as possible on
......@@ -67,10 +68,16 @@ public function testHelp() {
// Verify that introductory help text exists, goes for 100% module coverage.
$this->drupalLogin($this->adminUser);
$this->drupalGet('admin/help');
$this->assertRaw(t('For more information, refer to the subjects listed in the Help Topics section or to the <a href=":docs">online documentation</a> and <a href=":support">support</a> pages at <a href=":drupal">drupal.org</a>.', array(':docs' => 'https://www.drupal.org/documentation', ':support' => 'https://www.drupal.org/support', ':drupal' => 'https://www.drupal.org')), 'Help intro text correctly appears.');
$this->assertRaw(t('For more information, refer to the help listed on this page or to the <a href=":docs">online documentation</a> and <a href=":support">support</a> pages at <a href=":drupal">drupal.org</a>.', array(':docs' => 'https://www.drupal.org/documentation', ':support' => 'https://www.drupal.org/support', ':drupal' => 'https://www.drupal.org')));
// Verify that help topics text appears.
$this->assertRaw('<h2>' . t('Help topics') . '</h2><p>' . t('Help is available on the following items:') . '</p>', 'Help topics text correctly appears.');
// Verify that hook_help() section title and description appear.
$this->assertRaw('<h2>' . t('Module overviews') . '</h2>');
$this->assertRaw('<p>' . t('Module overviews are provided by modules. Overviews available for your installed modules:'), '</p>');
// Verify that an empty section is handled correctly.
$this->assertRaw('<h2>' . t('Empty section') . '</h2>');
$this->assertRaw('<p>' . t('This description should appear.'), '</p>');
$this->assertText(t('There is currently nothing in this section.'));
// Make sure links are properly added for modules implementing hook_help().
foreach ($this->getModuleList() as $module => $name) {
......@@ -81,10 +88,25 @@ public function testHelp() {
// handled correctly.
$this->clickLink(\Drupal::moduleHandler()->getName('help_test'));
$this->assertRaw(t('No help is available for module %module.', array('%module' => \Drupal::moduleHandler()->getName('help_test'))));
// Verify that the order of topics is alphabetical by displayed module
// name, by checking the order of some modules, including some that would
// have a different order if it was done by machine name instead.
$this->drupalGet('admin/help');
$page_text = $this->getTextContent();
$start = strpos($page_text, 'Module overviews');
$pos = $start;
$list = ['Block', 'Color', 'Custom Block', 'History', 'Text Editor'];
foreach ($list as $name) {
$this->assertLink($name);
$new_pos = strpos($page_text, $name, $start);
$this->assertTrue($new_pos > $pos, 'Order of ' . $name . ' is correct on page');
$pos = $new_pos;
}
}
/**
* Verifies the logged in user has access to the various help nodes.
* Verifies the logged in user has access to the various help pages.
*
* @param int $response
* (optional) An HTTP response code. Defaults to 200.
......@@ -100,7 +122,7 @@ protected function verifyHelp($response = 200) {
}
foreach ($this->getModuleList() as $module => $name) {
// View module help node.
// View module help page.
$this->drupalGet('admin/help/' . $module);
$this->assertResponse($response);
if ($response == 200) {
......
......@@ -43,7 +43,7 @@ public function testMainPageNoHelp() {
$this->drupalGet('admin/help');
$this->assertResponse(200);
$this->assertText('Help is available on the following items', 'Help page is found.');
$this->assertText('Module overviews are provided by modules');
$this->assertFalse(\Drupal::moduleHandler()->implementsHook('menu_test', 'help'), 'The menu_test module does not implement hook_help');
$this->assertNoText(\Drupal::moduleHandler()->getName('menu_test'), 'Making sure the test module menu_test does not display a help link on admin/help.');
......
{#
/**
* @file
* Default theme implementation for a section of the help page.
*
* Available variables:
* - title: The section title.
* - description: The description text for the section.
* - links: Links to display in the section.
* - empty: Text to display if there are no links.
*
* @ingroup themeable
*/
#}
<h2>{{ title }}</h2>
<p>{{ description }}</p>
{% if links %}
<ul>
{% for link in links %}
<li>{{ link }}</li>
{% endfor %}
</ul>
{% else %}
<p>{{ empty }}</p>
{% endif %}
<?php
/**
* @file
* Contains \Drupal\help_page_test\Plugin\HelpSection\EmptyHelpSection.
*/
namespace Drupal\help_page_test\Plugin\HelpSection;
use Drupal\help\Plugin\HelpSection\HelpSectionPluginBase;
/**
* Provides an empty section for the help page, for testing.
*
* @HelpSection(
* id = "empty_section",
* title = @Translation("Empty section"),
* description = @Translation("This description should appear."),
* )
*/
class EmptyHelpSection extends HelpSectionPluginBase {
/**
* {@inheritdoc}
*/
public function listTopics() {
return [];
}
}
<?php
/**
* @file
* Contains \Drupal\tour\Plugin\HelpSection\TourHelpSection.
*/
namespace Drupal\tour\Plugin\HelpSection;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Link;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\Core\Url;
use Drupal\help\Plugin\HelpSection\HelpSectionPluginBase;
use Symfony\Component\DependencyInjection\ContainerInterface;
/**
* Provides the tours list section for the help page.
*
* @HelpSection(
* id = "tour",
* title = @Translation("Tours"),
* description = @Translation("Tours guide you through workflows or explain concepts on various user interface pages. The tours with links in this list are on user interface landing pages; the tours without links will show on individual pages (such as when editing a View using the Views UI module). Available tours:"),
* permission = "access tour"
* )
*/
class TourHelpSection extends HelpSectionPluginBase implements ContainerFactoryPluginInterface {
/**
* The entity type manager.
*
* @var \Drupal\Core\Entity\EntityTypeManagerInterface
*/
protected $entityTypeManager;
/**
* Constructs a TourHelpSection object.
*
* @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\Core\Entity\EntityTypeManagerInterface $entity_type_manager
* The entity manager service.
*/
public function __construct(array $configuration, $plugin_id, $plugin_definition, EntityTypeManagerInterface $entity_type_manager) {
parent::__construct($configuration, $plugin_id, $plugin_definition);
$this->entityTypeManager = $entity_type_manager;
}
/**
* {@inheritdoc}
*/
public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
return new static(
$configuration,
$plugin_id,
$plugin_definition,
$container->get('entity_type.manager')
);
}
/**
* {@inheritdoc}
*/
public function getCacheMaxAge() {
// The calculation of which URL (if any) gets put on which tour depends
// on a route access check. This can have a lot of inputs, including user