Problem

The Webform module for Drupal 8 provides support for basic, advanced, and composite inputs/elements. Developers can also create custom elements and composites via code. Sometimes end-users need an interactive visual mechanism to select a complex option like a map location. The Image select element is limited to allowing users to select horizontally-aligned images.

What if an end-user needs to select a seat on a plane, a part of the human body, or a room at a conference?

HTML5 and SVG allow designers and site builders to build visually rich and interactive elements. To convert rich interactive HTML/SVG elements into a form input, there needs to be some PHP and JavaScript glue code that captures a user's selection and sets it as a webform submission value. 

Besides capturing the end-users selection, the PHP and JavaScript code must also ensure that the interactive HTML/SVG element is accessible to users with disabilities. 

Solution 

Allow site builders to create a custom 'options' element using HTML/SVG markup.

Concept

The general concept for creating a custom 'options' element' is to allow site builders to provide HTML/SVG markup that is dynamically converted into a select-able and accessible Webform element. 

Below is a straightforward example of some HTML markup that can be enhanced.

<div data-id="one" data-name="One" class="button">One</div>

<div data-id="two" data-name="Two" class="button">Two</div>

<div data-id="three" data-name="Three" class="button">Three</div>

 SVG support requires the same data-id and data-name attributes being added to the HTML markup. Below is an example of a single clickable element in SVG.

<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">

<circle cx="50" cy="50" r="50" data-id="circle" data-name="Circle" />

</svg>

Implementation 

The HTML/SVG markup must provide an option value or text attribute that can be used to create a list of available options. The default recommended 'value' attribute names are 'data-option-value', 'data-value', 'data-id', or 'id'. The default recommended 'text' attribute names are 'data-option-text', 'data-text', 'data-name', 'name', or 'title'. The Webform module uses these value/text attribute names to parse and detect the custom element's available options.

Accessibility 

Once the available options are detected, JavaScript is used to make each option focusable, clickable, and accessible using ARIA (Accessible Rich Internet Applications) and related HTML attributes. To allow the user's select option to post back to the server, a select menu is provided to capture the user's selection. The select menu supports HTML5 validation and provides a fully accessible alternative input for a user using a screen reader.

Example

Here is an example of a clickable map of U.S. states. 

Demo

More about custom 'options' elements

Configuration

Only webform administrators can define custom 'options' elements. Since these elements support any HTML/SVG markup, including JavaScript; Only trusted users should be allowed to administer the Webform module and create custom 'options' elements. 

HTML/SVG markup can be loaded from a URL or cut-and-pasted into the code editor. HTML/SVG markup supports Twig which can be used to enhance the markup and even render custom options.

 To being building custom 'options' elements, install the Webform Custom Options module (/admin/modules) and go to the Custom options configuration page (/admin/structure/webform/config/options_custom/manage).

​

Translation

Besides parsing option value and text from the HTML/SVG markup, the option value, text, and description can also be provided via the element edit form. Options entered via the element edit form are available for translation.

Enhancements

To make it easier for end-users to see more information about the available options, tooltip support is provided. SVG graphics can be panned and zoomed using the SVG Pan & Zoom library.

Integration

Custom 'options' elements are available to webforms as simple elements and entity references. Custom 'options' element which support entity references must have their option value match the entity reference ids, or the option text match the entity reference titles.

What is next for custom 'options' elements?

Code

The Webform Custom Options module is experimental. If you extend, alter, or override any code, please test your changes when updating the Webform module. The module's code still needs to be finalized. We also need to determine if any additional hooks or templates are required.

Examples

Currently, the only example is a map of U.S. states. More HTML/SVG examples and possibly a dedicated 'Webform Custom Options Examples' module are needed. A dedicated contrib module which provides SVG maps is also something that would be great to have. All examples need to use freely available SVGs with proper attribution to the source.

As a community, we need to explore what is and isn't possible using HTML and SVG graphics when creating a custom 'options' element.

Documentation

Documentation always needs improvement. Solving the challenge of click-able custom options requires a fairly complex solution. Please help me clarify how things work and how to create the necessary custom HTML/SVG markup.

Accessibility

Accessibility should never be ignored, assumed, or taken for granted. Custom 'options' elements need to be fully keyboard accessible and provide the right information to screen readers. The SVG Pan & Zoom library does need some accessibility improvements, especially around keyboard navigation.

Who sponsored this feature?

History

Two years ago, Madhan K'Samy (MkSamy) created Issue #2907663: SVG image parts as selectable options element, and we discussed this feature. I was able to build a simple prototype. Madhan K'Samy was unable to sponsor this feature. However, for the past two years when people asked for similar functionality I would demo the prototype.

Steve Babbitt from Mile3 (https://www.mile3.com/) approached me about sponsoring the new Webform Options Limit submodule, mentioning that his client needed a clickable SVG graphic. I showed him the prototype and he spoke with his client, who was willing to sponsor and contribute this feature, which allowed us to scope out the feature request using Issue #3081795: Allow custom HTML/SVG markup to be used as options.

Steve and clients have sponsored and contributed a feature that has changed what is possible using the Webform module. This feature allows an airline to convert an airplane's seating chart into an SVG graphic, which then can be used to create a seat selection Webform element. That’s an amazing feat and I’m confident we can find even more ways to make the best use out of this feature. 

This sponsored feature demonstrates the flexibility, openness, and collaboration that makes any idea or business requirement a possibility using Drupal.

If you want to sponsor a feature, please read my blog post and create a ticket in the Webform module's issue queue.

Backing the Webform module

Open Collective is providing us, Drupal, and Open Source, with a platform to experiment and improve Open Source sustainability. If you appreciate and value what you are getting from the Webform module, please consider becoming a backer of the Webform module's Open Collective. More support means more input with regard to enhancing accessibility and that is always a good thing.