- 🇺🇸United States Amber Himes Matz Portland, OR USA
Just adding a handy link to the change record to the issue summary (under API changes) since the link to it is buried in a comment.
On 📌 [META] Convert hook_help() module overview text to topics Fixed we are converting our hook_help() text into Help Topics (and making improvements). As part of that effort, on #3072312: Review/fix/delete existing help topics → , we are going through the initial topics we added as proof of concept when the original Help Topics patch went in. We came across a problem that is sort of a regression from things we could do in hook_help() that we can't currently do in a help topic.
In hook_help(), we could have code like this, to make a link only if another module exists:
$url = (\Drupal::moduleHandler()->moduleExists('block')) ? Url::fromRoute('help.page', ['name' => 'block'])->toString() : '#';
But we don't have a way to do that in a Twig template.
We also don't have a way to verify access before we put links in, so we may be leading users to 403 pages. This was also true in hook_help().
As a note, we actually don't even have a good way to make URLs at all in Twig -- see this related issue: #2996305: Add support for the url() function to twig {%trans%} →
Make a dedicated function for help topic Twig templates that outputs either a link or plain text. It should avoid throwing exceptions for things like route not found (perhaps a module isn't installed), invalid/missing parameters (maybe a topic can't be found), and it should not make a link that a given user cannot visit. In those cases, plain text would be put out, and if all is well, a link would be put out.
Since about half the links in our topics are links to other topics, it would be really helpful to also have a function that outputs a link to a topic, using the topic title as a link text.
Make/review/commit a patch that adds safe link functions for help topics: one for generic routes with generic link text, and the other for help topics with the topic title as link text. If the link is not accessible, or a route/parameter problem happens during link generation, plain text should be returned instead of a link.
Follow-up needed:
Issue:
#3192585: Fix up topics to use new help_topic_link function →
That issue is to make sure we:
- Fix up all the topics to use the new functions.
- Enforce their usage in help topics rather than the Twig base url() function. This can be added to the existing help topics syntax test.
- Update the help topic standards page to use this new function.
https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... →
a. Missing routes and parameters in URLs will not cause PHP exceptions on Help Topics pages.
b. Links generated in Help Topic pages will not take users to 403 pages.
c. In both of those cases, the link text will still show up as plain text.
No changes to existing APIs, but new Twig functions will be added for help topics to accomplish the above. Change record: New functions for making links in Help Topics →
None.
Probably does not need to go into release notes, as this is still Experimental.
Fixed
9.2
Last updated
Not all content is available!
It's likely this issue predates Contrib.social: some issue and comment data are missing.
Just adding a handy link to the change record to the issue summary (under API changes) since the link to it is buried in a comment.