diff --git a/README.txt b/README.txt index 887fc5d..601646a 100644 --- a/README.txt +++ b/README.txt @@ -1,15 +1,19 @@ -Help Topics module +Configurable Help module This module provides a way for site administrators to create and edit help topic pages. These pages are part of your site configuration, and can therefore be translated, imported, and exported. They can also be provided by modules, themes, and installation profiles. +This module works in conjunction with the core (currently Experimental) Help +Topics module. You will only be able to edit the topics you create, not the +built-in topics that modules and themes provide using the Help Topics +module. However, all topics will be seamlessly displayed together. INSTALLATION Install the module in the normal way for Drupal modules. The only dependency is -the core Help module. +the core Help and Help Topics modules. If you install the core Configuration Translation module (and its dependencies, Interface Translation and Language), and if you configure languages on your @@ -29,28 +33,14 @@ also be listed on the administration page, where you can edit them if you wish. VIEWING TOPICS All topics where the "Top-level" field has value TRUE are listed on the main -Help page (path admin/help). Topics where "Top-level" is FALSE will not be -listed on this page, but they may be linked in the Related Topics section of -other help topics. +Help page (path admin/help), along with topics provided by modules and +themes. Topics where "Top-level" is FALSE will not be listed on this page, but +they may be linked in the Related Topics section of other help topics. Administrators can also view individual help topics by clicking on the topic title from the help topic administration page. -HANDLING UPDATES - -If you update a module or theme on your site, the module/theme may add or update -the configurable help topics it provides. Help topics are part of your site -configuration, and due to how the Drupal Core config system works, Drupal would -never check or notice that new or updated topics exist (it only imports -configuration from modules and themes when you first install, and then never -looks at the provided default configuration after that). - -You can use the contributed Configuration Update Manager module -(https://www.drupal.org/project/config_update) to check for updates and get -additional/updated topics. Check its README file for instructions. - - SHARING TOPICS WITH OTHER SITES If you have created help topics that you would like to share with other sites, @@ -67,28 +57,3 @@ Configuration synchronization >> Import >> Single item (path admin/config/development/configuration/single/import). Choose Configuration Type "Help topic", and paste the contents of a previously-exported configuration file into the text box. - - -DEVELOPERS: AUTHORING TOPICS FOR A MODULE, THEME, OR PROFILE - -If you are developing an extension (module, theme, or profile/distribution) for -Drupal, your extension can provide one or more help topics, since help topics -are Configuration Entities. To do this: - -(1) Create the help topics using the Help Topics UI. Make sure to fill in - the Dependencies field on each topic (make them depend on your - module/theme; not necessary for installation profiles). Give each topic a - machine name prefixed by your extension's machine name, to avoid conflicts. - Make sure to have one "top level" topic, so that your help will be listed - on the main Help page. Avoid having too many top-level topics, as it will - clutter up the page; instead use the Related and List On fields to link - your topics together. - -(2) Export the topics from the Configuration management pages - (admin/config/development/configuration/single/export) -- they're of type - "Help topic". Save each one using the suggested file name into your - extension's config/optional directory. So for example, you might have a file - called config/optional/config_help.topic.mymodule.yml. - -(3) Then anyone using your module who has the Help Topics module also - installed will get your topics in their configuration. diff --git a/config/install/filter.format.help.yml b/config/install/filter.format.help.yml index ad48871..274682a 100644 --- a/config/install/filter.format.help.yml +++ b/config/install/filter.format.help.yml @@ -3,7 +3,7 @@ status: true dependencies: enforced: module: - - help_topics + - config_help name: Help format: help weight: 0 diff --git a/config/schema/help_topics.schema.yml b/config/schema/config_help.schema.yml similarity index 76% rename from config/schema/help_topics.schema.yml rename to config/schema/config_help.schema.yml index 61142c6..833873d 100644 --- a/config/schema/help_topics.schema.yml +++ b/config/schema/config_help.schema.yml @@ -1,4 +1,4 @@ -help_topics.topic.*: +config_help.topic.*: type: config_entity label: 'Help topic' mapping: @@ -11,9 +11,6 @@ help_topics.topic.*: top_level: type: boolean label: 'Top-level topic' - locked: - type: boolean - label: 'Locked' related: type: sequence label: 'Related topics' @@ -27,14 +24,14 @@ help_topics.topic.*: body: type: sequence label: 'Body' - form_element_class: '\Drupal\help_topics\FormElement\HelpTopicBody' + form_element_class: '\Drupal\config_help\FormElement\HelpTopicBody' sequence: - type: help_topics_text + type: config_help_text body_format: type: string label: 'Body format' -help_topics_text: +config_help_text: type: mapping mapping: prefix_tags: @@ -43,7 +40,7 @@ help_topics_text: text: type: text label: 'Inner text' - form_element_class: '\Drupal\help_topics\FormElement\HelpTopicBodyChunk' + form_element_class: '\Drupal\config_help\FormElement\HelpTopicBodyChunk' suffix_tags: type: string label: 'Suffix tags' diff --git a/config_help.info.yml b/config_help.info.yml new file mode 100644 index 0000000..554259c --- /dev/null +++ b/config_help.info.yml @@ -0,0 +1,9 @@ +name: Configurable Help +type: module +description: 'Allows editing configurable help topics' +core: 8.x +configure: entity.config_help.collection +dependencies: + - drupal:help + - drupal:help_topics + - drupal:filter diff --git a/config_help.links.action.yml b/config_help.links.action.yml new file mode 100644 index 0000000..005e0a6 --- /dev/null +++ b/config_help.links.action.yml @@ -0,0 +1,5 @@ +entity.config_help.add_form: + route_name: entity.config_help.add_form + title: 'Add new help topic' + appears_on: + - entity.config_help.collection diff --git a/help_topics.links.menu.yml b/config_help.links.menu.yml similarity index 60% rename from help_topics.links.menu.yml rename to config_help.links.menu.yml index f62c4fb..090dcbe 100644 --- a/help_topics.links.menu.yml +++ b/config_help.links.menu.yml @@ -1,5 +1,5 @@ -entity.help_topic.collection: +entity.config_help.collection: title: Help topics description: Add, delete, and edit help topics. - route_name: entity.help_topic.collection + route_name: entity.config_help.collection parent: system.admin_config_development diff --git a/config_help.links.task.yml b/config_help.links.task.yml new file mode 100644 index 0000000..54d18b0 --- /dev/null +++ b/config_help.links.task.yml @@ -0,0 +1,10 @@ +entity.config_help.edit_form: + title: Edit + route_name: entity.config_help.edit_form + base_route: entity.config_help.edit_form + +entity.config_help.delete_form: + route_name: entity.config_help.delete_form + base_route: entity.config_help.edit_form + title: Delete + weight: 10 diff --git a/help_topics.module b/config_help.module similarity index 68% rename from help_topics.module rename to config_help.module index 9593335..49348fd 100644 --- a/help_topics.module +++ b/config_help.module @@ -11,18 +11,18 @@ use Drupal\Core\Url; /** * Implements hook_help(). */ -function help_topics_help($route_name, RouteMatchInterface $route_match) { +function config_help_help($route_name, RouteMatchInterface $route_match) { switch ($route_name) { - case 'help.page.help_topics': + case 'help.page.config_help': $output = ''; $output .= '

' . t('About') . '

'; - $output .= '

' . t('The Help Topics module adds configurable and non-configurable help topics to the module overviews from the core Help module. For more information, see the online documentation for the Help Topics module.', [':online' => 'https://www.drupal.org/modules/help_topics']) . '

'; + $output .= '

' . t('The Configurable Help module adds configurable and non-configurable help topics to the module overviews from the core Help module. For more information, see the online documentation for the Help Topics module.', [':online' => 'https://www.drupal.org/modules/config_help']) . '

'; $output .= '

' . t('Uses') . '

'; $output .= '
'; $output .= '
' . t('Configuring help topics') . '
'; $output .= '
' . t('You can add, edit, delete, and translate configurable help topics on the Help topics administration page. Only some topics can be edited. See the Building a help system topic for more information on configuring help topics.', [ - ':topic_admin' => Url::fromRoute('entity.help_topic.collection')->toString(), - ':main_topic' => Url::fromRoute('help_topics.help_topic', ['id' => 'help_system_building'])->toString(), + ':topic_admin' => Url::fromRoute('entity.config_help.collection')->toString(), + ':main_topic' => Url::fromRoute('config_help.config_help', ['id' => 'help_system_building'])->toString(), ]) . '
'; $output .= '
' . t('Viewing help topics') . '
'; $output .= '
' . t('The top-level help topics are listed on the main Help page.', [':help_page' => Url::fromRoute('help.main')->toString()]) . '
'; @@ -34,12 +34,12 @@ function help_topics_help($route_name, RouteMatchInterface $route_match) { case 'help_topics.help_topic': return '

' . t('See the Help page for more topics, or the Help topics administration page to create and edit topics.', [ ':help_page' => Url::fromRoute('help.main')->toString(), - ':help_admin' => Url::fromRoute('entity.help_topic.collection')->toString(), + ':help_admin' => Url::fromRoute('entity.config_help.collection')->toString(), ]) . '

'; - case 'entity.help_topic.collection': - return '

' . t('Depending on your permissions, from this page you can edit unlocked configuration-based help topics, translate topics, add new topics, lock topics to editing, and unlock locked topics. See the Building a help system topic for more information.', [ - ':main_topic' => Url::fromRoute('help_topics.help_topic', ['id' => 'help_system_building'])->toString(), + case 'entity.config_help.collection': + return '

' . t('Depending on your permissions, from this page you can edit configuration-based help topics, translate topics, and add new topics. See the Building a help system topic for more information.', [ + ':main_topic' => Url::fromRoute('config_help.config_help', ['id' => 'help_system_building'])->toString(), ]) . '

'; } } @@ -47,9 +47,9 @@ function help_topics_help($route_name, RouteMatchInterface $route_match) { /** * Implements hook_theme(). */ -function help_topics_theme($existing, $type, $theme, $path) { +function config_help_theme($existing, $type, $theme, $path) { return [ - 'help_topic' => [ + 'config_help' => [ 'variables' => [ 'body' => [], 'related' => [], diff --git a/config_help.permissions.yml b/config_help.permissions.yml new file mode 100644 index 0000000..4b695ff --- /dev/null +++ b/config_help.permissions.yml @@ -0,0 +1,3 @@ +administer config help: + title: 'Administer configured help topics' + description: 'Create, edit, and delete help topics' diff --git a/config_help.routing.yml b/config_help.routing.yml new file mode 100644 index 0000000..ca72fa1 --- /dev/null +++ b/config_help.routing.yml @@ -0,0 +1,20 @@ +config_help.topic_autocomplete: + path: '/help-topics/autocomplete-topic' + defaults: + _controller: '\Drupal\config_help\Controller\AutocompleteController::topicAutocomplete' + requirements: + _permission: 'administer help topics' + +config_help.module_autocomplete: + path: '/help-topics/autocomplete-module' + defaults: + _controller: '\Drupal\config_help\Controller\AutocompleteController::moduleAutocomplete' + requirements: + _permission: 'administer help topics' + +config_help.theme_autocomplete: + path: '/help-topics/autocomplete-theme' + defaults: + _controller: '\Drupal\config_help\Controller\AutocompleteController::themeAutocomplete' + requirements: + _permission: 'administer help topics' diff --git a/help_topics.tokens.inc b/config_help.tokens.inc similarity index 88% rename from help_topics.tokens.inc rename to config_help.tokens.inc index 4005e78..3cdb6d4 100644 --- a/help_topics.tokens.inc +++ b/config_help.tokens.inc @@ -11,7 +11,7 @@ use Drupal\Core\Render\BubbleableMetadata; /** * Implements hook_token_info(). */ -function help_topics_token_info() { +function config_help_token_info() { $types['route'] = [ 'name' => t("Route information"), 'description' => t("Tokens based on route names."), @@ -31,7 +31,7 @@ function help_topics_token_info() { $topics = []; $topics['url'] = [ 'name' => t('URL'), - 'description' => t('The URL to the topic. Provide the topic machine name as help_topic:url:MACHINE_NAME'), + 'description' => t('The URL to the topic. Provide the topic machine name as config_help:url:MACHINE_NAME'), ]; return [ @@ -46,10 +46,10 @@ function help_topics_token_info() { /** * Implements hook_tokens(). */ -function help_topics_tokens($type, $tokens, array $data, array $options, BubbleableMetadata $bubbleable_metadata) { +function config_help_tokens($type, $tokens, array $data, array $options, BubbleableMetadata $bubbleable_metadata) { $replacements = []; $token_service = \Drupal::token(); - /** @var \Drupal\help_topics\Plugin\HelpTopic\HelpTopicPluginManagerInterface $plugin_manager */ + /** @var \Drupal\help_topics\HelpTopicPluginManagerInterface $plugin_manager */ $plugin_manager = \Drupal::service('plugin.manager.help_topic'); // Our tokens generate URLs, which depend on language. See if a language is @@ -66,7 +66,7 @@ function help_topics_tokens($type, $tokens, array $data, array $options, Bubblea if ($type == 'help_topic') { $topics = $token_service->findWithPrefix($tokens, 'url'); foreach ($topics as $name => $original) { - /** @var \Drupal\help_topics\Plugin\HelpTopic\HelpTopicPluginInterface $topic */ + /** @var \Drupal\help_topics\HelpTopicPluginInterface $topic */ if ($plugin_manager->hasDefinition($name) && $topic = $plugin_manager->createInstance($name, [])) { $url = $topic->toUrl($url_options)->toString(TRUE); $replacements[$original] = $url->getGeneratedUrl(); diff --git a/help_topics.info.yml b/help_topics.info.yml deleted file mode 100644 index 602f3b5..0000000 --- a/help_topics.info.yml +++ /dev/null @@ -1,8 +0,0 @@ -name: Help Topics -type: module -description: 'Displays and configures help topics' -core: 8.x -configure: entity.help_topic.collection -dependencies: - - drupal:help - - drupal:filter diff --git a/help_topics.install b/help_topics.install deleted file mode 100644 index c8a6d8f..0000000 --- a/help_topics.install +++ /dev/null @@ -1,132 +0,0 @@ -getEditable('filter.format.help'); - $filters = $config->get('filters'); - foreach ($filters as $index => $filter) { - if ($filter['id'] == 'filter_html') { - $filter['settings']['allowed_html'] .= '