The Help Topics module has finally been committed to Drupal Core!

So, we need to take out the parts of this sandbox project that got into Core, and make this into an add-on that allows admins to create their own help topics that will merge in with the ones coming from modules and themes.

I'm going to work on this...

Comments

jhodgdon created an issue. See original summary.

jhodgdon’s picture

StatusFileSize
new99.53 KB

Here is pass 1 at a patch. I haven't tried it yet... This patch so far attempts to:
- change module short name to config_help
- remove a bunch of stuff that we don't need, such as things in the Core Help Topics module, and I think locking (because we just don't need that functionality any more if Core has a way for modules/themes to provide topics, so all the topics will be admin-created)

Next step will be to try it out and fix the inevitable problems, but anyway here it is so I don't lose what I just did.

jhodgdon’s picture

Status: Active » Needs work
Issue tags: +Needs tests
StatusFileSize
new138.08 KB

OK, I think I have it basically working. The tests still need to be updated. Here's a new patch. Things to note:
- Parallel with what the Help Topics core module does, there is now just a "related" field, and not two separate fields (so there is no "list_on".
- Modules/themes should use core Help Topics. So, we don't need the fields that let you define module/theme dependencies.
- The view builder for topics only does the Body section, since the Help Topics module takes care of the Related section.
- In order to get the plugin discovery decorator to work, I had to override the Help Topics plugin manager service and create my own decorator class. This is because the core manager doesn't allow for decorated discovery via special YAML files (it uses Twig), or for decorated discovery via special Twig files. I tried adding a special decorator thing in the info alter function, but that is too late in the process.

One thing that doesn't seem to be working is the bi-directional "Related" thing, at least between configured (not Twig) help topics. Maybe between Twig ones too. I need to look into that more, as well as redo the tests.

jhodgdon’s picture

So, here's a list of the To Dos after that last patch:

a) As noted on previous comment, I need to figure out why the bi-directional "Related" is not working. I.e. if topic A says B is related, B should also list A in its Related topics section. I suspect it's because that is set up too early in the plugin discovery process and our config items are not being processed. Either that or it just doesn't work in core.

b) I haven't tested the tokens functionality yet.

c) I haven't looked at or run any of the tests. They will need some work.

d) I think I should create a Core issue about Help Topics plugin discovery being kind of impossible to decorate. I had to override the plugin manager service in order to do it, but that means a hypothetical other contrib module that also wanted to provide some topic things in a different way would not be able to coexist. For YAML-discovered plugins, any module can just create a little YAML file that tells the plugin manager that it wants to decorate with a class, and that the plugins are provided by a class, and it works. But we can't do this with our Twig discovery. A solution could be that we provide a hook called something like hook_help_topics_discovery_decorators() that you could implement and return an array similar to what you would put in one of those special YAML files. Then in the help topics plugin manager's getDiscovery() method, it would invoke the hook, and decorate the discovery with each value that was returned. This would let as many modules as wanted to, to decorate.

Anyway, I plan to work on all of this tomorrow or Monday.

jhodgdon’s picture

StatusFileSize
new139.57 KB

OK! From the previous comment:

(a) I figured out why the bidirectionality wasn't working and got it working. The reason is that the plugin discovery process goes through all the plugins during findDefinitions() and sets the related field so that it is bidirectional. But then our Derived plugin class didn't pay attention to the values in the plugin definition it gets from the constructor.

(b) I tested tokens manually and they are working.

(d) I realized I could define a hook that would let this module and others decorate Help Topics, for the time being, in this module, while we wait and see whether Core gets this feature or not.

So here's a patch. Still need to do (c) -- fix up the tests.

jhodgdon’s picture

Title: Update this module so it works with Core » Update Configurable Help module so it works with Core Help Topics
Related issues: +#3072519: Help Topics discovery cannot be decorated easily

And here's the Core issue I filed about the lack of ability to "decorate" plugin discovery.

jhodgdon’s picture

StatusFileSize
new162.01 KB

OK, here's the next iteration. I got both of the Kernel tests, as well as the functional HelpTopicsTest, working.

There are two more Functional tests in there: translation and admin. I haven't looked at them yet.

Tests are good. Getting them to pass exposed some bugs and deprecated stuff that I wouldn't have found otherwise. So... 2 more to go!

jhodgdon’s picture

Status: Needs work » Fixed
StatusFileSize
new182.25 KB

Woot! I got all the tests to pass, and I'm going to go ahead and commit this. Uploading the patch for posterity.

  • jhodgdon committed 2a53c3e on 8.x-2.x
    Issue #3072353 by jhodgdon: Update Configurable Help module so it works...

  • jhodgdon committed 174f194 on 8.x-2.x
    Issue #3072353 by jhodgdon: Add a link to admin from the help topics...
jhodgdon’s picture

I added one more thing after that commit -- a little function to alter the heading of the Topics section on admin/help so there is a link to the topics admin page.

jhodgdon’s picture

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.