Provide brief summaries about each category

chrisfromredfin → credited bsnodgrass → .

chrisfromredfin → credited leslieg → .

chrisfromredfin → credited lostcarpark → .

Exists here!
https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →

That link to d.o fixes only one out of the three points listed in the proposed resolution. :/ Plus it is suboptimal if you have to leave your site and the pb search ui to look up the meaning of a category on a different site

Doh! I got overzealous.

Agree 100% that this is needed.

I think the first part has been completed as part of the category revamp, and the new categories have descriptions.

I'm not sure if the descriptions are currently fed to the Project Browser UI.

I think we need some way of accessing those descriptions in the UI. I think a visually hidden element for each label could solve it for screen readers. For non-screen reader users, we need to come up with a UI mechanism. They're a bit old-fashioned, but would tooltips work?

This would probably need to be a separate issue, but I think the descriptions should also be displayed to module maintainers when setting categories for their modules. I don't think we can expect module maintainers to go searching for category descriptions unless they are put in their eyeline when selecting the module categories.

The description/summary about the categories on hover or click would be a very helpful thing not only to new users but also to developers, and site builders as well.

I've started working on this. At the moment I just have it fetching the descriptions with the categories and adding to a span after the category labels. I plan to visually hide this so they'll still be available to screen readers, and I should be able to use that as the basis for providing tooltips.

the downside of tooltips is that a sighted user has to hover over the category title which is not necessarily expected for a list of categories to get the category descriptions there. how about making category titles directly visible instead? with nothing searched yet one option might be making the category descriptions part of the project browser "start page" as outlined in ✨ Show curated content and links on the start page Instead of results without a search query being entered beforehand Active . each tile could provide the information about the category and quick refresher, as well as function as a link triggering an initial filtering of the project list without a search term entered, so the user gets all the modules associated with for example the accessibility category.

I have been working on a basic category tooltip.

I have the following working:

• The JSON API fetches the category descriptions as well as the titles.
• An additional span is placed inside the label containing the description. This is visually hidden so it will only be visible to screen readers.
• I've added a mouseover event to the checkbox and the title to show the tooltip.
• I've also added a focus event to the checkbox to show the tooltip, so moving over the checkboxes with the keyboard will cause the tooltips to be shown.

Some areas need work.

• I'm having some trouble getting the tests working. I think part of the problem is tests that check for the text of a category title are getting thrown by the extra element in the label. I think a possible fix would be to move the category title into a span (so the label would contain two child spans, one for the title, and another for the description). That should make it easier to isolate the title element.
• It would be nice if the tooltip appeared after a short delay, so it didn't show when moving over quickly, just when hovering.
• Moving the mouse over the categories quickly can result in more than one tooltip showing.
• Moving the mouse quickly produces some unsightly flickering as descriptions appear and are hidden.

I also gave it a try, worked smoothly, and majorly the points mentioned in #21 in Some areas need work.are the major things(mostly usability).

We could also consider to show it by:

• Displaying an (i) icon against each category name and showing the tooltip on hovering that only
• Showing the tooltip the way we are currently trying to show but show it to the right side so that the options below and above the hover option are not hidden
  

Thanks!

We don't seem to be testing this via PHPUnit/nightwatch (which might be fine), but note that we we want to test descriptions/tooltips, we might need to alter the fixtures used (so the real API endpoint is not queried for testing):
- https://git.drupalcode.org/project/project_browser/-/blob/2.0.x/tests/fi...
- https://git.drupalcode.org/project/project_browser/-/blob/2.0.x/tests/fi...

Is this RTBC and @fjgarlin didn't mark it or does it still need work?

I’d say still “needs work” as there are actions/feedback not addressed yet.

The markup is changing in https://www.drupal.org/project/project_browser/issues/3485747 🐛 The multi-category filter needs to be an actual set of labeled checkboxes Active . This will likely need a rebase once that fix lands.

Leslie has just suggested something good here. Can we split the difference and simplify by adding a ? or [i] icon next to the category label, and it opens a modal with all the terms & descriptions? This way you still don't have to leave the site and it loads fast. We might be able to then later use a anchor/fragment to link directly to one term/description.

I think in general I would rather a user opt-in to getting the definition rather than it just showing up on hover or focus. As it stands now the description might cover the next term and the user didn't even need to know the definition.

