Page MenuHomePhabricator

Add parameter search to sidebar of VE TemplateDialog
Closed, ResolvedPublic13 Estimated Story Points

Description

Background:
As a part of making working with templates in Visual Editor easier, we will change the way in which parameters can be discovered, added and removed from a template invocation.

Requirements

  • Implement behind a feature flag with:
  • Add a search field beneath the template name, when the template has parameters using OOUI SearchInputWidget (type=search). Placeholder text: "Find field"
  • Hide search field for templates without parameters.
  • Wire any content changes to update our search index.
  • When search term is entered, filter parameters within that template and show results using the same criteria in the current search (under Add more information dropdown). Show results essentially means to hide all non-relevant parameters from the sidebar. Note: current search on test instance is not displaying correct results, including when the exact label of parameter is typed. Needs de-bugging.
  • Filter applies only to the parameter list in the sidebar, not to the template content on the right-hand side (all currently selected parameters should remain visible, not just those included after the filter).
  • If no matching parameters are found, display text: "No matches found."
  • When multiple templates/content exists, filter only within a single template. Do not hide the other templates/content.

Mocks

Screen Shot 2021-01-26 at 14.32.29.png (250×249 px, 12 KB)
Screen Shot 2021-02-17 at 14.27.01.png (415×713 px, 26 KB)
Screen Shot 2021-02-17 at 14.33.09.png (616×386 px, 35 KB)
Screen Shot 2021-02-17 at 14.32.03.png (398×647 px, 27 KB)

Related tickets:

Related Objects

StatusSubtypeAssignedTask
OpenNone
ResolvedWMDE-Fisch
ResolvedWMDE-Fisch
ResolvedAndrew-WMDE
ResolvedWMDE-Fisch
ResolvedAndrew-WMDE
ResolvedBUG REPORTawight
OpenNone
OpenNone
ResolvedWMDE-Fisch
Resolvedawight
DeclinedNone
ResolvedNone
InvalidNone
Resolvedthiemowmde
Resolvedlilients_WMDE
InvalidNone
Resolvedthiemowmde
ResolvedAndrew-WMDE
ResolvedAndrew-WMDE
ResolvedNone
ResolvedNone
Resolvedthiemowmde
ResolvedAndrew-WMDE
ResolvedWMDE-Fisch
ResolvedLena_WMDE
ResolvedNone
Resolvedawight
ResolvedAndrew-WMDE
InvalidNone
Resolvedthiemowmde
ResolvedBUG REPORTWMDE-Fisch
ResolvedBUG REPORTthiemowmde
ResolvedBUG REPORTthiemowmde
ResolvedWMDE-Fisch
OpenBUG REPORTNone
ResolvedECohen_WMDE
OpenNone

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
Lena_WMDE renamed this task from DRAFT: Add parameter search to sidebar of VE TemplateDialog to Add parameter search to sidebar of VE TemplateDialog.May 14 2021, 7:46 AM

Change 700599 had a related patch set uploaded (by Awight; author: Awight):

[mediawiki/extensions/VisualEditor@master] [WIP] Parameter search widget

https://gerrit.wikimedia.org/r/700599

Note: current search on test instance is not displaying correct results, including when the exact label of parameter is typed. Needs de-bugging.

As described in this ticket, the search in the add more information element seems strange. The reason for this is actually that the search also looks into the descriptions of parameters. This leads to strange results at the first glance (especially because they are blocking adding parameters when there is a description match as well - see also T285940).

But in general (and especially in combination with a more relaxed adding mechanism) the search in parameter descriptions might be a wanted feature that we will lose with our new approach. Because we have no space to display the descriptions in the sidebar. I guess we should reflect about this, because this way the requirement from the ticket will be hard to meet:

When search term is entered, filter parameters within that template and show results using the same criteria in the current search (under Add more information dropdown)

Change 704128 had a related patch set uploaded (by Svantje Lilienthal; author: Svantje Lilienthal):

[mediawiki/extensions/VisualEditor@master] [WIP] Add parameter search to sidebar of VE TemplateDialog

https://gerrit.wikimedia.org/r/704128

Change 704498 had a related patch set uploaded (by Thiemo Kreuz (WMDE); author: Thiemo Kreuz (WMDE)):

[mediawiki/extensions/VisualEditor@master] [WIP] Tweaks and cleanups to template parameter search

https://gerrit.wikimedia.org/r/704498

During the Story time session, on July 14th (see notes), we discussed a couple of topics related to this task:

  1. Should the search field be hidden for < x params?

