Return to site

One of my biggest mistakes while building the Webform module for Drupal

· Drupal,Webform,Translations,Accessibility,Drupal 9

For the past year, I have been working towards a stable release of Webform 6.x for Drupal 8/9. Last year, I published a blog post titled, A bump in the Webform module’s road to Drupal 9, where I stated...

Fixing bad-smelling code is going to cause a bump in the Webform module’s road to Drupal 9.

That post specially focused on refactoring classes to not override constructors for service objects, plugins, and controllers. The post concluded by stating the Webform module’s version number will have to be bumped up from 5.x to 6.x. Besides refactoring constructors on the Webform module’s road to Drupal 9, I have also removed deprecated code, fixed some challenging issues, and managed to correct a few mistakes. That said, there are some issues and bad-smelling code that are not easy to fix.

I want to admit that I made some mistakes around the translatability of a webform.

Drupal provides a robust and well-thought-out API and UI for translating content and configuration. If you have a reasonably simple module that correctly defines a schema/metadata for configuration entities and uses Field API for content entities, Drupal’s translation system works as expected. The Webform module is not a simple module and using the basic schema/metadata definitions for configuration entities wasn’t always an option. Before I get into some technical details around these mistakes, there is a much simpler reason I made mistakes around translations: I only speak English and rarely use Drupal’s translation system.

As a non-disabled English speaking Drupal module developer, I made two mistakes while building the Webform module…

I ignored the accessibility and translatability of the Webform module.

Fortunately, I started caring about accessibility and fixed most of the Webform module’s accessibility issues. Now, accessibility is one of the first things I consider when adding a new UI feature. I also did not think about the translatability of the Webform module. Back when the Webform began as the YAML Form module, I was looking for a quick-and-dirty way to build a form and decided to use YAML as the underlying data structure for a webform’s elements.

I love YAML, and so does Drupal, but Drupal’s translation system focuses on translating simple text strings. It’s easy to define a schema for a simple YAML configuration file, which contains mostly key-value pairs. It isn’t easy to define a configuration schema for a webform with 80+ elements with 50+ varying properties that can be nested within each other. The YAML used to express a webform’s elements is stored as one giant string of text, leading to two problems.

First, Drupal’s configuration translation system does not handle large strings of text (i.e. greater than 64kb); this resulted in Issue #2836206: Translation of big webforms broken - an issue that has been open for four years, and might never be resolved. The most straightforward explanation I gave in the issue queue is “I don’t have the free time available to fix this issue.” And frankly, it would take weeks and possibly months to rework how a webform stores its elements. Fortunately, a patch works around the issue but sadly, this patch should never be committed to Drupal core.

Second, besides breaking the translation of big webforms, storing a webform’s elements as YAML made it challenging to provide a user-friendly interface for translating a webform’s elements. Once again, because translatability was not a high priority for me, I opted to build a good enough MVP (minimum viable product) solution, which extracted an element’s translatable labels and descriptions and then let the translator edit these values as raw YAML. The below screenshot shows the UI for translating the default Contact webform in Webform 8.x-5.x.

The UI for translating the default Contact webform in Webform 8.x-5.x.

Yep, for a non-technical user, that is a pretty confusing user interface and experience. It requires translators to understand YAML.

At first, I was hesitant to start working on a solution, but I realized while Webform 6.x is still in alpha releases there was an opportunity to fix this problem. The answer was to refactor the Webform’s translation-related code, making it feasible to provide a friendly user interface for editing a webform’s elements translated labels and descriptions.

Below is the new and improved UI for the UI for translating the default Contact webform in Webform 6.x.

The new and improved UI for the UI for translating the default Contact webform in Webform 6.x.

I am very proud of the above screenshot - not because I managed to fix some of my mistakes, but because I removed a frustrating user experience.

My mistake was not being empathetic to end-users with disabilities and people who speak languages other than English. When working within the Drupal community, one of my roles is to be an empathetic software developer, to continually reevaluate the needs of the end-users. I also see my work as a means of making people’s jobs a little easier. It is a process that is constantly shifting and changing, informed by what we know also by what we have yet to learn.

The lesson you can learn from my mistake is to pay attention to your code and module’s accessibility and translatability.

All Posts

Almost done…

We just sent you an email. Please click the link in the email to confirm your subscription!