Page MenuHomePhabricator

Add suggested values parameter property to TemplateData and to TemplateData editor
Closed, ResolvedPublic3 Estimated Story Points

Description

Requirements

  • Support a new parameter property for TemplateData, called suggestedvalues in JSON.
  • Property is returned from API
  • Implement the UI behind a feature flag
    • Add field to edit this new property in the TemplateData editor on the parameter properties page underneath the type property.
    • Give this field a label of: "Suggested values"
    • Only have this property visible when the following parameter types are selected: Content, Line, String, Unknown, Number, Unbalanced wikitext. Otherwise, hide suggested values and its field.
    • For input, use OOUI TagMultiselectWidget (allowArbitrary, inline input, placeholder). The items can then also include commas.
    • Placeholder text: "Add value..."
  • When rendering the embedded TemplateData table in an article, display the suggested values under a bold heading beneath the description, as is done for default and example.

Mock

Relevant prototype commits:

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 suggested values parameter property to TemplateData and to TemplateData editor to Add suggested values parameter property to TemplateData and to TemplateData editor.Jan 27 2021, 2:13 PM
Lena_WMDE updated the task description. (Show Details)
Lena_WMDE set the point value for this task to 8.Jan 27 2021, 2:22 PM

on test instance this was titled datalist.

Note: It was "datalist" because this is the name the exact same feature does have in HTML, see https://html.spec.whatwg.org/#the-datalist-element. Not meant to push for anything, just to document this decision.

  • It's unlikely anyone knows the HTML feature. Even web developers typically don't know it's called "datalist", even if they know the feature.
  • A "list of data" is a bad name anyway.
  • Even the spec explains it as a list of "predefined options suggested to the user", see https://html.spec.whatwg.org/#the-list-attribute.

Thanks for the extra detail @thiemowmde. Glad to know why, but would still call it suggested values for consistency.

Andrew-WMDE moved this task from Doing to Sprint Backlog on the WMDE-TechWish-Sprint-2021-03-03 board.
Andrew-WMDE added a subscriber: Andrew-WMDE.

I tried including "(comma separated)" guidance after the field name, but it breaks the line. Shall I leave that out?

How should we render the property in the TemplateData "view" mode? I suggest we do the same as for Default, Autovalue, etc. ? Mock:

I tried including "(comma separated)" guidance after the field name, but it breaks the line. Shall I leave that out?

Yes, the title can just be "Suggested values." A description will be added later when the layout is adjusted with labels above fields, explaining how it works. For now though, the title alone is fine.

Also note, the requirements changed so that we would like to use OOUI TagMultiselectWidget. This means that the values also no longer need to be comma separated.

How should we render the property in the TemplateData "view" mode? I suggest we do the same as for Default, Autovalue, etc. ?

I agree, I think it makes sense to display them in this way. I think this is what we chose on the test instance as well and it seemed to work.

I tried including "(comma separated)" guidance after the field name, but it breaks the line. Shall I leave that out?

Yes, the title can just be "Suggested values." A description will be added later when the layout is adjusted with labels above fields, explaining how it works. For now though, the title alone is fine.

Also note, the requirements changed so that we would like to use OOUI TagMultiselectWidget. This means that the values also no longer need to be comma separated.

Thank you, I was slowly coming around to the same realization :-). Great idea to use a tag widget!

Change 670461 had a related patch set uploaded (by Awight; owner: Awight):
[mediawiki/extensions/TemplateData@master] [WIP] Add suggested values parameter

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

I tried including "(comma separated)" guidance after the field name, but it breaks the line.

That's fine. These labels will have different amounts of text anyway, depending on the localization.

How should we render the property in the TemplateData "view" mode?

I linked all relevant commits from the prototyping phase in the task description. Please refer to these. For this specific question: Render it as you said, as a comma-separated list.

These labels will have different amounts of text anyway, depending on the localization.

Good point. But once the full design is implemented and the labels are over the fields instead of beside them, this will also be less of an issue

awight changed the point value for this task from 8 to 3.Wed, Mar 31, 8:27 AM

Just some notes about what's missing from the patch here:

  • Needs to use a TagMultiselectWidget
  • Needs placeholder text
  • When the feature is disabled, do not emit suggested values from the API. That lets us use the TemplateData feature flag as a global kill switch for the feature in VisualEditor and TemplateWizard.
  • Debatable: when the feature is disabled, maybe we should continue to document suggested values in the template doc HTML, since this is harmless, and the HTML is cached so suppressing output will cause a confusing state once we reenable the feature flag.
WMDE-Fisch added a subscriber: WMDE-Fisch.

@Lena_WMDE @ECohen_WMDE Two questions:

  • Should we continue to render suggested values hints in the HTML TemplateData rendering on Template:<title>/doc? I've decided to do so, for the moment, mostly because page caching is tricky and we can't reliably make the text appear or disappear based on the value of our feature flag, so I think that always showing is a reasonable compromise.
  • Please review this text which will be added to developer-facing Specification.md:

3.2.11 suggestedvalues

  • Value: Array
  • Default: []

A list of commonly used, suggested values.

Authors MUST give suggested values which match the field type.

Consumers SHOULD provide this list to the user when filling out the field, but MAY implement suggested values only for some field types.

Consumers MUST allow the user to enter free-form values not on this list.

"Authors" are people editing templatedata. "Consumers" are programs like VisualEditor and TemplateWizard. (This is from a received lexicon.)

I added the "MAY" clause to cover the current state, and to frame any future migration incompatibilities as non-breaking, incremental implementation.

Not writing UI tests, because only browser tests would reveal anything useful, and there are no browser tests in this repo, yet.