The specification indicates that the search field should be displayed in all circumstances where parameters are shown, but if the number of available parameters is too small, then the search/filtering capability is not so useful. Should the search input be hidden unless a certain number of parameters are present in the sidebar?
Decision: Although this is a very fair point, we decided to stick to current ticket description for now.

  1. The specification is to “Show results using the same criteria in the current search”, is it ok then to search/filter parameters based on their aliases and descriptions, even if they are not displayed anymore? (See comment above)

We decided again to stick to the current ticket specifications, and perform the search also on the parameters' aliases and descriptions. The assumption is that this might increase their findability (users might not know the exact name of the parameter and thus this might be useful – we wondered if @Lena_WMDE could be aware of any user feedback supporting this theory). But this also means that, in certain cases, the label of the parameters displayed in the results won't match the search input.
We still should prevent the behavior described in the note (see task description) and make sure that the right parameter is retrieved in case that characters matching the label of the parameter exactly are entered in the sidebar search.

users might not know the exact name of the parameter and thus this might be useful […]

Some additional notes:

  • Some users actively work with aliases (a.k.a. "alternative" or "secondary parameter names"). Typing an alias should find the parameter. However, it's true that we currently don't show the alias anywhere.
  • What we show in the list of checkboxes is not the parameter name, but it's label. These typically use the same words, but not necessarily. The parameter name is only shown when there is no label. When we follow the (possible) argument that we should only search visible fields, we still need to search parameter name and label.

Following these arguments the remaining disputable bit is the parameter's description. The description will be shown on the right side (easily visible, not hidden behind an icon any more) the moment the checkbox is checked.

Possible solutions:

  • Show parameter name and aliases somewhere in the right content pane, next to the description.
  • Temporarily replace the visible label in the sidebar on the left with the matching alias or parameter name. This avoids the confusing situation that a label is shown that doesn't even contain the search term. Possibly reset back to the label when the filter is cleared – or not, as this can cause confusion as well.
  • Show an extra snippet under the label as long as a filter is active. Unfortunately this creates a series of new problems:
    • What to show? This is especially a problem when a description is very long. Coming up with a good algorithm for this is not easy.
    • Every time these snippets are dynamically shown/hidden there are significant jumps in the layout, as the height of the affected items changes.

The description will be shown on the right side (easily visible, not hidden behind an icon any more) the moment the checkbox is checked.

Exactly, that is one of the reasons supporting the decision to follow the current search functionality specs, sorry for not making it explicit after all.

Show parameter name and aliases somewhere in the right content pane, next to the description.

Making the "missing" information available on the right-hand panel is a reasonable option to consider, as I agree it could help users validate their result selection. For now, though, there seems to be a strong letter by letter correlation between the name, the label and what I interpreted to be the alias of the parameters in all the examples I tried out (which are not many): do you think that displaying any of those pieces of information (or all of them) would help with the disambiguation of search results?

do you think that displaying any of those pieces of information (or all of them) would help with the disambiguation of search results?

I'm just listing options. 😄 Personally I would not display aliases on the right-hand side. It significantly increases the amount of noise on the screen, but is rarely helpful. A significant amount of aliases are just capitalization permutations, abbreviations, or numbers. Examples:

  • When you type "OT", "original title" or "original_title" but find "Original title" it should be rather obvious what's going on.
  • A user who types "1" probably knows what the meaning of the first parameter is. Finding that parameter by name should not be a surprise.

Change 704128 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Add parameter search to sidebar of VE TemplateDialog

https://gerrit.wikimedia.org/r/704128

When search term is entered, filter parameters within that template and show results using the same criteria in the current search (under Add more information dropdown). Show results essentially means to hide all non-relevant parameters from the sidebar.

Currently the Add more information dropdown also takes into account things written in the description of a parameter. It's kind of transparent there because you see a description preview for each parameter. In the sidebar you do not see the description. So it could be quite unexpected if you type a word there and see parameters that do not obviously include that word.

So I'm not sure if we should have a different behavior in the sidebar then. Can be discussed in the demo of this part. Not super urgent @ECohen_WMDE @Sarai-WMDE

Hey, @WMDE-Fisch. We had this exact discussion during this week's storytime (see comments above). The decision was to tentatively (@ECohen_WMDE or @Lena_WMDE might have a different opinion here) follow the original specification and take into account the parameter description, since this might help findability (users might not remember exactly the label of the parameter) and, after all, the description would still be available in the main section if the parameter is selected.

Change 704498 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Tweaks and cleanups to template parameter search

https://gerrit.wikimedia.org/r/704498

