help_topics.module in Drupal 9
Same filename and directory in other branches
Displays help topics provided by modules and themes.
File
core/modules/help_topics/help_topics.moduleView source
<?php
/**
* @file
* Displays help topics provided by modules and themes.
*/
use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\Core\Url;
/**
* Implements hook_help().
*/
function help_topics_help($route_name, RouteMatchInterface $route_match) {
switch ($route_name) {
case 'help.page.help_topics':
$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 = '';
$output .= '<h3>' . t('About') . '</h3>';
$output .= '<p>' . t('The Help Topics module adds module- and theme-provided help topics to the module overviews from the core Help module. If the core Search module is enabled, these topics are also searchable. For more information, see the <a href=":online">online documentation for the Help Topics module</a>.', [
':online' => 'https://www.drupal.org/documentation/modules/help_topics',
]) . '</p>';
$output .= '<h3>' . t('Uses') . '</h3>';
$output .= '<dl>';
$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 Seven 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>';
}
}
/**
* Implements hook_theme().
*/
function help_topics_theme() {
return [
'help_topic' => [
'variables' => [
'body' => [],
'related' => [],
],
],
];
}
/**
* Implements hook_modules_uninstalled().
*/
function help_topics_modules_uninstalled(array $modules) {
_help_topics_search_update($modules);
}
/**
* Implements hook_themes_uninstalled().
*/
function help_topics_themes_uninstalled(array $themes) {
_help_topics_search_update();
}
/**
* Implements hook_modules_installed().
*/
function help_topics_modules_installed(array $modules, $is_syncing) {
_help_topics_search_update();
}
/**
* Implements hook_themes_installed().
*/
function help_topics_themes_installed(array $themes) {
_help_topics_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_topics_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_topics', $extensions)) {
return;
}
$search_plugin_manager = \Drupal::service('plugin.manager.search');
if ($search_plugin_manager
->hasDefinition('help_search')) {
// Ensure that topics for extensions that have been uninstalled are removed
// and that the index state variable is updated.
$help_search = $search_plugin_manager
->createInstance('help_search');
$help_search
->updateTopicList();
$help_search
->updateIndexState();
}
}
Functions
Name | Description |
---|---|
help_topics_help | Implements hook_help(). |
help_topics_modules_installed | Implements hook_modules_installed(). |
help_topics_modules_uninstalled | Implements hook_modules_uninstalled(). |
help_topics_theme | Implements hook_theme(). |
help_topics_themes_installed | Implements hook_themes_installed(). |
help_topics_themes_uninstalled | Implements hook_themes_uninstalled(). |
_help_topics_search_update | Ensure that search is updated when extensions are installed or uninstalled. |