Authors MUST give suggested values which match the field type.

This sentence feels like it can have 3 different meanings:

  • Is the field "suggestedvalues" required to exist? I don't think it should.
  • Is the field required to contain at least 1 value? Or is it allowed to be empty?
  • Must the values be valid, according to the field type? I don't think we will ever validate this. Therefor I think this should not be a requirement. Or at least rephrased to be a SHOULD. For example, it's impossible to say if a suggested page name is valid (i.e. exists).

Authors MUST give suggested values which match the field type.

This sentence feels like it can have 3 different meanings:

  • Is the field "suggestedvalues" required to exist? I don't think it should.
  • Is the field required to contain at least 1 value? Or is it allowed to be empty?
  • Must the values be valid, according to the field type? I don't think we will ever validate this. Therefor I think this should not be a requirement. Or at least rephrased to be a SHOULD. For example, it's impossible to say if a suggested page name is valid (i.e. exists).

Thanks, I'll remove this line. It's not really our business what users put in as suggested values, nor are we equipped to properly validate since there might be wikitext that won't expand correctly until other Templates are adjusted, and so on.

We realized that "behind a feature flag" can have a surprising large number of meanings:

  1. It could mean that no UI element in VisualEditor ever shows suggested values, even if they are there.
  2. … it could mean the above, plus the TemplateData wizard's UI doesn't allow to add suggested values to a field, except the field already has suggested values.
  3. … it could mean all of the above, plus the TemplateData wizard's UI never shows the UI element, even if there are already suggested values.
  4. … it could mean all of the above, plus the HTML table rendered on the template page doesn't show suggested values, even if they are there.
  5. … it could mean all of the above, plus the TemplateData API never returns suggested values, even if they are there.
  6. … it could mean all of the above, plus when there is a "suggestedvalues" field in the JSON, it is silently discarded.
  7. … it could mean all of the above, plus the template can't be saved when there is a "suggestedvalues" field.

The feature flag can be added on any of these levels (even on multiple levels). We think two of them make the most sense:

5. Disabled at the API level

For this approach, we need the following decision: We are going to add "suggestedvalues" as a new field to the JSON. It can manually be added to the JSON. This can be done immediately (after the next train), on all wikis. It will not be hidden behind a feature flag. But we don't give any guarantee about what it does. No guarantee about any behavior in VE or the wizard, not even guaranteed to be rendered in the HTML table. All the new field is guaranteed to do is documentation, nothing else.

Because of this we don't even announce this. We announce only the full deployment on the wikis that support everything.

There is not much of a rollback plan necessary for this approach. That's it's main benefit. There is no risk of invalidating anything. We are free to remove the feature from all UIs. But it will forever be in the JSON.

7. Disabled on all levels

Wikis that don't have the feature enabled can't even manually enter suggested values in the JSON. They can't use the feature on any level, not even for pure documentation.

The main benefit here is that we can easily revert the feature on the majority of wikis. There is nothing that can break on these wikis. However, such a revert will break the early adopter wikis that had the feature enabled before. We would need to migrate these wikis. There are multiple ways to do this:

  • We could turn these wikis (but only these wikis) in a mode as described above (continue to allow the field, but it doesn't do anything any more).
  • We could leave a small piece of code behind that silently discards the now unsupported field (see 6. above).
  • We could block users from adding new suggested values, run a bot to remove them all, and then remove all code related to suggested values.

We don't need to discuss the migration now. This is just to illustrate that this approach doesn't run us into unsolvable problems. My questions are: Which approach is more convenient for us? How certain are we that this feature is going to stay?

This is a nice framing of the question, thank you. I don't have much to add, other than to qualify the word "forever" in our description of option (5). None of these options is relevant beyond the medium-term possible enabling and disabling of the extension. If we decide to kill the feature and remove it from wikis in the future, this involves a different set of considerations and more migration edge cases than are described here. Option (5) is compatible with eventually removing suggestedvalues from JSON.

As I see it, the only differences between (5) and (7) are whether we allow premature usages, and whether we "break" existing usages of suggestedvalues. Here is the migration matrix for (5), rows are "old state" and columns are "new state". "Happy" means that nothing unexpected is happening.

old↴ new→Never deployedFeature enabledFeature disabled
Never deployedsuggestedvalues may be present but has no effect ◇/→Happy ↴n/a
Feature enabledn/aHappy ◇/→Existing usages remain valid but will have no effect ↴
Feature disabledn/aHappy ⤴suggestedvalues may be present but has no effect ◇/←

Here's the matrix for (7):

old↴ new→Never deployedFeature enabledFeature disabled
Never deployedsuggestedvalues cannot be present ◇/→Happy ↴n/a
Feature enabledn/aHappy ◇/→Existing usages become invalid and the property must be removed before saving a page (hard validation) ↴
Feature disabledn/aHappy ⤴suggestedvalues cannot be present ◇/←

Implementation changes after team discussion:

  • Immediately allow suggestedvalues to be present on any TemplateData parameter, in JSON.
  • Render suggested values in the HTML documentation table whenever present.
  • Return these values in the API, regardless of the feature flag setting.
  • The feature flag will control TemplateData editor UI element visibility, so it's only possible to add suggested values with the UI when the flag is enabled. The flag causes no other behavior changes.
  • The UI will only allow suggested values for these parameter types: Content, Line, String, Unknown, Number, unbalanced wikitext
awight updated the task description. (Show Details)
awight updated the task description. (Show Details)
awight removed awight as the assignee of this task.Fri, Apr 9, 7:03 AM

Change 670461 merged by jenkins-bot:

[mediawiki/extensions/TemplateData@master] Add suggested values parameter

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