question for @WMDE-Fisch, though: label matches will still be displayed at the top, right? (I'd say that's the current behavior of the Add more information field, but I'm not 100% sure)

Hey, @WMDE-Fisch. We had this exact discussion during this week's storytime (see comments above). The decision was to tentatively (@ECohen_WMDE or @Lena_WMDE might have a different opinion here) follow the original specification and take into account the parameter description, since this might help findability (users might not remember exactly the label of the parameter) and, after all, the description would still be available in the main section if the parameter is selected.

Thanks for the clarification. I guess I was still not up to date with what was discussed there. Sorry ^^'

question for @WMDE-Fisch, though: label matches will still be displayed at the top, right? (I'd say that's the current behavior of the Add more information field, but I'm not 100% sure)

The current behavior is to not rank "name"-results higher than "description"-results. Also not in the "Add more information" field. But it might make sense and if we want that we could add it to both. Would need a new ticket though.

WMDE-Fisch moved this task from Demo to Sprint Backlog on the WMDE-TechWish-Sprint-2021-07-07 board.

Devs: Layout needs to be adjusted to mock.

Change 704965 had a related patch set uploaded (by Svantje Lilienthal; author: Svantje Lilienthal):

[mediawiki/extensions/VisualEditor@master] fix order of sidebar elements

https://gerrit.wikimedia.org/r/704965

Change 704965 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] fix order of sidebar elements

https://gerrit.wikimedia.org/r/704965

The current behavior is to not rank "name"-results higher than "description"-results.

The order of the search results was always the original order of the parameters. In other words, there was never a ranking that could understand if one search result is better than the other. While it might be possible to change this for the existing parameter search widget on the right, it doesn't make sense for our filter on the left, in my opinion. I would find it confusing if the order of parameters suddenly changes on the left, and doesn't match the order on the right any more.

@Sarai-WMDE, I run into another edge-case. When I edit a template that doesn't have parameters, the filter input isn't shown (as specified). However, I can still add parameters to this template. This should be rare in the wild, but is possible. At the moment this doesn't make the filter input appear. Should it?

The same thing can happen the other way around – but that's even more unlikely to happen in the wild. When I edit a template that doesn't have any documented parameters, I can delete all of them. Should the filter input disappear then?

I think it's possible to argue for both behaviors. Personally, I tend towards dynamically displaying/hiding the filter.

Change 704993 had a related patch set uploaded (by Andrew-WMDE; author: Andrew-WMDE):

[mediawiki/extensions/VisualEditor@master] Adjust the styling for the template parameter search

https://gerrit.wikimedia.org/r/704993

Change 704993 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Adjust the styling for the template parameter search

https://gerrit.wikimedia.org/r/704993

Change 705648 had a related patch set uploaded (by Andrew-WMDE; author: Andrew-WMDE):

[mediawiki/extensions/VisualEditor@master] Dynamically set the visibility of the sidebar search

https://gerrit.wikimedia.org/r/705648

Hey, @thiemowmde. Thanks for bringing all those edge cases 😄

I would find it confusing if the order of parameters suddenly changes on the left, and doesn't match the order on the right any more.

I'm not sure if this would be confusing. After all, while performing the filtering search, users are focused on the task of getting a certain result for their input. The original order of the parameters and their correspondence with the right-hand form are not relevant anymore for the task they're trying to accomplish. While getting meaningful matches is the expected behavior. I suggest we discuss this further in today's story time meeting, if that makes sense.

When I edit a template that doesn't have parameters, the filter input isn't shown (as specified). However, I can still add parameters to this template. This should be rare in the wild, but is possible. At the moment this doesn't make the filter input appear. Should it?

I'd say so, yes, as this matches the specification. The next time that template is opened in the editor, the search should be available if parameters are generated.

When I edit a template that doesn't have any documented parameters, I can delete all of them. Should the filter input disappear then?

If you are referring to deleting the parameters in the template documentation, then yes, the search wouldn't be displayed whenever said template is edited using the VE.
If you're referring to deleting/deselecting the parameters from the VE, then the search would only disappear when changes are saved/the edit session ends. As the parameters would still be visible (and available to be selected again) until then.

Personally, I tend towards dynamically displaying/hiding the filter.

I believe that the dynamic approach matches what's suggested in the designs :)

Change 705648 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Dynamically set the visibility of the sidebar search

https://gerrit.wikimedia.org/r/705648

Change 700599 abandoned by Thiemo Kreuz (WMDE):

[mediawiki/extensions/VisualEditor@master] [WIP] Parameter search widget

Reason:

This patch looks very incomplete. I believe we don't lose anything if we close it. The ticket is already done via other patches.

https://gerrit.wikimedia.org/r/700599

Change 711261 had a related patch set uploaded (by Thiemo Kreuz (WMDE); author: Thiemo Kreuz (WMDE)):

[mediawiki/extensions/VisualEditor@master] Minimize template dialog CSS a bit

https://gerrit.wikimedia.org/r/711261

Change 711261 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Minimize template dialog CSS a bit

https://gerrit.wikimedia.org/r/711261