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...
| Comment | File | Size | Author |
|---|---|---|---|
| #8 | 3072353-8-all-tests-pass.patch | 182.25 KB | jhodgdon |
Comments
Comment #2
jhodgdonHere 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.
Comment #3
jhodgdonOK, 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.
Comment #4
jhodgdonSo, 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.
Comment #5
jhodgdonOK! 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.
Comment #6
jhodgdonAnd here's the Core issue I filed about the lack of ability to "decorate" plugin discovery.
Comment #7
jhodgdonOK, 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!
Comment #8
jhodgdonWoot! I got all the tests to pass, and I'm going to go ahead and commit this. Uploading the patch for posterity.
Comment #11
jhodgdonI 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.
Comment #12
jhodgdonFollow-up: #3073943: Update help topic discovery for Configurable Help