Component edit form.
Structured text components.
Error messages for individual parts failing validation.
Various field configurations, with one in error for uniqueness violation.

This module provides a webform component for structured text - text that follows an input-mask format. For example, you may want to gather phone numbers in a particular format, but an ordinary text field doesn't do that. You could cobble together a few different text or number fields to do what you want, and use Webform Validation to try to check the input, but that's a pain to maintain. This control provides you with a single field definition and data storage, with validation based on the mask and optionally supplied RegEx.

Installation and Configuration

Install and enable the module as you would any contributed Drupal module. Once enabled, you should have a new Webform control type called "Structured Text". Configure it like any other Webform component, including specifying the mask you want to use, any labels, placeholders, and default values you want to use, if the user-input values should be unique, and if you want there to be a description of the input format appended to the description you provide. You can also specify you want to 'auto-skip' to the next chunk when the prior one is filled, and if chunks should be evaluated against a RegEx. Full instructions on specifying masks are given in the component (see image). Save the control, and that's it.

The control validates that all chunks of the field are filled in according to the specified mask if the field is required or if any chuck has input. Validation errors are generated if chunks are missing, or the characters in the chunk don't correspond to the mask, or if any specified RegEx comparisons fail.

Once the input passes validation, the chunks are concatenated and stored as a single value in the database. However, they are displayed and output to CSV in the format specified by the mask.

Dependencies

  1. Webform. Webform Structured Text works with both major versions 3 and 4 of Webform.
  2. PHP 5.3 or above is required as of version 1.7 of the module.

Partial Incompatibility

Webform Conditional: If a user leaves a value in a structured text component that subsequently becomes hidden because another controlling choice is made, without the patch found at #2203469: Better accommodation for components with nested form controls., the element value won't be cleared properly, and the element will still go through (and possibly fail) validation, even though it's no longer visible and applicable.

Translation

As of version 1.5, Webform Structured Text components are fully translatable by leveraging Drupal's built-in localisation, enhanced with the the Internationalisation module, and the Webform Localisation module (D7 only).

Webform Localisation handles translation of the field label (the component's '#title' attribute), as well as description, hidden mask labels, and placeholders. These all appear as part of the "Webform Localization" text group in the translation interface.

Configuration text can also be introduced within the mask itself, and within RegEx validation error messages. Webform Structured Text handles submitting these specialised, embedded pieces of text to the translation system, and they appear under the text group "Webform Structured Text" in the translation interface.

Note that only strings displayed to the end user are translatable (title, description, hidden mask labels, placeholders, markup embedded in the mask, and RegEx error messages), but not the mask specification itself nor the RegEx patterns. For example, in the mask (999) 999-9999 E^xt: r10,5, the (, ), -, and Ext: will appear in the translation interface, but not the entire mask. Similarly, for a RegEx of 1|Area Code cannot begin with a zero.|/[1-9][0-9][0-9]/, only Area Code cannot begin with a zero. will appear in the translation interface, and not the RegEx pattern itself.

Theming

The default behaviour when rendering a structured text component (as of version 1.7) is to make the component appear as if it is a single text field with the individual input boxes inside this field. This is done by using a surrounding <div> with a border around it, and then making the individual <input> fields borderless. Because of this, the rendered component may not look exactly like the rest of your text input fields, particularly if they are heavily styled. The webform_structured_text.css file has instructions for themers who want to modify the look of the component to match the rest of their <input> fields. Note that this only applies if you allow Webform Structured Text to render the component to appear as a single field. If you instead choose to render the component as individual boxes for each chunk, they will render as do all your other text input fields.

Project information

Releases