WMDE Technical Wishes/Suggested values for template parameters

Suggested values for template parameters
Status	Deployed to all wikis
Focus area	Templates
Phabricator	T273857
Responsible	Technical Wishes Team

This page documents the development progress of and discussions about the project Suggested values for template parameters from the focus area "Make working with templates easier". You can find general information about the focus area and how we chose the projects that are being implemented on this page.

We welcome comments and questions about this project on the discussion page.

Description

When filling in parameter values in templates in Visual Editor it is often not obvious at first glance which values are expected for a certain parameter. In some cases only certain values are even accepted by the template, but the user cannot necessarily see what those values are. For example, if a user edits an article about a novel and wants to specify the genre in the parameter "genre" in the infobox, they might ask themselves whether to enter crime, thriller or perhaps mystery?

With the new parameter property suggestedvalues, anyone who creates or maintains templates can now define a list of suggested values for a parameter. These values will then be displayed to VisualEditor users in a dropdown menu. If you use the template and want to enter a value for this parameter, you can then quickly select the appropriate value from the list. If you want to type in a value that is not in the list, e.g. Sci-Fi Crime in the example above, this option is still available. Because there are sometimes situations where an article needs a more customized value, it will be possible to fill in values other than the suggested ones.

This way, the user does not need to know the expected values and their required format in advance. It is no longer necessary to figure out what values go in each field by visiting the template documentation page or to even try to guess the expected values. This new feature is particularly helpful for those who are not yet familiar with a template.

This prevents potential errors, reduces the effort needed to fill the template with values and makes the formatting of the values more consistent. Together with the planned improvements in the template dialog, the suggested values feature makes the usage of templates in the VisualEditor easier.

How to use the new feature

A new parameter property, suggestedvalues lets you define a list of parameter values to be shown to VisualEditor users in a dropdown for easy selection. In order to use this feature, the suggested values must be added to the template’s TemplateData. This can be done either directly in JSON or using the TemplateData editor (no coding required). Both methods are explained in detail below.

TemplateData

You can add suggested values to be displayed in the VisualEditor for parameters which have their type set to one of the following options:

• content
• line
• string
• number
• unknown
• unbalanced wikitext.

Other types (file, page, template, user, date, boolean, URL) are not currently supported because they have special functionalities in the VisualEditor already, such as autocomplete, which would interfere with the drop-down menu for suggested values in the VisualEditor.

Editing TemplateData as JSON in Wikitext

To add suggested values to any parameter type, add the new property “suggestedvalues” to the parameter in JSON. The “suggestedvalues” attribute must be a list of strings.

An example might look like this:

"media_type": {
    "label": "Type of media",
    "example": "Newspaper",
    "type": "string",
    "description": "In what medium was the article published?",
    "suggestedvalues": [
        "Journal",
        "Book",
        "Newspaper",
        "Magazine"
    ]
}

Example of how to add suggested values in TemplateData editor

Editing TemplateData with the TemplateData Editor

For the parameter types listed above, you can add suggested values using the TemplateData editor.

Step 1. Click on "Manage TemplateData".

Step 2. Click on the name of the parameter you want to add suggested values to.

Step 3. If it’s not already, set the type of the parameter to one of the following: content, line, string, number, unknown or unbalanced wikitext. A new input field "Suggested values" will appear. If the parameter is already set to one of these types, the input field should already be visible.

Step 4. Type in the suggested value(s), including any spaces and special characters, and press enter to add it to the list.

Example of filling in a template with suggested values feature in VisualEditor

Effect in VisualEditor

Once the values have been added to TemplateData, via JSON or the TemplateData editor, the VisualEditor will display them in a combo box (a dropdown into which users can also enter a custom value) for the parameter types listed above. The user selects the desired value by clicking on it. If the list of values is long -- for example, a list of a country’s states -- the user can begin typing in the field, whereupon the list will be filtered to show only values containing the typed text. To change an entered value, the user must simply clear the field, and the full dropdown list will appear again. If the user needs a value not included in the list (for example, "message in a bottle") they can type it in manually.

Status and next steps

• Deployed to all wikis on April 29, 2021.