From 5691efb09bde15442d3754b5c54fdac7a593ca3d Mon Sep 17 00:00:00 2001
From: Lee Rowlands <lee.rowlands@previousnext.com.au>
Date: Sat, 5 Oct 2019 08:43:07 +1000
Subject: [PATCH] Issue #3069109 by alexpott, markcarver, jhodgdon, lauriii:
Replace help_topic meta tags with front matter
---
core/modules/help_topics/help_topics.module | 2 +-
.../help_topics/core.config_basic.html.twig | 9 +-
.../help_topics/core.config_error.html.twig | 8 +-
.../help_topics/core.maintenance.html.twig | 6 +-
.../help_topics/core.menu_overview.html.twig | 6 +-
.../help_topics/core.security.html.twig | 9 +-
.../core.ui_accessibility.html.twig | 7 +-
.../help_topics/core.ui_components.html.twig | 6 +-
.../help_topics/core.ui_contextual.html.twig | 7 +-
.../help_topics/core.ui_tours.html.twig | 7 +-
.../help_topics.help_topic_writing.html.twig | 6 +-
.../shortcut.ui_shortcuts.html.twig | 7 +-
.../user.security_account_settings.html.twig | 7 +-
core/modules/help_topics/src/FrontMatter.php | 173 ++++++++++++++++++
.../help_topics/src/HelpTopicDiscovery.php | 30 ++-
.../src/HelpTopicPluginManager.php | 20 +-
.../modules/help_topics/src/HelpTopicTwig.php | 2 -
.../help_topics/src/HelpTopicTwigLoader.php | 33 ++++
.../help_topics_test.additional.html.twig | 7 +-
.../help_topics_test.linked.html.twig | 4 +-
.../help_topics_test.test.html.twig | 10 +-
.../tests/src/Functional/HelpTopicTest.php | 5 -
.../tests/src/Unit/HelpTopicDiscoveryTest.php | 96 ++++++++--
.../src/Unit/HelpTopicTwigLoaderTest.php | 34 +++-
.../tests/src/Unit/HelpTopicTwigTest.php | 2 +-
.../help_topics_test_theme.test.html.twig | 9 +-
26 files changed, 430 insertions(+), 82 deletions(-)
create mode 100644 core/modules/help_topics/src/FrontMatter.php
diff --git a/core/modules/help_topics/help_topics.module b/core/modules/help_topics/help_topics.module
index 5b89b36de1fe..4e63e952c359 100644
--- a/core/modules/help_topics/help_topics.module
+++ b/core/modules/help_topics/help_topics.module
@@ -24,7 +24,7 @@ function help_topics_help($route_name, RouteMatchInterface $route_match) {
$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 meta tags 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 .= '<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 .= '</dl>';
diff --git a/core/modules/help_topics/help_topics/core.config_basic.html.twig b/core/modules/help_topics/help_topics/core.config_basic.html.twig
index 09fcb5b9d0a2..ca4239930390 100644
--- a/core/modules/help_topics/help_topics/core.config_basic.html.twig
+++ b/core/modules/help_topics/help_topics/core.config_basic.html.twig
@@ -1,6 +1,9 @@
-<meta name="help_topic:label" content="Changing basic site settings"/>
-<meta name="help_topic:top_level"/>
-<meta name="help_topic:related" content="user.security_account_settings"/>
+---
+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')) %}
diff --git a/core/modules/help_topics/help_topics/core.config_error.html.twig b/core/modules/help_topics/help_topics/core.config_error.html.twig
index f91fc2a64e4c..a8b840ba84f9 100644
--- a/core/modules/help_topics/help_topics/core.config_error.html.twig
+++ b/core/modules/help_topics/help_topics/core.config_error.html.twig
@@ -1,5 +1,9 @@
-<meta name="help_topic:label" content="Configuring error responses, including 403/404 pages"/>
-<meta name="help_topic:related" content="core.config_basic,core.maintenance"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/core.maintenance.html.twig b/core/modules/help_topics/help_topics/core.maintenance.html.twig
index 8d86f14fdde3..f713192e4e23 100644
--- a/core/modules/help_topics/help_topics/core.maintenance.html.twig
+++ b/core/modules/help_topics/help_topics/core.maintenance.html.twig
@@ -1,3 +1,5 @@
-<meta name="help_topic:label" content="Maintaining and troubleshooting your site"/>
-<meta name="help_topic:top_level"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/core.menu_overview.html.twig b/core/modules/help_topics/help_topics/core.menu_overview.html.twig
index 4e27967f94e9..bb4a2218e2a6 100644
--- a/core/modules/help_topics/help_topics/core.menu_overview.html.twig
+++ b/core/modules/help_topics/help_topics/core.menu_overview.html.twig
@@ -1,3 +1,5 @@
-<meta name="help_topic:label" content="Defining navigation and URLs"/>
-<meta name="help_topic:top_level"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/core.security.html.twig b/core/modules/help_topics/help_topics/core.security.html.twig
index 63b12c49373b..97c0ea1079ca 100644
--- a/core/modules/help_topics/help_topics/core.security.html.twig
+++ b/core/modules/help_topics/help_topics/core.security.html.twig
@@ -1,4 +1,7 @@
-<meta name="help_topic:label" content="Making your site secure"/>
-<meta name="help_topic:top_level"/>
-<meta name="help_topic:related" content="menu_ui.menu_overview"/>
+---
+label: 'Making your site secure'
+top_level: true
+related:
+ - menu_ui.menu_overview
+---
<p>{% trans %}The topics listed here will help you make and keep your site secure.{% endtrans %}</p>
diff --git a/core/modules/help_topics/help_topics/core.ui_accessibility.html.twig b/core/modules/help_topics/help_topics/core.ui_accessibility.html.twig
index f93aa4d580ce..d1f30157ee01 100644
--- a/core/modules/help_topics/help_topics/core.ui_accessibility.html.twig
+++ b/core/modules/help_topics/help_topics/core.ui_accessibility.html.twig
@@ -1,5 +1,8 @@
-<meta name="help_topic:label" content="Accessibility features"/>
-<meta name="help_topic:related" content="core.ui_components"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/core.ui_components.html.twig b/core/modules/help_topics/help_topics/core.ui_components.html.twig
index f2b28f45ac9b..0a14a1b61b42 100644
--- a/core/modules/help_topics/help_topics/core.ui_components.html.twig
+++ b/core/modules/help_topics/help_topics/core.ui_components.html.twig
@@ -1,3 +1,5 @@
-<meta name="help_topic:label" content="Using the administrative interface"/>
-<meta name="help_topic:top_level"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/core.ui_contextual.html.twig b/core/modules/help_topics/help_topics/core.ui_contextual.html.twig
index 202a285404bb..d269556156b3 100644
--- a/core/modules/help_topics/help_topics/core.ui_contextual.html.twig
+++ b/core/modules/help_topics/help_topics/core.ui_contextual.html.twig
@@ -1,5 +1,8 @@
-<meta name="help_topic:label" content="Contextual links"/>
-<meta name="help_topic:related" content="core.ui_components"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/core.ui_tours.html.twig b/core/modules/help_topics/help_topics/core.ui_tours.html.twig
index 7edf84283b5a..4bbaec220981 100644
--- a/core/modules/help_topics/help_topics/core.ui_tours.html.twig
+++ b/core/modules/help_topics/help_topics/core.ui_tours.html.twig
@@ -1,5 +1,8 @@
-<meta name="help_topic:label" content="Tours"/>
-<meta name="help_topic:related" content="core.ui_components"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/help_topics.help_topic_writing.html.twig b/core/modules/help_topics/help_topics/help_topics.help_topic_writing.html.twig
index cf61fc46307d..b5d1bfd992cc 100644
--- a/core/modules/help_topics/help_topics/help_topics.help_topic_writing.html.twig
+++ b/core/modules/help_topics/help_topics/help_topics.help_topic_writing.html.twig
@@ -1,5 +1,7 @@
-<meta name="help_topic:label" content="Writing good help"/>
-<meta name="help_topic:top_level"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/shortcut.ui_shortcuts.html.twig b/core/modules/help_topics/help_topics/shortcut.ui_shortcuts.html.twig
index 0228a37acf56..832b89facd0f 100644
--- a/core/modules/help_topics/help_topics/shortcut.ui_shortcuts.html.twig
+++ b/core/modules/help_topics/help_topics/shortcut.ui_shortcuts.html.twig
@@ -1,5 +1,8 @@
-<meta name="help_topic:label" content="Shortcuts"/>
-<meta name="help_topic:related" content="core.ui_components"/>
+---
+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>
diff --git a/core/modules/help_topics/help_topics/user.security_account_settings.html.twig b/core/modules/help_topics/help_topics/user.security_account_settings.html.twig
index ef2d25a7577f..fbf5052936d4 100644
--- a/core/modules/help_topics/help_topics/user.security_account_settings.html.twig
+++ b/core/modules/help_topics/help_topics/user.security_account_settings.html.twig
@@ -1,5 +1,8 @@
-<meta name="help_topic:label" content="Defining how user accounts are created"/>
-<meta name="help_topic:related" content="core.security"/>
+---
+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> > <em>People</em> > <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>
diff --git a/core/modules/help_topics/src/FrontMatter.php b/core/modules/help_topics/src/FrontMatter.php
new file mode 100644
index 000000000000..4d95f268eb66
--- /dev/null
+++ b/core/modules/help_topics/src/FrontMatter.php
@@ -0,0 +1,173 @@
+<?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['code'], 0, $len + 2) === static::FRONT_MATTER_SEPARATOR . "\r\n") {
+ preg_match(static::FRONT_MATTER_REGEXP, $this->parsed['code'], $matches);
+ $matches = array_map('trim', $matches);
+ }
+
+ // Immediately return if the code doesn't contain front matter data.
+ if (empty($matches)) {
+ return $this->parsed;
+ }
+
+ // Set the extracted source code.
+ $this->parsed['code'] = $matches[2];
+
+ // Set the extracted front matter data. Do not catch any exceptions here
+ // as doing so would only obfuscate any errors found in the front matter
+ // data. Typecast to an array to ensure top level scalars are in an array.
+ if ($matches[1]) {
+ $this->parsed['data'] = (array) $this->serializer::decode($matches[1]);
+ }
+
+ // Determine the real source line by counting newlines from the data and
+ // then adding 2 to account for the front matter separator (---) wrappers
+ // and then adding 1 more for the actual line number after the data.
+ $this->parsed['line'] = count(preg_split('/\r\n|\n/', $matches[1])) + 3;
+ }
+ return $this->parsed;
+ }
+
+ /**
+ * Retrieves the extracted source code.
+ *
+ * @return string
+ * The extracted source code.
+ *
+ * @throws \Drupal\Component\Serialization\Exception\InvalidDataTypeException
+ * Exception thrown when the Front Matter cannot be parsed.
+ */
+ public function getCode() {
+ return $this->parse()['code'];
+ }
+
+ /**
+ * Retrieves the extracted front matter data.
+ *
+ * @return array
+ * The extracted front matter data.
+ *
+ * @throws \Drupal\Component\Serialization\Exception\InvalidDataTypeException
+ * Exception thrown when the Front Matter cannot be parsed.
+ */
+ public function getData() {
+ return $this->parse()['data'];
+ }
+
+ /**
+ * Retrieves the line where the source code starts, after any data.
+ *
+ * @return int
+ * The source code line.
+ *
+ * @throws \Drupal\Component\Serialization\Exception\InvalidDataTypeException
+ * Exception thrown when the Front Matter cannot be parsed.
+ */
+ public function getLine() {
+ return $this->parse()['line'];
+ }
+
+}
diff --git a/core/modules/help_topics/src/HelpTopicDiscovery.php b/core/modules/help_topics/src/HelpTopicDiscovery.php
index 63564f3a8580..159cb00b91cf 100644
--- a/core/modules/help_topics/src/HelpTopicDiscovery.php
+++ b/core/modules/help_topics/src/HelpTopicDiscovery.php
@@ -7,6 +7,8 @@
use Drupal\Component\FileSystem\RegexDirectoryIterator;
use Drupal\Component\Plugin\Discovery\DiscoveryInterface;
use Drupal\Component\Plugin\Discovery\DiscoveryTrait;
+use Drupal\Component\Serialization\Exception\InvalidDataTypeException;
+use Drupal\Core\Serialization\Yaml;
use Drupal\Core\StringTranslation\TranslatableMarkup;
/**
@@ -113,29 +115,37 @@ public function findAll() {
static::FILE_KEY => $file,
];
- // Get the rest of the plugin definition from meta tags contained in the
- // help topic Twig file.
- foreach (get_meta_tags($file) as $key => $value) {
- $key = substr($key, 11);
+ // Get the rest of the plugin definition from front matter contained in
+ // the help topic Twig file.
+ try {
+ $front_matter = FrontMatter::load(file_get_contents($file), Yaml::class)->getData();
+ }
+ catch (InvalidDataTypeException $e) {
+ throw new DiscoveryException(sprintf('Malformed YAML in help topic "%s": %s.', $file, $e->getMessage()));
+ }
+ foreach ($front_matter as $key => $value) {
switch ($key) {
case 'related':
- $data[$key] = array_map('trim', explode(',', $value));
+ if (!is_array($value)) {
+ throw new DiscoveryException("$file contains invalid value for 'related' key, the value must be an array of strings");
+ }
+ $data[$key] = $value;
break;
case 'top_level':
- $data[$key] = TRUE;
- if ($value !== '') {
- throw new DiscoveryException("$file contains invalid meta tag with name='help_topic:top_level', the 'content' property should not exist");
+ if (!is_bool($value)) {
+ throw new DiscoveryException("$file contains invalid value for 'top_level' key, the value must be a Boolean");
}
+ $data[$key] = $value;
break;
case 'label':
$data[$key] = new TranslatableMarkup($value);
break;
default:
- throw new DiscoveryException("$file contains invalid meta tag with name='$key'");
+ throw new DiscoveryException("$file contains invalid key='$key'");
}
}
if (!isset($data['label'])) {
- throw new DiscoveryException("$file does not contain the required meta tag with name='help_topic:label'");
+ throw new DiscoveryException("$file does not contain the required key with name='label'");
}
$all[$provider][$data['id']] = $data;
diff --git a/core/modules/help_topics/src/HelpTopicPluginManager.php b/core/modules/help_topics/src/HelpTopicPluginManager.php
index bfe63d798bd9..636bdda0a428 100644
--- a/core/modules/help_topics/src/HelpTopicPluginManager.php
+++ b/core/modules/help_topics/src/HelpTopicPluginManager.php
@@ -17,18 +17,20 @@
* help_topics. The provider is validated to be the extension that provides the
* help topic.
*
- * The Twig file must contain a meta tag named 'help_topic:label'. It can also
- * contain meta tags named 'help_topic:top_level' and 'help_topic:related'. For
- * example:
+ * The Twig file must contain YAML front matter with a key named 'label'. It can
+ * also contain keys named 'top_level' and 'related'. For example:
* @code
- * <!–– The label/title of the topic. -->
- * <meta name="help_topic:label" content="Configuring error responses, including 403/404 pages"/>
+ * ---
+ * label: 'Configuring error responses, including 403/404 pages'
*
- * <!–– Related help topics in a comma separated help topic ID list. -->
- * <meta name="help_topic:related" content="core.config_basic,core.maintenance"/>
+ * # Related help topics in an array.
+ * related:
+ * - core.config_basic
+ * - core.maintenance
*
- * <!–– If present then the help topic will appear on admin/help. -->
- * <meta name="help_topic:top_level"/>
+ * # If the value is true then the help topic will appear on admin/help.
+ * top_level: true
+ * ---
* @endcode
*
* In addition, modules wishing to add plugins can define them in a
diff --git a/core/modules/help_topics/src/HelpTopicTwig.php b/core/modules/help_topics/src/HelpTopicTwig.php
index 34f3804adb9e..2d383ebee866 100644
--- a/core/modules/help_topics/src/HelpTopicTwig.php
+++ b/core/modules/help_topics/src/HelpTopicTwig.php
@@ -62,8 +62,6 @@ public static function create(ContainerInterface $container, array $configuratio
*/
public function getBody() {
return [
- // Note that #markup elements are automatically XSS admin filtered which
- // removes the meta tags from the rendered HTML.
'#markup' => $this->twig->load('@help_topics/' . $this->getPluginId() . '.html.twig')->render(),
];
}
diff --git a/core/modules/help_topics/src/HelpTopicTwigLoader.php b/core/modules/help_topics/src/HelpTopicTwigLoader.php
index 1e8ebfd217a1..186572550bb9 100644
--- a/core/modules/help_topics/src/HelpTopicTwigLoader.php
+++ b/core/modules/help_topics/src/HelpTopicTwigLoader.php
@@ -2,8 +2,12 @@
namespace Drupal\help_topics;
+use Drupal\Component\Serialization\Exception\InvalidDataTypeException;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Extension\ThemeHandlerInterface;
+use Drupal\Core\Serialization\Yaml;
+use Twig\Error\LoaderError;
+use Twig\Source;
/**
* Loads help topic Twig files from the filesystem.
@@ -59,4 +63,33 @@ protected function addExtension($path) {
}
}
+ /**
+ * {@inheritdoc}
+ */
+ public function getSourceContext($name) {
+ $path = $this->findTemplate($name);
+
+ $contents = file_get_contents($path);
+ try {
+ // Note: always use \Drupal\Core\Serialization\Yaml here instead of the
+ // "serializer.yaml" service. This allows the core serializer to utilize
+ // core related functionality which isn't available as the standalone
+ // component based serializer.
+ $front_matter = FrontMatter::load($contents, Yaml::class);
+
+ // Reconstruct the content if there is front matter data detected. Prepend
+ // the source with {% line \d+ %} to inform Twig that the source code
+ // actually starts on a different line past the front matter data. This is
+ // particularly useful when used in error reporting.
+ if ($front_matter->getData() && ($line = $front_matter->getLine())) {
+ $contents = "{% line $line %}" . $front_matter->getCode();
+ }
+ }
+ catch (InvalidDataTypeException $e) {
+ throw new LoaderError(sprintf('Malformed YAML in help topic "%s": %s.', $path, $e->getMessage()));
+ }
+
+ return new Source($contents, $name, $path);
+ }
+
}
diff --git a/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.additional.html.twig b/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.additional.html.twig
index 3696dad0ce8b..cb70357edfcf 100644
--- a/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.additional.html.twig
+++ b/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.additional.html.twig
@@ -1,3 +1,6 @@
-<meta name="help_topic:label" content="Additional topic"/>
-<meta name="help_topic:related" content="help_topics_test.test"/>
+---
+label: 'Additional topic'
+related:
+ - help_topics_test.test
+---
<p>{% trans %}This topic should get listed automatically on the Help test topic.{% endtrans %}</p>
diff --git a/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.linked.html.twig b/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.linked.html.twig
index 9a1d37b219e3..a101a1c15c97 100644
--- a/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.linked.html.twig
+++ b/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.linked.html.twig
@@ -1,2 +1,4 @@
-<meta name="help_topic:label" content="Linked topic"/>
+---
+label: 'Linked topic'
+---
<p>{% trans %}This topic is not supposed to be top-level.{% endtrans %}</p>
diff --git a/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.test.html.twig b/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.test.html.twig
index eaf23b14d28b..0a1453602f03 100644
--- a/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.test.html.twig
+++ b/core/modules/help_topics/tests/modules/help_topics_test/help_topics/help_topics_test.test.html.twig
@@ -1,6 +1,10 @@
-<meta name="help_topic:label" content="ABC Help Test module"/>
-<meta name="help_topic:top_level"/>
-<meta name="help_topic:related" content="help_topics_test.linked,does_not_exist.and_no_error"/>
+---
+label: "ABC Help Test module"
+top_level: true
+related:
+ - help_topics_test.linked
+ - does_not_exist.and_no_error
+---
{% set help_topic_url = render_var(url('help_topics.help_topic', {id: 'help_topics_test.additional'})) %}
<p>{% trans %}This is a test. It should <a href="{{ help_topic_url }}">link to the additional topic</a>. Also there should be a related topic link below to the Help module topic page and the linked topic.{% endtrans %}</p>
<p>{% trans %}Test translation.{% endtrans %}</p>
diff --git a/core/modules/help_topics/tests/src/Functional/HelpTopicTest.php b/core/modules/help_topics/tests/src/Functional/HelpTopicTest.php
index 769850a16ed9..b5877f7d48b3 100644
--- a/core/modules/help_topics/tests/src/Functional/HelpTopicTest.php
+++ b/core/modules/help_topics/tests/src/Functional/HelpTopicTest.php
@@ -196,12 +196,7 @@ protected function verifyHelpLinks() {
// Verify theme provided help topics work and can be related.
$this->drupalGet('admin/help/topic/help_topics_test_theme.test');
$session->pageTextContains('This is a theme provided topic.');
- // Use the article element to provide a positive assertion to improve the
- // assertion that the help html does not contain meta tags.
$this->assertContains('This is a theme provided topic.', $session->elementExists('css', 'article')->getText());
- // Ensure that meta tags containing plugin information do not appear on
- // topic pages
- $session->elementNotExists('css', 'article meta');
$this->clickLink('Additional topic');
$session->linkExists('XYZ Help Test theme');
diff --git a/core/modules/help_topics/tests/src/Unit/HelpTopicDiscoveryTest.php b/core/modules/help_topics/tests/src/Unit/HelpTopicDiscoveryTest.php
index bad221673d74..99cfb13834dc 100644
--- a/core/modules/help_topics/tests/src/Unit/HelpTopicDiscoveryTest.php
+++ b/core/modules/help_topics/tests/src/Unit/HelpTopicDiscoveryTest.php
@@ -41,7 +41,7 @@ public function testDiscoveryExceptionProviderMismatch() {
/**
* @covers ::findAll
*/
- public function testDiscoveryExceptionMissingLabelMetaTag() {
+ public function testDiscoveryExceptionMissingLabel() {
vfsStream::setup('root');
vfsStream::create([
@@ -57,21 +57,20 @@ public function testDiscoveryExceptionMissingLabelMetaTag() {
$discovery = new HelpTopicDiscovery(['test' => vfsStream::url('root/modules/test/help_topics')]);
$this->expectException(DiscoveryException::class);
- $this->expectExceptionMessage("vfs://root/modules/test/help_topics/test.topic.html.twig does not contain the required meta tag with name='help_topic:label'");
+ $this->expectExceptionMessage("vfs://root/modules/test/help_topics/test.topic.html.twig does not contain the required key with name='label'");
$discovery->getDefinitions();
}
/**
* @covers ::findAll
*/
- public function testDiscoveryExceptionInvalidMetaTag() {
+ public function testDiscoveryExceptionInvalidYamlKey() {
vfsStream::setup('root');
- // Note a blank line is required after the last meta tag otherwise the last
- // meta tag is not parsed.
$topic_content = <<<EOF
-<meta name="help_topic:label" content="A label"/>
-<meta name="help_topic:foo" content="bar"/>
-
+---
+label: 'A label'
+foo: bar
+---
EOF;
vfsStream::create([
@@ -86,7 +85,7 @@ public function testDiscoveryExceptionInvalidMetaTag() {
$discovery = new HelpTopicDiscovery(['test' => vfsStream::url('root/modules/test/help_topics')]);
$this->expectException(DiscoveryException::class);
- $this->expectExceptionMessage("vfs://root/modules/test/help_topics/test.topic.html.twig contains invalid meta tag with name='foo'");
+ $this->expectExceptionMessage("vfs://root/modules/test/help_topics/test.topic.html.twig contains invalid key='foo'");
$discovery->getDefinitions();
}
@@ -95,12 +94,39 @@ public function testDiscoveryExceptionInvalidMetaTag() {
*/
public function testDiscoveryExceptionInvalidTopLevel() {
vfsStream::setup('root');
- // Note a blank line is required after the last meta tag otherwise the last
- // meta tag is not parsed.
$topic_content = <<<EOF
-<meta name="help_topic:label" content="A label"/>
-<meta name="help_topic:top_level" content="bar"/>
+---
+label: 'A label'
+top_level: bar
+---
+EOF;
+
+ vfsStream::create([
+ 'modules' => [
+ 'test' => [
+ 'help_topics' => [
+ 'test.topic.html.twig' => $topic_content,
+ ],
+ ],
+ ],
+ ]);
+ $discovery = new HelpTopicDiscovery(['test' => vfsStream::url('root/modules/test/help_topics')]);
+
+ $this->expectException(DiscoveryException::class);
+ $this->expectExceptionMessage("vfs://root/modules/test/help_topics/test.topic.html.twig contains invalid value for 'top_level' key, the value must be a Boolean");
+ $discovery->getDefinitions();
+ }
+ /**
+ * @covers ::findAll
+ */
+ public function testDiscoveryExceptionInvalidRelated() {
+ vfsStream::setup('root');
+ $topic_content = <<<EOF
+---
+label: 'A label'
+related: "one, two"
+---
EOF;
vfsStream::create([
@@ -115,7 +141,7 @@ public function testDiscoveryExceptionInvalidTopLevel() {
$discovery = new HelpTopicDiscovery(['test' => vfsStream::url('root/modules/test/help_topics')]);
$this->expectException(DiscoveryException::class);
- $this->expectExceptionMessage("vfs://root/modules/test/help_topics/test.topic.html.twig contains invalid meta tag with name='help_topic:top_level', the 'content' property should not exist");
+ $this->expectExceptionMessage("vfs://root/modules/test/help_topics/test.topic.html.twig contains invalid value for 'related' key, the value must be an array of strings");
$discovery->getDefinitions();
}
@@ -125,7 +151,9 @@ public function testDiscoveryExceptionInvalidTopLevel() {
public function testHelpTopicsExtensionProviderSpecialCase() {
vfsStream::setup('root');
$topic_content = <<<EOF
-<meta name="help_topic:label" content="Test"/>
+---
+label: Test
+---
<h2>Test</h2>
EOF;
@@ -142,6 +170,33 @@ public function testHelpTopicsExtensionProviderSpecialCase() {
$this->assertArrayHasKey('core.topic', $discovery->getDefinitions());
}
+ /**
+ * @covers ::findAll
+ */
+ public function testHelpTopicsBrokenYaml() {
+ vfsStream::setup('root');
+ $topic_content = <<<EOF
+---
+foo : [bar}
+---
+<h2>Test</h2>
+EOF;
+
+ vfsStream::create([
+ 'modules' => [
+ 'help_topics' => [
+ 'help_topics' => [
+ 'core.topic.html.twig' => $topic_content,
+ ],
+ ],
+ ],
+ ]);
+ $discovery = new HelpTopicDiscovery(['help_topics' => vfsStream::url('root/modules/help_topics/help_topics')]);
+ $this->expectException(DiscoveryException::class);
+ $this->expectExceptionMessage("Malformed YAML in help topic \"vfs://root/modules/help_topics/help_topics/core.topic.html.twig\":");
+ $discovery->getDefinitions();
+ }
+
/**
* @covers ::findAll
*/
@@ -152,9 +207,14 @@ public function testHelpTopicsDefinition() {
vfsStream::setup('root');
$topic_content = <<<EOF
-<meta name="help_topic:label" content="Test"/>
-<meta name="help_topic:top_level"/>
-<meta name="help_topic:related" content="one, two ,three"/>
+---
+label: 'Test'
+top_level: true
+related:
+ - one
+ - two
+ - three
+---
<h2>Test</h2>
EOF;
diff --git a/core/modules/help_topics/tests/src/Unit/HelpTopicTwigLoaderTest.php b/core/modules/help_topics/tests/src/Unit/HelpTopicTwigLoaderTest.php
index cf4b8c61c8ae..2f5258d054b6 100644
--- a/core/modules/help_topics/tests/src/Unit/HelpTopicTwigLoaderTest.php
+++ b/core/modules/help_topics/tests/src/Unit/HelpTopicTwigLoaderTest.php
@@ -5,6 +5,7 @@
use Drupal\help_topics\HelpTopicTwigLoader;
use Drupal\Tests\UnitTestCase;
use org\bovigo\vfs\vfsStream;
+use Twig\Error\LoaderError;
/**
* Unit test for the HelpTopicTwigLoader class.
@@ -51,6 +52,24 @@ public function testConstructor() {
$this->assertTrue(in_array($this->directories['theme']['test'] . '/help_topics', $paths));
}
+ /**
+ * @covers ::getSourceContext
+ */
+ public function testGetSourceContext() {
+ $source = $this->helpLoader->getSourceContext('@' . HelpTopicTwigLoader::MAIN_NAMESPACE . '/test.topic.html.twig');
+ $this->assertEquals('{% line 4 %}<h2>Test</h2>', $source->getCode());
+ }
+
+ /**
+ * @covers ::getSourceContext
+ */
+ public function testGetSourceContextException() {
+ $this->expectException(LoaderError::class);
+ $this->expectExceptionMessage("Malformed YAML in help topic \"vfs://root/modules/test/help_topics/test.invalid_yaml.html.twig\":");
+
+ $source = $this->helpLoader->getSourceContext('@' . HelpTopicTwigLoader::MAIN_NAMESPACE . '/test.invalid_yaml.html.twig');
+ }
+
/**
* Creates a mock module or theme handler class for the test.
*
@@ -86,9 +105,22 @@ protected function getHandlerMock($type) {
* Sets up the virtual file system.
*/
protected function setUpVfs() {
+ $content = <<<EOF
+---
+label: Test
+---
+<h2>Test</h2>
+EOF;
+ $invalid_content = <<<EOF
+---
+foo : [bar}
+---
+<h2>Test</h2>
+EOF;
$help_topics_dir = [
'help_topics' => [
- 'test.topic.html.twig' => '',
+ 'test.topic.html.twig' => $content,
+ 'test.invalid_yaml.html.twig' => $invalid_content,
],
];
diff --git a/core/modules/help_topics/tests/src/Unit/HelpTopicTwigTest.php b/core/modules/help_topics/tests/src/Unit/HelpTopicTwigTest.php
index 70e085236fe6..201b73b70fd3 100644
--- a/core/modules/help_topics/tests/src/Unit/HelpTopicTwigTest.php
+++ b/core/modules/help_topics/tests/src/Unit/HelpTopicTwigTest.php
@@ -65,7 +65,7 @@ public function testText() {
* @covers ::isTopLevel
* @covers ::getRelated
*/
- public function testMeta() {
+ public function testDefinition() {
$this->assertEquals($this->helpTopic->getProvider(),
self::PLUGIN_INFORMATION['provider']);
$this->assertEquals($this->helpTopic->isTopLevel(),
diff --git a/core/modules/help_topics/tests/themes/help_topics_test_theme/help_topics/help_topics_test_theme.test.html.twig b/core/modules/help_topics/tests/themes/help_topics_test_theme/help_topics/help_topics_test_theme.test.html.twig
index c2893d74bf34..79c85eed4d3e 100644
--- a/core/modules/help_topics/tests/themes/help_topics_test_theme/help_topics/help_topics_test_theme.test.html.twig
+++ b/core/modules/help_topics/tests/themes/help_topics_test_theme/help_topics/help_topics_test_theme.test.html.twig
@@ -1,4 +1,7 @@
-<meta name="help_topic:label" content="XYZ Help Test theme"/>
-<meta name="help_topic:top_level"/>
-<meta name="help_topic:related" content="help_topics_test.additional"/>
+---
+label: 'XYZ Help Test theme'
+top_level: true
+related:
+ - help_topics_test.additional
+---
<p>{% trans %}This is a theme provided topic.{% endtrans %}</p>
--
GitLab