Commit c102edad authored by Gábor Hojtsy's avatar Gábor Hojtsy

Issue #3087027 by webchick, jhodgdon, larowlan, Amber Himes Matz, andypost,...

Issue #3087027 by webchick, jhodgdon, larowlan, Amber Himes Matz, andypost, catch, xjm: Mark the help topics module as beta stability

This reverts parts of commit 2a545911.
parent 696296bd
......@@ -653,7 +653,7 @@
"dist": {
"type": "path",
"url": "core",
"reference": "c52542b8ded961942356aae5de373c09f484e4b2"
"reference": "0d37d40cb2086fd922c8e2a942793e80d1707f1f"
},
"require": {
"asm89/stack-cors": "^1.1",
......@@ -766,6 +766,7 @@
"drupal/forum": "self.version",
"drupal/hal": "self.version",
"drupal/help": "self.version",
"drupal/help_topics": "self.version",
"drupal/history": "self.version",
"drupal/image": "self.version",
"drupal/inline_form_errors": "self.version",
......
......@@ -114,6 +114,7 @@
"drupal/forum": "self.version",
"drupal/hal": "self.version",
"drupal/help": "self.version",
"drupal/help_topics": "self.version",
"drupal/history": "self.version",
"drupal/image": "self.version",
"drupal/inline_form_errors": "self.version",
......
langcode: en
status: true
dependencies:
enforced:
config:
- search.page.help_search
module:
- search
- system
theme:
- seven
id: seven_help_search
theme: seven
region: help
weight: -4
provider: null
plugin: search_form_block
settings:
id: search_form_block
label: 'Search help'
provider: search
label_display: visible
page_id: help_search
visibility:
request_path:
id: request_path
pages: /admin/help
negate: false
context_mapping: { }
langcode: en
status: true
dependencies:
module:
- help_topics
id: help_search
label: Help
path: help
weight: 0
plugin: help_search
configuration: { }
search.plugin.help_search:
type: sequence
label: 'Help search'
<?php
/**
* @file
* Hooks provided by the Help Topics module.
*/
/**
* @addtogroup hooks
* @{
*/
/**
* Perform alterations on help topic definitions.
*
* @param array $info
* Array of help topic plugin definitions keyed by their plugin ID.
*
* @internal
* Help Topics is currently experimental and should only be leveraged by
* experimental modules and development releases of contributed modules.
* See https://www.drupal.org/core/experimental for more information.
*/
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".
*/
name: Help Topics
type: module
description: 'Displays help topics provided by themes and modules.'
core: 8.x
package: Core (Experimental)
version: VERSION
dependencies:
- drupal:help
<?php
/**
* @file
* Install and uninstall functions for help_topics module.
*/
/**
* Implements hook_schema().
*/
function help_topics_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;
}
<?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/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) {
// Early return if search is not installed or if we're uninstalling this
// module.
if (!\Drupal::hasService('plugin.manager.search') ||
in_array('help_topics', $modules)) {
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.
$help_search = $search_plugin_manager->createInstance('help_search');
$help_search->updateTopicList();
}
}
/**
* Implements hook_themes_uninstalled().
*/
function help_topics_themes_uninstalled(array $themes) {
// Use the same code as module uninstall to ensure that theme help is removed
// when a theme is uninstalled.
help_topics_modules_uninstalled([]);
}
help.help_topic:
path: '/admin/help/topic/{id}'
defaults:
_controller: '\Drupal\help_topics\Controller\HelpTopicPluginController::viewHelpTopic'
requirements:
_permission: 'access administration pages'
services:
help.breadcrumb:
class: Drupal\help_topics\HelpBreadcrumbBuilder
arguments: ['@string_translation']
tags:
- { name: breadcrumb_builder, priority: 900 }
public: false
plugin.manager.help_topic:
class: Drupal\help_topics\HelpTopicPluginManager
arguments: ['@module_handler', '@theme_handler', '@cache.discovery', '@app.root']
help.twig.loader:
class: Drupal\help_topics\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
plugin.manager.help_section_topics:
class: Drupal\help_topics\HelpSectionManager
decorates: plugin.manager.help_section
parent: plugin.manager.help_section
calls:
- [setSearchManager, ['@?plugin.manager.search']]
tags:
- { name: plugin_manager_cache_clear }
---
label: 'Changing basic site settings'
top_level: true
related:
- user.security_account_settings
---
{% set regional_url = render_var(url('system.regional_settings')) %}
{% set information_url = render_var(url('system.site_information_settings')) %}
{% set datetime_url = render_var(url('entity.date_format.collection')) %}
<p>{% trans %}The settings for your site are configured on various administrative pages, as follows:{% endtrans %}</p>
<dl>
<dt>{% trans %}Site name, slogan, and email address{% endtrans %}</dt>
<dd>{% trans %}On the <a href="{{ information_url }}"><em>Basic site settings</em></a> page, which you can reach in the main <em>Manage</em> administrative menu, by navigating to <em>Configuration</em> &gt; <em>System</em> &gt; <em>Basic site settings</em>.{% endtrans %}</dd>
<dt>{% trans %}Time zone and country{% endtrans %}</dt>
<dd>{% trans %}On the <a href="{{ regional_url }}"><em>Regional settings</em></a> page, which you can reach in the main <em>Manage</em> administrative menu, by navigating to <em>Configuration</em> &gt; <em>Regional and language</em> &gt; <em>Regional settings</em>.{% endtrans %}</dd>
<dt>{% trans %}Date and time formats{% endtrans %}</dt>
<dd>{% trans %}On the <a href="{{ datetime_url }}"><em>Date and time formats</em></a> page, which you can reach in the main <em>Manage</em> administrative menu, by navigating to <em>Configuration</em> &gt; <em>Regional and language</em> &gt; <em>Date and time formats</em>.{% endtrans %}</dd>
</dl>
---
label: 'Configuring error responses, including 403/404 pages'
related:
- core.config_basic
- core.maintenance
---
{% set log_settings_url = render_var(url('system.logging_settings')) %}
{% set site_settings_url = render_var(url('system.site_information_settings')) %}
<h2>{% trans %}Configuring 403/404 pages{% endtrans %}</h2>
<p>{% trans %}The core software provides default responses for 403 response (Not Authorized: when someone tries to visit a page they do not have permission to see) and 404 response (Not Found: when someone tries to visit a page that does not exist). You can change what page is displayed for these responses on the <a href="{{ site_settings_url }}"><em>Basic site settings</em></a> page, which you can reach in the main <em>Manage</em> administrative menu, by navigating to <em>Configuration</em> &gt; <em>System</em> &gt; <em>Basic site settings</em>. Note that the pages you want to use must already exist as either system-provided pages or content that you have created.{% endtrans %}</p>
<h2>{% trans %}Responding to software errors{% endtrans %}</h2>
<p>{% trans %}Software errors on your site are logged, if you have a logging module installed (such as the core Database Logging module or the core Syslog module). You can configure whether or not error messages are also shown (to both administrators and other site visitors) on the <a href="{{ log_settings_url }}"><em>Logging and errors</em></a> configuration page, which you can reach in the main <em>Manage</em> administrative menu, by navigating to <em>Configuration</em> &gt; <em>Development</em> &gt; <em>Logging and errors</em>.{% endtrans %}</p>
<h2>{% trans %}Viewing the site log{% endtrans %}</h2>
<p>{% trans %}If you have the core Database Logging module installed, you can view recent error and informational messages by navigating in the main <em>Manage</em> administrative menu to <em>Reports</em> &gt; <em>Recent log messages</em>. If you are using the core Syslog module for logging, error messages will be logged in your web server''s log files.{% endtrans %}</p>
---
label: 'Maintaining and troubleshooting your site'
top_level: true
---
<p>{% trans %}The related topics listed here will help you keep your site running and troubleshoot problems.{% endtrans %}</p>
---
label: 'Defining navigation and URLs'
top_level: true
---
<p>{% trans %}The related topics listed here describe how to set up various aspects of site navigation and URLs.{% endtrans %}</p>
---
label: 'Making your site secure'
top_level: true
related:
- core.menu_overview
---
<p>{% trans %}The topics listed here will help you make and keep your site secure.{% endtrans %}</p>
---
label: 'Accessibility features'
related:
- core.ui_components
---
<p>{% trans %}The following features of the administrative user interface may help administrative users with disabilities access your site:{% endtrans %}</p>
<dl>
<dt>{% trans %}Disabling drag-and-drop functionality{% endtrans %}</dt>
<dd>{% trans %}The default drag-and-drop user interface for ordering tables in the administrative interface 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 <em>Show row weights</em> above the table. The replacement interface allows users to order the table by choosing numerical weights instead of dragging table rows.{% endtrans %}</dd>
</dl>
---
label: 'Using the administrative interface'
top_level: true
---
<p>{% trans %}The related topics listed here describe various aspects of the administrative interface, and tell how to use them.{% endtrans %}</p>
---
label: 'Contextual links'
related:
- core.ui_components
---
<h2>{% trans %}What are contextual links?{% endtrans %}</h2>
<p>{% trans %}<em>Contextual links</em> give users with the <em>Use contextual links</em> permission quick access to administrative tasks related to areas of non-administrative pages. For example, if a page on your site displays a block, the block would have a contextual link that would allow users with permission to configure the block. If the block contains a menu or a view, it would also have a contextual link for editing the menu links or the view. Clicking a contextual link takes you to the related administrative page directly, without needing to navigate through the administrative menu system.{% endtrans %}</p>
<h2>{% trans %}Displaying and using contextual links{% endtrans %}</h2>
<p>{% trans %}If you have the core Contextual Links module installed, the contextual links related to an area on a page can be displayed by clicking the contextual links button in that area of the page. In most themes, this button looks like a pencil and is placed in the upper right corner of the page area (upper left for right-to-left languages); however, contextual links buttons are normally hidden. Here are two ways to make contextual links buttons visible:{% endtrans %}</p>
<ul>
<li>{% trans %}Hovering your mouse over an area on the page will temporarily make the contextual links button visible, if there is one for that area of the page. Also, in most themes, the page area that the contextual links pertain to will be outlined while you are hovering.{% endtrans %}</li>
<li>{% trans %}If you have the core Toolbar module enabled, there will be a contextual links toggle button at the far right end of the toolbar (far left end for right-to-left languages; this button looks like a pencil in most themes). Clicking the toggle button will make all the individual contextual links buttons on the page visible; clicking the toggle button again will make them invisible.{% endtrans %}</li>
</ul>
<p>{% trans %}While the contextual links button for the area of interest is visible, click the button to display the list of links for that area. Click a link in the list to perform the task.{% endtrans %}</p>
---
label: 'Tours'
related:
- core.ui_components
---
<h2>{% trans %}What are tours?{% endtrans %}</h2>
<p>{% trans %}The core Tour module provides users with <em>tours</em>, which are guided tours of the administrative interface. Each tour starts on a particular administrative page, and consists of one or more <em>tips</em> that highlight elements of the page, guide you through a workflow, or explain key concepts. Users need <em>Access tour</em> permission to view tours, and JavaScript must be enabled in their browsers.{% endtrans %}</p>
<h2>{% trans %}Viewing tours{% endtrans %}</h2>
<p>{% trans %}If a tour is available on a page, and you have the core Toolbar module installed, a <em>Tour</em> button will appear on the right end of the toolbar (left end for right-to-left languages). Click this button to view the first tip of the tour; click the <em>Next</em> button to advance to the next tip, and <em>End tour</em> at the end to close the tour.{% endtrans %}</p>
---
label: 'Configuring help search'
top_level: true
---
<h2>{% trans %}Goal{% endtrans %}</h2>
<p>{% trans %}Set up your site so that users can search for help.{% endtrans %}</p>
<h2>{% trans %}Steps{% endtrans %}</h2>
<ol>
<li>{% trans %}From the <em>Extend</em> administrative page (<em>admin/modules</em>), verify that the Search, Help, Help Topics, and Block modules are installed (or install them if they are not already installed).{% endtrans %}</li>
<li>{% trans %}In the <em>Manage</em> administrative menu, navigate to <em>Configuration</em> &gt; <em>Search and metadata</em> &gt; <em>Search pages</em> (<em>admin/config/search/pages</em>).{% endtrans %}</li>
<li>{% trans %}Verify that a Help search page is listed in the <em>Search pages</em> section. If not, add a new page of type <em>Help</em>.{% endtrans %}</li>
<li>{% trans %}Check the indexing status of the Help search page. If it is not fully indexed, run Cron until indexing is complete.{% endtrans %}</li>
<li>{% trans %}In the future, you can click <em>Rebuild search index</em> on this page, or clear the site cache, in order to force help topic text to be reindexed for searching. This should be done whenever a module, theme, language, or string translation is updated.{% endtrans %}</li>
<li>{% trans %}In the <em>Manage</em> administrative menu, navigate to <em>Structure</em> &gt; <em>Block layout</em> (<em>admin/structure/block</em>).{% endtrans %}</li>
<li>{% trans %}Click the link for your administrative theme (such as the core Seven theme), near the top of the page.{% endtrans %}</li>
<li>{% trans %}See if there is already a help search block placed in the Help region of your administrative theme.{% endtrans %}</li>
<li>{% trans %}If there is not already a help search block placed, click <em>Place block</em>, and then click <em>Place block</em> in the row next to <em>Search form</em> in the dialog. Choose <em>Help</em> as the search page for the block, and in the <em>Visibility</em> &gt; <em>Pages</em> field, enter <em>/admin/help</em> to make the search form only visible on the main <em>Help</em> page.{% endtrans %}</li>
<li>{% trans %}Fill in the rest of the form and save the block.{% endtrans %}</li>
<li>{% trans %}Visit the main <em>Help</em> page (<em>admin/help</em>) to verify that the search block is visible, and try a search.{% endtrans %}</li>
</ol>
---
label: 'Writing good help'
top_level: true
---
<p>{% trans %}Here are some suggestions for how to make your help topics as useful as possible for readers:{% endtrans %}</p>
<ul>
<li>{% trans %}Choose short titles. If the topic describes a task, start with a verb in -ing form, like "Writing good help".{% endtrans %}</li>
<li>{% trans %}Make your topics modular and short, using links to connect information together.{% endtrans %}</li>
<li>{% trans %}Use headings and lists to organize your topics.{% endtrans %}</li>
<li>{% trans %}Write in second person (you, your). When describing a task, use imperative mood (tell people directly what to do, such as "Enter information in the ABC field", rather than using words like "please" or more passive or declarative language like "the ABC field needs to be filled in").{% endtrans %}</li>
</ul>
---
label: 'Shortcuts'
related:
- core.ui_components
---
<h2>{% trans %}What are shortcuts?{% endtrans %}</h2>
<p>{% trans %}<em>Shortcuts</em> are quick links to administrative pages; they are managed by the core Shortcut module. A site can have one or more <em>shortcut sets</em>, which can be shared by one or more users; each set contains one or more shortcuts. Users need <em>Use shortcuts</em> permission to view shortcuts; <em>Edit current shortcut set</em> permission to add, delete, or edit the shortcuts in the set assigned to them; and <em>Select any shortcut set</em> permission to select a different shortcut set when editing their user profile. There is also an <em>Administer shortcuts</em> permission, which allows an administrator to do any of these actions, and also permits assigning shortcut sets to other users.{% endtrans %}</p>
<h2>{% trans %}Creating and deleting shortcuts{% endtrans %}</h2>
<p>{% trans %}When viewing certain administrative pages, you will see a link that allows you to add the page to your current shortcut set. In the core Seven administrative theme, the link looks like a star, and is displayed next to the page title. If the page is already in your shortcut set, you will instead see a link that allows you to remove it.{% endtrans %}</p>
<h2>{% trans %}Viewing and using shortcuts{% endtrans %}</h2>
<p>{% trans %}If you have the core Toolbar module installed, click <em>Shortcuts</em> in the toolbar to display your shortcuts. Once they are displayed, click any link in the shortcut bar to go directly to the administrative page. If you are not using the Toolbar module, you can display shortcuts by placing the <em>Shortcuts</em> block in a region of your theme.{% endtrans %}</p>
---
label: 'Defining how user accounts are created'
related:
- core.security
---
{% set account_settings_url = render_var(url('entity.user.admin_form')) %}
<p>{% trans %}On the <a href="{{ account_settings_url }}"><em>Account settings</em></a> page, which you can reach from the <em>Manage</em> administrative menu, by navigating to <em>Configuration</em> &gt; <em>People</em> &gt; <em>Account settings</em> (requires the <em>Administer account settings</em> permission), you can configure several settings related to how user accounts are created:{% endtrans %}</p>
<ul>
<li>{% trans %}You can make it possible for new users to register themselves, with or without administrator approval. Or, you can make it so only administrators with <em>Administer users</em> permission can register new users.{% endtrans %}</li>
<li>{% trans %}You can require email verification of new user accounts.{% endtrans %}</li>
<li>{% trans %}You can enable or disable a password strength indicator, which is shown whenever passwords are being set up or changed.{% endtrans %}</li>
<li>{% trans %}You can edit the email messages that are sent to users in conjunction with the user registration process.{% endtrans %}</li>
</ul>
<?php
namespace Drupal\help_topics\Controller;
use Drupal\Component\Utility\SortArray;
use Drupal\Core\Controller\ControllerBase;
use Drupal\Core\Url;
use Drupal\help_topics\HelpTopicPluginManagerInterface;
use Drupal\Core\Render\RendererInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
/**
* Controller for help topic plugins.
*
* @internal
* Help Topic is currently experimental and should only be leveraged by
* experimental modules and development releases of contributed modules.
* See https://www.drupal.org/core/experimental for more information.
*/
class HelpTopicPluginController extends ControllerBase {
/**
* The renderer service.
*
* @var \Drupal\Core\Render\RendererInterface
*/
protected $renderer;
/**
* The Help Topic plugin manager.
*
* @var \Drupal\help_topics\HelpTopicPluginManagerInterface
*/
protected $helpTopicPluginManager;
/**
* Constructs a HelpTopicPluginController object.
*
* @param \Drupal\help_topics\HelpTopicPluginManagerInterface $help_topic_plugin_manager
* The help topic plugin manager service.
* @param \Drupal\Core\Render\RendererInterface $renderer
* The renderer service.
*/
public function __construct(HelpTopicPluginManagerInterface $help_topic_plugin_manager, RendererInterface $renderer) {
$this->helpTopicPluginManager = $help_topic_plugin_manager;
$this->renderer = $renderer;
}
/**
* {@inheritdoc}
*/
public static function create(ContainerInterface $container) {
return new static(
$container->get('plugin.manager.help_topic'),
$container->get('renderer')
);
}
/**
* Displays a help topic page.
*
* @param string $id
* The plugin ID. Maps to the {id} placeholder in the
* help.help_topic route.
*
* @return array
* A render array with the contents of a help topic page.
*/
public function viewHelpTopic($id) {
$build = [];
if (!$this->helpTopicPluginManager->hasDefinition($id)) {
throw new NotFoundHttpException();
}
/* @var \Drupal\help_topics\HelpTopicPluginInterface $help_topic */
$help_topic = $this->helpTopicPluginManager->createInstance($id);
$build['#body'] = $help_topic->getBody();
$this->renderer->addCacheableDependency($build, $help_topic);
// Build the related topics section, starting with the list this topic
// says are related.
$links = [];
$related = $help_topic->getRelated();
foreach ($related as $other_id) {
if ($other_id !== $id) {
/** @var \Drupal\help_topics\HelpTopicPluginInterface $topic */
$topic = $this->helpTopicPluginManager->createInstance($other_id);
$links[$other_id] = [
'title' => $topic->getLabel(),
'url' => Url::fromRoute('help.help_topic', ['id' => $other_id]),
];
$this->renderer->addCacheableDependency($build, $topic);
}
}
if (count($links)) {
uasort($links, [SortArray::class, 'sortByTitleElement']);
$build['#related'] = [
'#theme' => 'links__related',
'#heading' => [
'text' => $this->t('Related topics'),
'level' => 'h2',
],
'#links' => $links,
];
}
$build['#theme'] = 'help_topic';
$build['#title'] = $help_topic->getLabel();
return $build;
}
}
<?php
namespace Drupal\help_topics;
/**
* Extracts Front Matter from the beginning of a source.
*
* @internal
* This front matter extractor only supports help topic discovery and is not
* part of the public API.
*/
final class FrontMatter {
/**
* The separator used to indicate front matter data.
*
* @var string
*/
const FRONT_MATTER_SEPARATOR = '---';
/**
* The regular expression used to extract the YAML front matter content.
*
* @var string
*/
const FRONT_MATTER_REGEXP = "{^(?:" . self::FRONT_MATTER_SEPARATOR . ")[\r\n|\n]*(.*?)[\r\n|\n]+(?:" . self::FRONT_MATTER_SEPARATOR . ")[\r\n|\n]*(.*)$}s";
/**
* The parsed source.
*
* @var array
*/
protected $parsed;
/**
* A serializer class.
*
* @var string
*/
protected $serializer;
/**
* The source.
*
* @var string
*/
protected $source;
/**
* FrontMatter constructor.
*
* @param string $source
* A string source.
* @param string $serializer
* A class that implements
* \Drupal\Component\Serialization\SerializationInterface.
*/
public function __construct($source, $serializer = '\Drupal\Component\Serialization\Yaml') {
assert(is_string($source), '$source must be a string');
assert(is_string($serializer), '$serializer must be a string');
if (!is_subclass_of($serializer, '\Drupal\Component\Serialization\SerializationInterface')) {
throw new \InvalidArgumentException('The $serializer parameter must reference a class that implements \Drupal\Component\Serialization\SerializationInterface.');
}
$this->serializer = $serializer;
$this->source = $source;
}
/**
* Creates a new FrontMatter instance.
*
* @param string $source
* A string source.
* @param string $serializer
* A class that implements
* \Drupal\Component\Serialization\SerializationInterface.
*
* @return static
*/
public static function load($source, $serializer = '\Drupal\Component\Serialization\Yaml') {
return new static($source, $serializer);
}
/**
* Parses the source.
*
* @return array
* An associative array containing:
* - code: The real source code.
* - data: The front matter data extracted and decoded.
* - line: The line number where the real source code starts.
*
* @throws \Drupal\Component\Serialization\Exception\InvalidDataTypeException
* Exception thrown when the Front Matter cannot be parsed.
*/
private function parse() {
if (!$this->parsed) {
$this->parsed = [
'code' => $this->source,
'data' => [],
'line' => 1,
];
// Check for front matter data.
$len = strlen(static::FRONT_MATTER_SEPARATOR);
$matches = [];
if (substr($this->parsed['code'], 0, $len + 1) === static::FRONT_MATTER_SEPARATOR . "\n" || substr($this->parsed[