WMDE Technical Wishes/VisualEditor template dialog improvements

This page documents the development progress of and discussions about the project VisualEditor template dialog improvements from the focus area "Make working with templates easier". You can find general information about that area and how we chose the projects in that area on this page.

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

Planned improvements in a nutshellEdit

  • Better overview of available parameters
  • Make adding parameters easier, including search filters
  • Make important information more visible
  • Improved documentation
  • Larger dialog window with more spacing
  • Make adding files easier (cancelled)
VisualEditor template dialog improvements
Status In implementation; Release Notes
Focus area Templates
Phabricator T286992 T284203
Responsible Technical Wishes Team

Status and next stepsEdit

  • on German, Greek, Malay, Twi, French, Hungarian, Turkish, Hebrew, Finnish and Dagbani Wikipedia and on English Wikivoyage and Nauruan Wiktionary: planned for October 2021
  • Deployments on more wikis planned for later in 2021.

Current problemsEdit

Our research has identified several problems with the existing interface for editing templates in the VisualEditor. Among other things:

  • It’s hard to know what the template expects from you, in terms of both content and formatting. Currently, descriptions with essential instructions are hidden away in the info icon, leaving people guessing.
  • It’s unclear why the dialog looks the way it does. Why are there no descriptions? Why are the parameter names so confusing? Why are some fields present and some absent? The various configurations are poorly explained, and it’s unclear where to look for help or instructions. In particular, less experienced editors are often unaware that templates and TemplateData are community-generated content.
  • Templates can be complex and very large: some have over 100 parameters. Under the current design, getting an overview is difficult, as is understanding the template’s many options within the template and finding the parameters you need. It’s exceptionally difficult to add new parameters using the existing “add more information” dropdown if you want to add more than one or don’t know exactly what the options are.
  • In particular, it’s difficult to add images. You have to know about Wikimedia Commons and understand that, to add an image, you have to open Commons in a new tab, find an image there, and then copy the exact file name back to the VisualEditor dialog. You need to know exactly how to write the image name, and you get no feedback when you make a mistake.
  • Users often complained about the dialog’s small size, saying that it made their work more difficult because it felt like being forced to look through a tiny window. The current window size is insufficient for the complexity of the work and the amount of information it must contain.


Help users understand what information is needed and how to format it, so that:

  • Less experienced users can easily make small edits without accidentally breaking the template or page, and without needing to fully understand the complexities of templates.
  • Experienced but less technical users can perform more complex edits without needing to edit source code.
  • Experienced technical users will spend less time cleaning up.

Planned implementationEdit

Implementation for VisualEditor and new Wikitext modeEdit

The implementation focuses on the VisualEditor and the new wikitext mode, because research has shown that there are particularly many problems when using templates in the VisualEditor (summary). Because the new wikitext mode (beta feature) uses the same template dialog, the changes also take effect there.

We’re planning the following improvements to address existing problems:

Main dialogEdit

  • Making the information required by parameter fields more visible. We will move the parameter name, description and special messages such as examples (if defined in TemplateData), to a prominent location above the input field. Long texts will be collapsed. Required fields will be clearly marked by an asterisk next to the field label, making it easier to focus on the content. We'll more clearly indicate the data a template expects and how it should be formatted, thereby reducing the research, knowledge and cognitive load required to work with a template. Hopefully our improvements to the process of adding template content will also help keep mistakes and trial and error to a minimum.
  • Writing context-specific help messages for templates. Users will get an explanation of what they’re seeing that varies according to whether a template has TemplateData or not, whether  the parameters can be auto-generated, if the template is meant to work without parameters and if there is multi-part content. Each variation will also provide a link to the right place for users to look for help, including the template’s own page and its documentation.
  • Removing the [[ ]] button. Tests have shown that most users don’t understand the function of the [[ ]] button. In addition, the functionality is no longer necessary in the first place; parameter fields already accept wikitext. Removing the button will reduce confusion and improve accessibility, making it easier to tab through fields quickly.
  • Changing the visibility of adding undocumented parameters. We will retain this existing feature but only show it when it’s needed. In usability testing, we found that inexperienced users were confused by the ability to add a parameter and thought they were changing the template itself. As a result, we are updating the name of the component and adding clear instructions about when it’s needed. The component for adding undocumented parameters will appear if the template lacks documentation (TemplateData) and in cases where parameters cannot be auto-generated. It will also appear whenever at least one undocumented parameter has already been added.
  • Improving documentation. We will improve the documentation for the VisualEditor Template dialog and link to it directly from the dialog, providing easy access to more in-depth information.
  • The planned improvements to make adding files easier had to be cancelled, unfortunately.

Indirect improvements via related projects

  • Adding a dropdown with suggested values. Parameters may now have a new dropdown menu with a list of predefined values. Users see this dropdown if the template’s TemplateData contains the new parameter property “suggestedvalues”, providing suggested values for this parameter. This change should make selection quicker and reduce typos and spelling variants, and it can help template users understand what the template author had in mind for this field. You can still enter your own value not listed in the dropdown menu.


  • The sidebar will display all parameters available for this template as defined in TemplateData. You can easily see all the options and add many parameters at once.
  • Checkboxes will indicate which parameters appear in the main dialog. You will be able to quickly add a parameter by checking it and remove it by unchecking it. Required parameters will be selected by default and can’t be unselected; suggested parameters will be selected by default; optional parameters will be listed but not selected.
  • You will be able to filter all available parameters with a search bar.
  • The sidebar will serve as a table of contents: you can click on the name of a parameter to jump to its input field in the main dialog.
  • In the desktop view, the sidebar will always be open (on mobile it’s collapsed by default).
  • The toolbar at the bottom contains a few advanced options which are only relevant for multi-part content.[1] To reduce confusion, this toolbar will be hidden for single template invocations (the most common way templates are invoked) and displayed only when editing existing multi-part content.


The size of the dialog will be significantly larger (sidebar and main area); better spacing will make it easier to work with the complex content and to see more at a glance.


  1. Multi-part content contains one or more templates and in some cases wikitext, mainly used for unbalanced templates and templates within tables.