Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Following up on discussions in issues such as #2938800: Finalize wording for Toolbar warning message and #2941582: Create a drupal.org documentation page for Umami profile to explain why it shouldn't be used in production sites and elsewhere, the Umami profile should implement hook_help() so as to provide an introduction about what the profile is for.
The toolbar warning message can then link to this help text, and the help text can in turn link to https://www.drupal.org/docs/8/umami-drupal-8-demonstration-installation-... (the drupal.org page that was created in #2941582: Create a drupal.org documentation page for Umami profile to explain why it shouldn't be used in production sites).
This has a couple advantages:
- It more closely follows the standard Drupal help pattern (in-site basic help, plus a link to drupal.org for more in-depth discussion).
- It allows the help text to be translated.
- It allows the help text to be reached via the standard Help system (not just via the toolbar).
To address concerns raised previously about what happens to the toolbar warning when the Help module is turned off, we could just make the warning in the toolbar link directly to the drupal.org documentation page when the Help module is disabled.
As part of this issue, it would also be good to review the text at https://www.drupal.org/docs/8/umami-drupal-8-demonstration-installation-... and make sure it is conveying the message it should be and that it meshes well with the text in hook_help(). For example:
- I interpreted this as being the install profile's generic documentation page, but the current text focuses too much on the recommendation not to use it for a real site. That can be part of the page, but shouldn't be the loudest part. I think that could be mostly addressed by deleting the really large "The Umami installation profile is for demo purposes only" sub-headline that is currently there.
-
Once you've tried Drupal using Umami and want to build your own site, simply reinstall Drupal selecting the Minimal or Standard profiles from the install screen.
We shouldn't assume Standard or Minimal are the only ones available, since there are contrib profiles too. I would change this to something like "...simply reinstall Drupal and select a different installation profile (such as Standard) from the install screen."
Finally, when we link to this page, the code currently in core links to it via https://www.drupal.org/node/2941833. That's the same page as https://www.drupal.org/docs/8/umami-drupal-8-demonstration-installation-... but a less friendly URL. I suggest using the friendly URL instead.
| Comment | File | Size | Author |
|---|
Issue fork drupal-2942016
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
- 2942016-add-a-hookhelp
changes, plain diff MR !3879 - 2942016-followup changes, plain diff MR !6069
Comments
Comment #2
David_Rothstein commentedHere's an initial patch. The text might need some work, but it's a start.
I didn't change the link to point to the user-friendly URL mentioned in the issue summary yet, nor did I make any edits to the drupal.org documentation page. I'm still not sure if that page is intended to be a "regular" module help page similar to e.g. https://www.drupal.org/docs/8/core/modules/contact/overview (I think it should be) in which case it will wind up with a different URL anyway once it is moved to the correct page in the drupal.org documentation structure.
Comment #3
markconroy commentedHi David,
Thanks a lot for this. It looks very interesting. We'll discuss it during today's weekly meeting.
Just to mention, the current documentation page we have on Drupal.org is not a generic documentation page; it's a page specifically about the experimental nature of this profile. We don't have any content yet for the more generic "About Umami" type pages.
Comment #4
kaythay commentedA reroll based on the minor language change from another issue at line 71.
Comment #5
john cook commentedThanks for re-rolling @kaythay.
This is a good way to demonstrate how to implement the help system.
When patched the warning in the admin bar is changed to the help page for the profile instead of being redirected to D.O.
I think that the "What to do when you are ready to build your Drupal website" should be split out with it's own <h> tag. This would make it clearer that it is not a 'use' of Umami.
The
<h3>s should be changed to<h2>s. This is a HTML schematic error and could be an a11y issue.It would be nice to have mode uses for the demo but theses could be added later, along with changing the URL to a proper documentation page.
Comment #6
markconroy commentedDoes this mean we need to maintain two copies of the text for documentation? One on drupal.org and one in hook_help? Are they currently in sync?
Comment #7
john cook commented@markconroy, the first paragraph in the help text is similar to the first paragraph on Umami: Drupal 8 demonstration installation profile. The rest of the help text is new. So they are not currently in sync.
I see this as a short section to explain a little about Umami, and doesn't change very often. But with a link (or links) to the main documentation, that can change a lot, on D.O.
Comment #17
rassoni commentedFixed Custom failed to patch #4 for D10.
Addressed #5 feedback points.
- Addressed
- Addressed
Comment #18
rassoni commentedFixed Custom failed to patch #17 for D10.
Comment #20
rassoni commentedSorry for converting patch into MR due to local CI failed.Please review MR.
Below points addressed:
Comment #21
markconroy commentedThanks for working on this @Rassoni. I think it's nearly ready. I've made some small changes to remove the
dlelements and use heading elements instead, as I think this is more correct semantically for this use case.Comment #22
smustgrave commentedGoing to mark this but wanted to note
If a follow up should be opened to create help_topic for help_hook.
Visually this looks weird but think it's because the H3s are close in size to H2s
Comment #23
markconroy commentedYes, and if I remember correctly, this was using Claro, not Umami, for the admin theme, so maybe we could file a follow-up with Claro maintainers.
Comment #25
catchNot sure why this is removing experimental from the profile name, I think that needs UX and/or product manager review if we want to do that, it's currently there so people don't think they can install the profile and build a site from it.
Also should this still be hook_help or should it use a help topic at this point? There's not a direct replacement for hook_help() from the new help system yet, so the answer might be 'yes it should still use hook_help()' but wanted to check.
Comment #26
markconroy commentedThanks @catch
This should definitely NOT be removing "Experimental" from the profile name. Let's get that put back in before we move this to RTBC. With that being the case, I'm removing the "Needs product manager review tag".
Comment #28
narendrarComment #29
smustgrave commentedApplied the MR 3879 and verified the help page see screenshot
Uninstalled help module
Verified "This site is intended for demonstration purposes." links to the Drupal page.
Hiding patches for clarity.
Comment #30
longwaveCommitted 97ca061 and pushed to 11.x. Thanks!
Comment #32
andypostIt needs follow-up as the permission should be access help pages since 10.1 https://www.drupal.org/node/3344060
Comment #33
andypostComment #35
andypostFiled follow-up MR https://git.drupalcode.org/project/drupal/-/merge_requests/6069
Comment #36
smustgrave commentedSmall change seems fine.
Comment #38
longwaveThank you for spotting that @andypost.