[UX] Either get rid of MENU_SUGGESTED_ITEM or change the way it works in a way that fixes UX WTFs

[klonos]

I initially started typing this in a comment in #5674, but realized that I might be derailing the issue (which aims to fix some menu-related issues when upgrading from D7 - which makes that either a task of a bug), so I am starting this new issue here (which is more of a feature request).

Why was MENU_SUGGESTED_ITEM introduced?

So let me see if I've got this right... it seems to me that MENU_SUGGESTED_ITEM was invented in order to hold "parked" menu items. So a module can use it to "suggest" menu items, which will only be available when that module is enabled. However, the difference with other module-provided menu items is that:

1. These items are not for admin-related tasks, so they are not to be added in the admin bar
2. We needed a way to have such menu items in a disabled state initially, so that each site owner could decide:
   • whether the suggested menu parent is the right one, and if not, then move the menu item to another parent (which could be an entirely different menu than the suggested one).
   • whether they even need that menu item in the first place (and if not, then keep it disabled - there is no way to delete these items anyway).

Is that it? It sounds like some legacy thing, that was implemented that way at a time when no other way was available or thought of to do things in a better, more user-friendly manner.

FWIW, MENU_SUGGESTED_ITEM was removed in D8.1: https://www.drupal.org/project/drupal/issues/1013726 ...but then again, the old routing system was removed in D8 anyway. So this is most likely irrelevant to what we are trying to do here.

Current UX WTFs

