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.

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.

In T271897#6900028, @ECohen_WMDE wrote:

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

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.

@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).

In T271897#6975971, @thiemowmde wrote:

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.

Here's the matrix for (7):

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

Change 670461 merged by jenkins-bot:

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

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