I think trying to implement the simplest possible solution makes sense, otherwise the conversation is likely to drag on another 2½ years...

A modal popup activated by a "?" icon outside the category drop-down would have several big advantages:

• It avoids adding complication to the Category drop-down JavaScript, which is already quite involved
• It keeps the user on the page, rather than diverting them to an external page, avoiding load time and having to use the back button to return
• It should be quick to implement

Perhaps a more complex solution could be considered later, but at least this approach should get a basic solution merged quickly.

Agree with you James. Would be great if this could be completed this week.

lostcarpark → changed the visibility of the branch 3293907-provide-brief-summaries to hidden.

Resurrecting this issue, I've created a new branch.

As discussed previously, I've added a button next to the category dropdown:

Pressing it shows a pop-up with the category descriptions:

To do:

• 3 tests in ProjectBrowserUiTestJsonApi.php are failing. I'm struggling to figure out the cause, as they are passing locally.
• Currently the header of the pop-up is not translatable. I meant to fix that before pushing, but forgot.
• There probably should be some explanatory text before the descriptions.
• At the moment the button just has a "?" for the label. There should probably be an aria label for it. I'm not sure if there's a way to tell screen readers not to read the question mark, as it's not very helpful.

Could it be because the categories fixture does not have the descriptions?

The fixture is here: https://git.drupalcode.org/issue/project_browser-3293907/-/blob/3293907-...
You probably need to adapt the query here: https://git.drupalcode.org/issue/project_browser-3293907/-/blob/3293907-...
And then regenerate the fixtures.

At the moment the button just has a "?" for the label

Why not an information icon like https://git.drupalcode.org/project/drupal/-/blob/11.x/core/misc/icons/00...?

We should re-target this against 2.0.x and refactor it.

Here's the main problem: not all sources even support categories anymore. Categories are just considered a "multiple-choice filter", and those are handled generically.

Here's how I'd approach this: let's allow any filter to harbor a description by adding such a field to FilterBase::__construct(). Those descriptions will automatically be sent to the frontend. The front end can then decide how to display those filter descriptions. Maybe they are tooltips if they are under a certain length; maybe they pop into a modal if they're very long (it's up to the front end to decide).

That would give the backend the ability to send category descriptions, and it would give the frontend a clean way to display them without needing to be coupled to any assumptions about what filters there are.

But either way, we should abandon the 1.0.x version of this.

@phenaproxima I branched off the current 2.0.x, so I think the current code is good. I made mave missed a step because it's an old fork.

Marking needs review for @chrisfromredfin. I know there's still more work needed, but I would like some feedback on what's been done.

Currently the help button is added to all multiselect drop-downs. Would be nice to make it only shown if the filter has help text. And maybe make it more general, so any filter can offer help text.

Also needs some tidying up to make the tests work again, but would be helpful to get some feedback on whether this takes it in the right direction.

I SWORE I already provided feedback on this, but it's not here - might have been one of those ones that I started in an open tab, then closed the tab.

There's a few more major things here, and it might be that this branches out into an issue that needs to be worked on before this one:

1. As Adam says, we need to basically allow a "description" more generically. That's the first piece. FilterBase should support a description field (which accepts markup?).

2. If a description is set, then we should set a ? icon, I think, next to the label (not next to the select). I would use core's questionmark-disc icon (although I'm not sure if we can always count on that being there, but might make sense to try anyway - even if it's not guaranteed).

3. As we're doing now, I think it's OK to then open that description markup in a popup/modal.

4. I'm not sure where we're actually getting the names/descriptions from, but I think we'd want to actually have this queried from Drupal.org; not sure if that means it needs its own endpoint? I'm happy to do that part later, and rely on something like the test fixture (for now), but I don't love that as a long-term solution. (Also, happy to cache that for like an hour or even longer if needed, to help reduce requests to d.o)

As Adam says, we need to basically allow a "description" more generically. That's the first piece. FilterBase should support a description field (which accepts markup?).

Yup, let's add a new string|\Stringable|null $description = NULL parameter to FilterBase::__construct(). There's no reason it couldn't take markup.

This would be an API addition, not an API break, and therefore this issue is not a beta blocker.