It seems to me that we are currently making many assumptions, which may lead to WTFs depending on what the site builder/owner wants to actually achieve. Consider the following scenarios (there can be many more, I'm sure):

• Oh, that module I just enabled created a menu item for me (a non-admin one that is - it is not in the admin bar). Cool that I don't have to figure out default paths etc. 👍🏼 ...but:
  • I just randomly discovered it. How am I supposed to know that it even exists? 👎🏼
  • Why was it placed in the main navigation menu? I don't want it there 👎🏼
  • Why is it disabled? 👎🏼
• WTF?! The menu item I had in that menu just vanished 👎🏼 ...did disabling that module the other day have something to do with this? (this is the current behaviour with the PR available for #5674)
  • OK, I re-enabled that module. ...nice! That menu item was restored in the menu I had it, enabled, and in the order I had it. Backdrop is smart! 👍🏼 (again, this is what happens with the PR in #5674 - thank you @indigoxela 🙏🏼 )
• Decided that I don't need the functionality of the module. I disable the module that provided that menu item, and I then completely uninstall it. ...nice! the menu item it provided is now gone 👍🏼 ...clear caches (all or just menu) ...some time goes by, people either forget about that module and the menu item it provided, in what parent menu it was moved etc. because a lot of time has passed since, or maybe this is now a different site admin/developer - not the same person that had originally enabled, configured, and then disabled and uninstalled the module ...I need that module again, so I re-enable the module -> look for the menu item in the main nav menu, like the documentation for that module suggests -> menu item is not there. WTF! 👎🏼

Proposed solution/PoC

All that sound like an interesting UX problem and I would like to work on and provide a PoC with a few suggestions/ideas, which may solve some of these WTFs in what I think would be a better way...

So, if we are adding a MENU_SUGGESTED_ITEM menu item when enabling a module, how about we:

• Don't place it in any specific existing menu (empty parent - don't make assumptions). We instead add it in some sort of "preconfigured" or "suggested" menu items library. People then are given the option to either "+ Add custom menu item" (create new) or "+ Place existing menu item" (menu items provided by modules via hook_menu())
• This new "module-provided menu item library" (whatever we want to call it) that is either under Structure -> Menus, or under Reports -> Module-provided menu items, does the following:
  • Shows me in which menu each such MENU_SUGGESTED_ITEM item is currently placed, and also provides handy links to jump to that menu
  • If a MENU_SUGGESTED_ITEM menu item is unused (was never placed anywhere, so it still has an empty parent), the link says "place menu item".
• Have hook_menu() throw a status message when the module it enabled for the first time, along the lines of "The xyz module added the following menu item(s) ...[list of menu items + links to edit the menus that hold them - or jump to the suggested menu items library]"
• Similarly, when disabling a module that provides a menu item, we throw a message (via confirm_form() or otherwise), to let people know that disabling the module will also remove the menu item(s) provided by it (if they are placed in a menu, and if they are not disabled).

[klonos]

For reference: https://docs.backdropcms.org/api/backdrop/1/search/MENU_SUGGESTED_ITEM

Menu type -- A normal menu item, hidden until enabled by an administrator.

Modules may "suggest" menu items that the administrator may enable. They act just as callbacks do until enabled, at which time they act like normal items. Note for the value: 0x0010 was a flag which is no longer used, but this way the values of MENU_CALLBACK and MENU_SUGGESTED_ITEM are separate.

[indigoxela]

Personally, I find the concept of MENU_SUGGESTED_ITEM a bit weird. But for BC reasons we might have to stick with it.

Putting those items in the main menu doesn't seem ideal. But where else can we park them, so people find them and they're not in the way?

[klonos]

But where else can we park them, so people find them and they're not in the way?

This is what I currently have on my local:

...as I said, this is only a PoC - working on it still, so nothing is set (especially what things will be called). I will file a PR when I've addressed most of the UX issues I've identified, and will request feedback then.

[klonos]

PoC PR for initial discussion/feedback here: https://github.com/backdrop/backdrop/pull/4233

...I don't expect tests to pass etc., plus there's this error that is thrown when trying to edit any menu item that is MENU_SUGGESTED_ITEM:

I've intentionally left that there, as a reminder to add an update hook that removes this silly 'internal' menu from MENU_SUGGESTED_ITEM menu items.

[indigoxela]

That's a very promising approach. A little rough around the edges, some confusing wording - but hey, promising.

[argiepiano]

I like this!

[quicksketch]

I sort of think that MENU_SUGGESTED_ITEMs are an unnecessary concept. I think the point was to inform people of new pages that are added by a module? For example Basic Cart module might make a suggested item at /cart (however it doesn't, it uses MENU_CALLBACK). I think most modules are completely fine with just mentioning in the README.md or in the admin configuration pages if they expose new pages that may or may not be wanted in the menu navigation.

Rather than adding more infrastructure around MENU_SUGGESTED_ITEM, we could instead add an update hook to convert them to normal, disabled menu links and start treating them identical to MENU_CALLBACK. And then perhaps throw deprecated notices on menu rebuilds.

[avpaderno]

MENU_SUGGESTED_ITEM has been defined in Drupal since Drupal 4.6, but it has been only used from Drupal core to hide a menu item in _menu_link_build(). Seven Drupal 7 core modules (excluding test modules) use that constant in their hook_menu() implementation; of those modules, in Backdrop, only the following ones define a MENU_SUGGESTED_ITEM item.

• Book
• Contact
• Search

I tend to agree with @quicksketch that those menu items should be converted to MENU_CALLBACK items.
As developer, I find difficult to decide which menu items should be MENU_SUGGESTED_ITEM; I would probably tend to make MENU_SUGGESTED_ITEM every MENU_CALLBACK menu item or, on the contrary, always use MENU_CALLBACK menu items.

[indigoxela]

So, is there consensus, that we should switch to regular MENU_CALLBACK instead?

I'm asking, because there's an actual bug when upgrading from D7, that needs to get fixed: #5674.

What happens after that? Should we deprecate MENU_SUGGESTED_ITEM? Can we do that in 1.x, anyway?

[klonos]

As developer, I find difficult to decide which menu items should be MENU_SUGGESTED_ITEM;

Was the intended purpose of MENU_SUGGESTED_ITEM to be a variation of MENU_CALLBACK where the menu items are being added but disabled? The name of this constant seems to be suggesting that (pun 😅 ).

[avpaderno]

Basing on the constant definition, that was the intent.

Modules may "suggest" menu items that the administrator may enable. They act just as callbacks do until enabled, at which time they act like normal items. Note for the value: 0x0010 was a flag which is no longer used, but this way the values of MENU_CALLBACK and MENU_SUGGESTED_ITEM are separate.

[avpaderno]

Modules may "suggest" menu items that the administrator may enable.

For what I recall, Drupal does not have a page where administrators can enable suggested menu items. It means that a MENU_SUGGESTED_ITEM item will always be handled as a MENU_CALLBACK item and that the concept of suggested menu items have never been fully implemented.