3.0 Exploration

Problem/Motivation

Currently working on the nuxt-formkit-webform Nuxt module that integrates graphql_webform with the FormKit form library. It maps webform elements to matching FormKit inputs and its aim is to support as much of webform's features as possible.

This required exposing more fields on element types and introducing new GraphQL interfaces to share common fields between these element types. In addition it revealed a couple of bugs in existing resolvers, but especially in the webform_submit producer.

I have tried to keep each new element + bug fix in single commits, but resolving elements + handling submission for all of them basically required changes in a handful of files across all of them.

API changes

Query.webformById

• Pre-existing sourceEntityType / sourceEntityId args now actually reach form build - they were stashed on the field context but WebformElements called getSubmissionForm() with no arguments, so [webform_submission:source-entity:*] tokens never resolved. Now passed as entity_type / entity_id values to getSubmissionForm($values, 'api') inside the sub-request.
• New prepopulate: String - URL-encoded query string (e.g. address[city]=Cologne&color=red). Honours the webform's form_prepopulate setting and per-element #prepopulate: true opt-in. Reserved source_entity_* keys are stripped.

Webform.elements

• Elements with #access FALSE (display_on: view / none, permission denials, custom access) are filtered out.
• Form is built in api mode inside a sub-request to entity.webform.canonical. The sub-request prevents the GraphQL endpoint's graphql_server route param from leaking into source-entity detection; api mode prevents Webform from disabling elements that aren't on the current wizard page (i.e. everything past the first page).
• When WebformSubmissionForm::getCustomForm() rejects the render tree (closed form, source-entity mismatch, limit reached, …), the element list collapses to a single fake WebformElementWebformMessage keyed unavailable. Temporary workaround, the proper fix is a new WebformForm type.

Cacheability

• Per-element #cache (tags / contexts / max-age) is bubbled to the GraphQL field context at every tree level.
• Form-root bubbles tags + contexts; the max-age = 0 that EntityFormDisplay::buildForm() always adds is dropped (it'd make every webform response uncacheable for reasons that don't apply). Per-element max-age preserved, so time-token cacheability ([date:medium], etc.) still works.
• #default_value resolution is rerouted through a dedicated webform_element_default_value producer that re-runs token replacement with its own BubbleableMetadata - otherwise token cacheability was lost when the form-root max-age got stripped. Debatable whether this is a good thing or now, but it at least allows us to respect cacheability for default value tokens (e.g. time-based tokens that always require a max-age of 0).
• Form build wrapped in a RenderContext to catch cacheability that leaks the form's cache metadata (e.g. WebformComputedToken::computeValue).

Mutation.submitWebform

I tested every element type for "submissability", both in single and multi value formats.

• *_other variants: value + "other" input split correctly; composite-with-other is handled.
• Checkboxes: the all and none values are normalized.
• Date / datelist input parsed into the element's expected shape; multi-value date submissions validated.
• Custom composite with #multiple: value shape fixed.

#states

• Wizard pages no longer drop element states. Previously the resolved states would get lost for all elements inside pages 2+.
• Inverted conditions (e.g. ['checked' => FALSE]) now return the correct trigger + value pair instead of the positive trigger with an empty value. It basically fixes the bug with the "same" element, where checking e.g. "shipping same as billing" would show the target element instead of hiding it.

Data model changes

Per-plugin fields added on auto-generated types

Support for more elements was added:

• webform_message - body, type, close, id.
• webform_terms_of_service.
• webform_computed_token / webform_computed_twig - computedValue, mode, computedDisplayOn.
• webform_email_confirm - confirm-input title / description / placeholder, flexbox.
• webform_autocomplete - items, limit, match length, match operator.
• webform_same - source, destination.
• webform_likert.
• view - name, displayId, arguments (metadata only, view is not executed).
• entity_autocomplete - defaultEntities resolved to {id, label} pairs.
• *_other variants of select / radios / checkboxes.

New interfaces

• WebformElementNumericBase - min / max / step for plugins extending NumericBase.
• WebformElementSelectBase - emptyOption.
• WebformElementCheckboxesBase - optionsAllValue / optionsNoneValue.
• WebformElementOptionsDisplayBase - orientation, randomize, etc.
• WebformElementComputedBase - shared computed-element fields.

New fields on existing types

• Textfield / Textarea / WebformAutocomplete - counter, inputMask, inputHide.
• Date / Datelist / Datetime - part order, year range, increment, text parts, placeholders, time min / max / step.
• Tel - international picker config, per-format validation.
• Color - colorSize.
• Details - open.
• Number / Range - size, placeholder, autocomplete, slider output placement + prefix / suffix.
• Section - titleTag.
• Signature - readonly.
• Time - min / max / step (string-typed, distinct from the numeric triplet).
• Flexbox - alignItems.
• Actions - submitLabel.
• Containers - randomize.
• Options elements - optionsRandomize (resolver unshuffles stored options for stable output); groupLabel on nested groups.
• Term select - optionsWithDepth(depth: Int).

Todos

The biggest todo is the introduction of a new WebformForm type. The current workaround of emitting a fake webform_message element when resolving elements at least allows fetching the form that is unavailable.

The elements field would move to this new type. The type would also have a new unavailable field that properly resolves the reason for why the form is unavailable (and maybe even an enum).

The current schema doesn't allow this: The elements producer currently "owns" the call to getSubmissionForm. It would have to return an empty array in this case. A new resolver for the unavailable field would then have to call the same method again, just to determine if the returned render array is actually the webform and not the "custom form" render array that contains the message.

Doing so also makes sense from a data structure way: The Webform is the entity and WebformForm is the actual form. This split would also allow us to move sourceEntityLabel etc. into this new type, because it belongs to the form, not the webform entity.