Page MenuHomePhabricator

add "exclusive" attribute to parameters with suggested values
Open, Needs TriagePublic

Description

use case:
"suggested values" are primarily used with parameters that are fed into {{#switch "template condition".
in actual usage, "switch" can have 3 distinct behaviors when it's fed an unexpected value:

  • simply ignore it and behave as if no value at all was fed (no "default" clause)
  • use the unexpected value
  • generate an error (something like:
| #default = {{error|bla bla bla}}

IOW, a value outside the list is either expected or an error (first case is also an error: editors expect parameter values to have an effect).
templatedata should be able to indicate whether for this template and this parameter it's "kosher" to feed a value outside of "expected". again, this is useful for wizards and linting tools

Event Timeline

Izno renamed this task from requesting templatedata additional attributes for parameter field to add "exclusive" attribute to parameters with suggested values.Apr 20 2024, 7:01 PM
Izno updated the task description. (Show Details)
Izno subscribed.

T54582 asks a bit more,=, it asks for VE to behave in a certain way. this request is more modest: all i ask is to allow 2 more attributes.
there's strict validation code that doesn't let you save a page which contains invalid TD, and this request is to allow two more attributes, with suggested names.
it should be straightforward and short to implement, maybe even simpler than documenting it.

for instance, in hewiki we maintain both template-wizard for source-code editor, and parameter validation system ("lint" like), and both rely on templatedata to do their work, adding the requested attributes as legitimate will help both.

peace.

i am asking for minimal change, in TD validation only.
the other stories may be viewed as asking for some behavior change (mainly VE support), all i'm asking here is to allow two specific "parameter" attributes in TD validation.
code (and doc) changes should be minimal.
unfortunately i am not able to submit pull request myself, but i imagine such change should not be more than a dozen or so lines of code (most of which as comments)

hopefully this request has slightly higher chance of being granted than the older stories. trying to be practical here.

peace

Unfortunately not, sorry. At the moment the ticket explains neither a solution nor a problem. What is the user story? How should the new syntax look like? How should it be presented and explained in the interactive TemplateData editor? How should it be documented? How should consumers like VisualEditor, the MediaWiki-extensions-TemplateWizard, Citoid, or the ContentTranslation workflow behave? Should this really block the user's edit from being saved? How would this look like in the UI? What does the error message say? What if the template already contains an unknown value that wasn't entered by the current user? Should we still block the user from continuing what they wanted to do? Why? How do we explain it to the user? How do we help the user to get unstuck? How do we measure the success rate to make sure the change was worth it and we don't loose meaningful edits due to users getting frustrated and giving up?

This is very similar to what I said in T197634#9712254 just a few days ago: I think what we are discussing here is called "programming" and requires an actual programming language. Which we have: Lua. It's the job of the template to decide if it wants to accept unlisted values, ignore them, or trigger an error. Why would we need to duplicate this logic in a different place in an entirely different format?

Unfortunately not, sorry. At the moment the ticket explains neither a solution nor a problem. What is the user story? How should the new syntax look like? How should it be presented and explained in the interactive TemplateData editor? How should it be documented? How should consumers like VisualEditor, the MediaWiki-extensions-TemplateWizard, Citoid, or the ContentTranslation workflow behave? Should this really block the user's edit from being saved? How would this look like in the UI? What does the error message say? What if the template already contains an unknown value that wasn't entered by the current user? Should we still block the user from continuing what they wanted to do? Why? How do we explain it to the user? How do we help the user to get unstuck? How do we measure the success rate to make sure the change was worth it and we don't loose meaningful edits due to users getting frustrated and giving up?

This is very similar to what I said in T197634#9712254 just a few days ago: I think what we are discussing here is called "programming" and requires an actual programming language. Which we have: Lua. It's the job of the template to decide if it wants to accept unlisted values, ignore them, or trigger an error. Why would we need to duplicate this logic in a different place an entirely different format?

unfortunately, sone of the answers to short questions and comments are not so short themselves. sorry.

What is the user story?

user 1 story:
(let me introduce myself first): I am a template-parameter validator used on hewiki, flagging common errors such as missing a "required" parameter, passing a parameter not recognized by the template, passing non-numerical value to parameter defined as numerical, and 5 or 6 other errors. I use maintenance categories, and operate on all the common parametric templates used in article space on hewiki, (a bit over 1,500 templates, some used on tens of thousands of articles).
there are a few wikimedians who are routinely scanning the maintenance cats correcting the templates, thus recovering essential content to articles (e.g., when an editor misspells parameter name but adds meaningful param value)
I use templatedata as the basis for validation.

As a template-parameter-linter i need to know if template parameter which has "suggested values" defined and its current value is not one of the suggested value represents an error.
if you'd like to meet me, i live here: https://he.wikipedia.org/wiki/Module:ParamValidator

user 2 story:
(let me introduce myself first): i am a template-wizard for source code editor, active on hewiki. i am roughly 13 years old and predate visual editor or mw "param wizard" for source editor.
unfortunately, i cannot retire, since mw "param wizard" for source code is a useless cripple, incapable of handling the common case of editing an existing partially filled template.
when i was born, templatedata was not yet introduced, and i used my own form of template metadata, which included "suggested values" (and "exclusive" flag).
after templatedata was introduced, i switched to using it, so only a single instance of metadata representing the template need to exist, rather than maintaining multiple versions in incompatible formats.

As a template parameter wizard, i need to know whether or not to allow value outside the list for parameters sporting "suggested values", e.g., i want to decide whether to use a listbox control or a combobox control, as well as deciding whether or not to highlight this parameter as "in error" (i do this for parameters not appearing in TD, missing "required" param etc.).
if you'd like to meet me, look here: https://he.wikipedia.org/wiki/Mediawiki:Gadget-TemplateParamWizard.js

user 3 story:
(let me introduce myself first): i am mediawiki visual editor. when the new flag will be introduced, i'll do with it whatever the @#$%% i want.

How should the new syntax look like?

example:

"params": {
		"param name": {
			"suggestedvalues": ["val1", "val2", "val3"],
                        "exclusive": true
                }
}

alternative implementation:

"params": {
                "param1 name": { 
                         "type": "string"
                 }, 
		"param2 name": {
                         "type": "exclusive list",
			"suggestedvalues": ["val1", "val2", "val3"],
                }
}
How should it be presented and explained in the interactive TemplateData editor?

for implementation #2, just add "exclusive list" to the available types. for option #1, add a new checkbox called "exclusive"
bonus points: only expose the "exclusive" checkbox when "suggested values" field is not empty.

How should it be documented?

by writing appropriate documentation.

How should consumers like VisualEditor, the MediaWiki-extensions-TemplateWizard, Citoid, or the ContentTranslation workflow behave?

above my pay grade. i explained how consumers such as hewiki param wizard and hewiki param validator will behave. any other consumer should decide whether to ignore this flag or use it any way it sees fit.

Should this really block the user's edit from being saved?

stupid question. we do not block saving edits with missing required parameters, misnamed parameters, non-numerical values for parameters defined as numeric. we don't block saving for wrongly filled templates.

if you meant to ask whether the _template_ page should be prevented from being saved when TD contains "illegal" attribute, well, i don't know if it _should_ be prevented, but the fact is, it's prevented now.
you don't have to believe me: try to save a template with TD that tries to add "exclusive" flag.

image.png (64×963 px, 3 KB)

more questions

quoting: "How would this look like in the UI? What does the error message say? What if the template already contains an unknown value that wasn't entered by the current user? Should we still block the user from continuing what they wanted to do? Why? How do we explain it to the user? How do we help the user to get unstuck? How do we measure the success rate to make sure the change was worth it and we don't loose meaningful edits due to users getting frustrated and giving up?"

forgive my french, all of those are stupid questions, and look as if they were not asked in good faith, but rather argumentatively, as poor excuses to say "no".
these questions have nothing to do wht the request, and nothing to do with TD. they deal with the desired behavior of various TD consumers.
despite the inappropriate questions, i'll answer in a nutshell: each consumer should do exactly what the do today when encountering a param whose type defined "numeric" and value is non-numeric. no more, no less.

It's the job of the template to decide if it wants to accept unlisted values, ignore them, or trigger an error.

ha? can you repeat that? what is the role of "templatedata" then?
or, expanding on your question, isn't it also the job of the template to decide whether a certain parameter is "required"? or another param should be numeric? why does TD have to repeat it? why does TD have to exist at all? let the template decide, let the template tell VE how to set up the UI, and let the template find and report any errors.

mediawiki templates' syntax is a miserable mess, and templates are ill-equipped to do even their given job, let alone report errors.
when encountering an error, all a template can do is either emit an error message into the article, exposing it to the readers, or add some tracking category.
both of those are bad/unacceptable. i hope i don't need to tell you why the former is unacceptable. as to the latter, it is a poor support when some template appears 15 times in one article and the category says "pages with bad value in template X". with our linter, we have much better than this, with clear error message, that points not only to the offending page and marks the _specific_ offending template(s) in it, but actually to the specific parameter(s) and error(s): "missing required param X, using deprecated param Y, unknown param Z, Q is an alias of param W and both are given different values" and so on)

currently, in light of mw devs refusal to listen, we treat all "suggested values" as exclusive, which gives us pain when it's not exclusive.
we can live with it, but you guys should do better.

peace.