Add support for webform variants

Problem/Motivation

To perform A/B testing and the personalization of a webform, a site builder needs to create a variant of the form that can be triggered based on certain contexts.

A variant is a form or version of something that differs in some respect from other forms of the same thing or from a standard.
-- https://www.lexico.com/en/definition/variant

A webform variant might alter a form's labels, descriptions, and even it's confirmation page. A webform variant could be used to create an A/B test to confirm if a tweak or improvement to a webform's user experience does, in fact, increase the form's completion rate. A very basic A/B test would randomly load the variants, allow a defined number of users to complete the form, and then review the results to determine which variant had the highest completion rate. The most successful variant can then be permanently applied to the webform.

A webform variant could also be used to create a personalized webform based on a user's demographics. For example, a webform's available inputs, labels, and even options could be altered based on a user's gender, age, locale, employer, etc… Even subtle tweaks can improve a form's user experience, for example, removing inappropriate options or inputs based on a gender simplifies a form.

Proposed resolution

Right now, the one out-of-box solution is to create multiple instances of a webform and route users to the appropriate webform. The biggest issue with multiple webforms is you will need to collect two different datasets. Ideally, all submission data should go into the same results table to be analyzed with just the user experience changing.

You can also use conditional logic to tweak hide/show elements and disable/enable certain behaviors. Both approaches have limitations and lack some organization. For A/B testing, it is possible to alter a form via JavaScript but this approach is limited to front-end tweaks, for example, you can't alter an element's server-side conditional logic using client-side JavaScript.

The best solution is to build an administrative user interface for defining and managing webform variants. Site builders need to define a variant type as an element and then create variants as individual webform handlers. Storing the variant type as an element makes it easy to track and report submissions by variant. Implement the variant instances as webform handler make it very easy to alter any aspect of the webform. Since, A/B testing and personalization is an advanced concept allowing site builders to alter elements, settings, and behaviors using YAML provides the most flexibility. Webform variants can alter a webform's title, settings, handler, and elements.

Altering a webform's title and settings allow a form's behaviors to be tweaked. For example, a variant can change a webform's confirmation type and message. It is also possible to setup variant-specific submission limits.

Altering a webform's elements makes it possible to change an element's types, label, validation, and even conditional logic. A webform's elements can be completely overridden and replaced or simply have an individual element's properties altered. Being able to complete override an webform's elements makes it possible to perform an A/B test where elements can be reordered.

Altering a webform's handlers configuration is mostly applicable to email handlers because variants should be able to alter an email's subject, message, and recipients.

Remaining tasks

• Create webform_variants element
  • Extends value element
  • Support prepopulation via query parameter
  • Allow variants to be randomly selected
  • Provide default configuration for a variant handler
• Create webform_variants handler
  • Similar to the Settings handler
  • Requires site builders to select a variant type
  • Allows variants to be archived which make the unavailable to new submission but still applicable to old submissions.
  • Provide debug information on which variants are being applied based on the current webform's context
  • Validate element, settings, and handled data type values
• Refactor WebformHandler to support only displaying variant handlers when a variant type element is added to a webform.
• Add adminster variants 'permission'
• Create a Variants management page under the 'References' tab
  • Actions include 'View', 'Test', and Create''
  • List all webform node instance using variants
• Provide an 'Add Variant' dialog
• Add Variants page to 'Results'
• Create A/B example
• Write automated tests
• Create a change record

Webform variant element YAML source example

test:
  '#type': webform_variants
  '#prepopulate': true
  '#randomize': false
  '#default_value': a

Examples

The webform_example_variant.module will include an example of an A/B test for a Feedback form. The variants will show how to create a compact and expanded version of a webform.

User interface changes

Adding new variants element and variant handler

API changes

Webform handler might need to be tweaked.

Data model changes

N/A

Release notes snippet

TBD

User Acceptance Testing

Variant permission

• Confirm variants element is not available.
• Enable 'edit webform variants' permission. - /admin/people/permissions#module-webform

Variants configuration

• Confirm permission messages mesage.
• Confirm variants can be sorted.
• Confirm variants can be enabled/disabled.

Variant element

• Add variant element to webform.
• Confirm Variants is available via configuration settings.
• Confirm create, edit, and delete reload the entire page, which hides/shows Variants tab.
• Confirm multiple variants are supported.
• Confirm display on works as expected.

Handler plugin

• Confirm ::isApplicable method is working as expected

Variant update

• Confirm update hook - webform_update_8178()

Variant plugin report

• Confirm variants plugin report - /admin/reports/webform-plugins/variants
• Review variants plugin report help text

Variants management

• Confirm variants admin configuration form - /admin/structure/webform/config/variants
• Review variants help text
• Confirm variants sorting
• Confirm when the variant element is deleted a broken element error message is displayed.
• Confirm variants settings form add, duplicate, edit, disable, enable, and delete
• Confirm variant view and test operations

Select a variant

• Confirm variants filtering
• Confirm only select variant types are available - /admin/structure/webform/manage/{webform}/variants/add

Variants view/test

• Confirm multiple variants display view/test operations - /admin/structure/webform/manage/webform_example_variant_segments/variants
• Confirm variant view and test operations querystring parameter changes based on #prepopulate.

Variant disabled

• Confirm disabled variants do not display view, test, and apply operations.
• Confirm variant value is still always saved with a submission but the variant is not applied.

Variant apply

• Confirm single variant can be applied
• Confirm single variant can be applied and deleted
• Confirm single variant can be applied and all variants deleted
• Confirm multiple variants can be applied
• Confirm multiple variants can be applied and deleted
• Confirm multiple variants can be applied and all variants deleted

Variant override plugin

• Confirm settings, elements, and handlers form 
• Confirm settings, elements, and handlers validation
• Confirm debug

Variant examples

• Confirm A/B variants are randomized - /form/webform-example-variant-ab-test
• Confirm form type and organization can be tested - /form/webform-example-variant-segments

Appling variants

• Confirm variant is applied via default value
• Confirm variant is applied via webform node default default
• Confirm variant is applied via a query string parameter
• Confirm variant is randomized
• Confirm disable variant can not be applied

Randomized variants

• Confirm JavaScript is loaded when #randomize is TRUE.
• Confirm only enabled variant elements are randomized.
• Confirm only enabled variant plugins are randomized.

Variant webform nodes reference

• Confirm Add buttons are replaced with one 'Add references' button
• Confirm 'Add references' form redirects to the appropriate 'Create content' form

Variant configuration management

• Confirm variants are included in the exported configuration - /admin/structure/webform/manage/contact/export