Forms

View as Markdown

Build a form that submits to an Extbase action with fetch, shows server and client validation errors on its fields and reports the result without a page reload.

Installation

Add the Form and Field primitives:

typo3 ui:add form && typo3 ui:add field

Submit a form to an Extbase action

Render the form

Point action at your Extbase action and set objectName to the name of the action's argument. object fills the fields from an existing model instance.

<ui:form.root action="registration" objectName="eventRegistration" object="{eventRegistration}">
    <ui:field.root name="email" required="{true}">
        <ui:input.root type="email" autocomplete="email">
            <ui:input.label>Email</ui:input.label>
            <ui:input.input />
        </ui:input.root>
        <ui:field.helperText>We send your confirmation here.</ui:field.helperText>
        <ui:field.errorText />
    </ui:field.root>

    <ui:button type="submit">Register</ui:button>
</ui:form.root>

Each input sits in a field. Its name is the property of your model (person.name for a nested one), which is how errors find the field. Primitives like ui:select or ui:numberInput nest the same way, and their own label part points the label at the right control. A native element without a primitive goes into ui:field.control with asChild="{true}".

The values are sent under the argument namespace of the plugin the form submits to, for example tx_myextension_eventregistration[eventRegistration][email]. The form uses the plugin that renders it or, when you set controller, the plugin that registers that controller and action, so it can render in one plugin and post to an action of another. Set extensionName and pluginName to name the plugin yourself, they win over both. Outside an Extbase request, in a plain Fluid partial for example, pass both: with either one missing, rendering throws.

Answer with JSON

Make sure your controller returns a valid JSON response via $this->jsonResponse(). To make this work you either have to register the action as an AJAX page type via Typoscript or use throw PropagateResponseException().

Persistence Warning

When using PropagateResponseException to return a JSON response, make sure to persist your data manually before throwing the exception since we exit Extbase's normal flow.

JsonValidationErrorsTrait replaces the errorAction() of your controller. Failed validation is automatically answered with a 422 JSON response of messages keyed by field, which the form maps onto its fields. Good to know: the trait uses PropagateResponseException internally to return the JSON response.

use Jramke\FluidPrimitives\Traits\JsonValidationErrorsTrait;
use TYPO3\CMS\Core\Http\PropagateResponseException;

final class EventRegistrationController extends ActionController
{
    use JsonValidationErrorsTrait;

    public function __construct(
        private readonly EventRegistrationRepository $eventRegistrationRepository,
    ) {}

    public function registrationAction(EventRegistration $eventRegistration): ResponseInterface
    {
        $this->eventRegistrationRepository->add($eventRegistration);

        return $this->jsonResponse(
            json_encode(['message' => 'Thank you for registering.'], JSON_THROW_ON_ERROR),
        );
    }
}

The trait covers every action of the controller. To keep Extbase's error handling for other actions, alias its method and dispatch by hand:

final class EventRegistrationController extends ActionController
{
    use JsonValidationErrorsTrait {
        errorAction as protected jsonErrorAction;
    }

    #[\Override]
    protected function errorAction(): ResponseInterface
    {
        if ($this->actionMethodName === 'registrationAction') {
            return $this->jsonErrorAction();
        }

        return parent::errorAction();
    }
}

Send the values

ui:add form ships an entry file that mounts every form and posts its values with extbase.post(). The message of the JSON response becomes the error or success text of the form.

Write your own entry file for validation, render or a different onSubmit. Give the root autoMount="{false}" and a rootId such as registration-form, then mount it by that id (see Hydration):

import { extbase, mount } from 'fluid-primitives';
import { Form } from 'fluid-primitives/form';

mount('ui:form', 'registration-form', ({ props }) =>
    new Form({
        ...props,
        onSubmit: async ({ api, values }) => {
            const response = await extbase.post(api.getAction(), values.toObject(), {
                prefix: api.getFieldNamePrefix(),
                objectName: api.getObjectName(),
            });

            const data: { message?: string } = await response.json().catch(() => ({}));
            if (!response.ok) {
                api.setErrorText(data.message ?? null);
                return false;
            }

            api.setSuccessText(data.message ?? null);
            return true;
        },
    }).init()
);

extbase.post() nests the values under the Extbase namespace, Extbase's hidden __trustedProperties and __identity fields included, so your fields keep plain names like email or person.name.

Clear a property with an empty field

Every control submits its name, also while it is empty, so Extbase can clear the property it is bound to. An unchecked Checkbox or Switch, a CheckboxGroup with nothing checked, and a Select, Combobox or DatePicker without a value submit ''. A RadioGroup with nothing chosen submits nothing, like native radios.

A field whose name ends with [] (tags[]) submits its empty value under the name without the brackets (tags), as Fluid's own f:form.checkbox does: Extbase maps '' to an empty array or ObjectStorage. In the form values the field reads as [] and an unchecked box as '', and extbase.post() sends an empty list as '' again.

A disabled control submits nothing, and neither does its empty-value input. Render your own control's input with ui:emptyValueInput.

Show server-side errors on the fields

With the trait, Extbase's validation errors arrive as a 422 response. Each key is a property path, prefixed with the objectName:

{
    "eventRegistration.email": ["Please enter a valid email address."],
    "eventRegistration.name": ["Please enter your name."]
}

Every key lands on the field with that name and shows in its ui:field.errorText.

A server error belongs to the value that caused it. It disappears when the user changes the value and returns when they enter that value again. Pick the VIP ticket in the event registration example and submit to see it.

A key equal to the objectName carries a message about the whole object. It becomes the error text of the form and the form ends in error.

Reject a submission from the action

For a rule that lives outside the model, such as a sold-out ticket, send the 422 yourself:

if ($eventRegistration->getTicketType() === 'vip') {
    $payload = ['eventRegistration.ticketType' => ['VIP tickets are sold out.']];
    $response = $this->jsonResponse(json_encode($payload, JSON_THROW_ON_ERROR))->withStatus(422);
}

Secure the action

A Form posts with fetch and the cookies of the visitor, like any other form. Extbase signs part of what it sends, the rest is up to your action:

__trustedProperties signs the field names, not the visitor. Name the properties an argument may set with allowProperties('name', 'email'), because allowAllProperties() lets a visitor set every property of the object.
__identity is signed as present, its value is not. A visitor can send the identity of any object of that type, so check in the action that they may change it.
The frontend session cookie is SameSite=lax by default, so another site cannot post a form with the session of the visitor. If your site sets cookieSameSite to none, send a request token: pass { headers: { 'X-TYPO3-RequestToken': token } } to extbase.post() and read it with SecurityAspect::getReceivedRequestToken() in the action.
required, pattern, maxlength, accept and the client-side validation below only help the visitor. Validate on the server.

Client-side validation

Validating in the browser gives quicker feedback and improves the user experience. Keep the server-side validation as well: a client check can be bypassed, the server check cannot. Native constraints, the validation of the form and the validate of a field end up in the same error text as the errors of the server.

Fields check the native constraints of their control without any TypeScript: required, type="email", pattern, min/max and minlength/maxlength. A maxLength that should not cut a paste off works through the maxLengthBehavior of an Input or Textarea. Submit this form empty to see the messages:

<ui:form.root actionUri="#" class="w-full max-w-74">
    <ui:form.content class="space-y-6">
        <ui:field.root name="email" required="{true}">
            <ui:input.root type="email" autocomplete="email">
                <ui:input.label>Email</ui:input.label>
                <ui:input.input />
            </ui:input.root>
            <ui:field.errorText match="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ValidityMatch::ValueMissing')}">Please enter your email address.</ui:field.errorText>
            <ui:field.errorText match="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ValidityMatch::TypeMismatch')}">That doesn't look like an email address.</ui:field.errorText>
        </ui:field.root>

        <ui:field.root name="zip">
            <ui:input.root type="text" inputmode="numeric" autocomplete="postal-code">
                <ui:input.label>ZIP code</ui:input.label>
                <ui:input.input pattern="[0-9]+" minlength="5" maxlength="5" />
            </ui:input.root>
            <ui:field.helperText>Five digits.</ui:field.helperText>
            <ui:field.errorText match="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ValidityMatch::PatternMismatch')}">A ZIP code only has digits.</ui:field.errorText>
            <ui:field.errorText match="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ValidityMatch::TooShort')}">A ZIP code has five digits.</ui:field.errorText>
        </ui:field.root>

        <ui:button type="submit">Submit</ui:button>
    </ui:form.content>
</ui:form.root>

By default a field validates when the user leaves it after editing, and again on every change while it shows an error. A submit validates every field and moves the focus to the first invalid one. The validation mode changes when errors show up, and a field can run its own async check.

Validate with a schema

Pass a synchronous Standard Schema validator such as Zod (npm install zod) as validation, next to your onSubmit:

import { z } from 'zod';

const validation = z.object({
    name: z.string().min(1, 'Please enter your name'),
    email: z.email('Please enter a valid email address'),
    ticketCount: z.coerce.number().min(1).max(10),
    privacy: z.literal('1', 'Please accept the privacy policy'),
});

mount('ui:form', 'registration-form', ({ props }) => new Form({ ...props, validation }).init());

The keys match the name of the fields, person.name for a nested one. Values arrive as strings or Files, so ticketCount reads as '2' until z.coerce.number() converts it. onSubmit runs once every field is valid, until then the focus moves to the first invalid field. Any validator that implements the Standard Schema interface works the same way.

Manual client-side validation

Without a schema library, pass a callback. It receives values and returns errors keyed by field name, the shape of a 422 response. A callback also suits rules across fields, like a password confirmation.

mount('ui:form', 'registration-form', ({ props }) =>
    new Form({
        ...props,
        validation: ({ values }) => {
            const errors: Record<string, { messages: string[] }> = {};
            const email = values.get('email');

            if (typeof email !== 'string' || !email.includes('@')) {
                errors.email = { messages: ['Please enter a valid email address.'] };
            }

            return errors;
        },
    }).init()
);

values offers get(path), getAll(path), has(path), pick(path) and toObject(), with your field names as dot paths. validation runs synchronously. Check a single field asynchronously with the validate of the field, and use onSubmit for checks that need the whole form.

Show the result of a submit

onSubmit ends with one of three results:

true - the form goes to success
false - the form goes to error, as does a rejected promise such as a network failure
field errors, Record<string, { messages: string[] }> - the form goes to invalid and every message lands on its field

Show a message for the whole form

Set the text with api.setErrorText() and api.setSuccessText(), as the onSubmit above does. form.content shows its fields in ready, invalid and submitting and hides them in error and success. A form.indicator shows its content in the state you give it. form.errorText and form.successText show the text you set, or their own content when you set none. A button with type="reset" brings the form back to ready.

<ui:form.root ...>
    <ui:form.content>
        <!-- fields -->
    </ui:form.content>

    <ui:form.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FormState::Error')}">
        <ui:form.errorText>Something went wrong. Please try again.</ui:form.errorText>
        <ui:button type="reset">Back to form</ui:button>
    </ui:form.indicator>

    <ui:form.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FormState::Success')}">
        <ui:form.successText
            >Your registration was submitted successfully. Thank you!</ui:form.successText
        >
    </ui:form.indicator>
</ui:form.root>

Map a response to field errors

A response other than a 422 can end up on a field too. Return the errors from onSubmit after the extbase.post() call:

if (response.status === 409) {
    return { email: { messages: ['This email address is already registered.'] } };
}

return response.ok;

Style the form state

The <form> carries a data-state attribute: ready, submitting, invalid, success or error. data-submitting, data-invalid, data-dirty and data-touched are present while they apply.

form[data-submitting] button[type='submit'] {
    opacity: 0.5;
    pointer-events: none;
}

Submit button

Use the Button as the submit button. It shows a loading state while the form submits: focusableWhenDisabled keeps the focus on it and its indicator parts swap the label. Loading States explains the aria-labelledby wrapper.

<f:variable name="submitLabelId" value="{ui:id()}" />
<ui:button
    type="submit"
    focusableWhenDisabled="{true}"
    aria-labelledby="{submitLabelId}"
    autoMount="{false}"
    rootId="submit-button"
>
    <span id="{submitLabelId}">
        <ui:button.indicator
            state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ButtonIndicatorState::Idle')}"
            >Register</ui:button.indicator
        >
        <ui:button.indicator
            state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ButtonIndicatorState::Loading')}"
            >Submitting...</ui:button.indicator
        >
    </span>
</ui:button>

Mount the button with its rootId and pass the submitting state on from the render callback of the form, which runs whenever the form state changes:

import { Button } from 'fluid-primitives/button';

const submitButton = mount('ui:button', 'submit-button', ({ props }) => new Button(props).init());

mount('ui:form', 'registration-form', ({ props }) =>
    new Form({
        ...props,
        render: form => submitButton?.api.setLoading(form.api.isSubmitting),
    }).init()
);

Complete example: event registration

A registration with a ticket select, a country combobox, an optional badge photo and Zod validation on the client. The student ticket shows a student ID field through listenTo, and the VIP ticket is sold out on the server.

Event Registration

Ticket Type

How many tickets?

Optional Donation $ 0

Help cover event costs with an optional donation.

Attendance Mode In Person Virtual

Name

Your full name as it will appear on the ticket.

Your email address will be used for registration confirmation and updates.

Phone

Only used if we need to contact you about your registration.

Country

Used for your badge and invoice details.

Badge Photo (optional)

Upload a photo for your badge

JPG or PNG, up to 5MB.

No file selected yet.

Shown on your badge if provided. You can skip this.

Accessibility Needs Wheelchair Access Sign Language Interpretation

Additional Comments

I consent to the processing of my data in accordance with the privacy policy.

<ui:exposeToClient />
<ui:prop name="object" type="FluidPrimitives\Docs\Domain\Model\EventRegistration" optional="{true}" />

<ui:form.root
    action="registration"
    objectName="eventRegistration"
    object="{object}"
    autoMount="{false}"
    rootId="{rootId}-form">
    <h2 class="text-lg font-semibold">Event Registration</h2>

    <ui:form.content class="space-y-6">

        <ui:listCollection
            items="{
                0: {value: 'vip', label: 'VIP'},
                1: {value: 'standard', label: 'Standard'},
                2: {value: 'student', label: 'Student'}
            }"
            as="ticketTypes" />

        <ui:field.root name="ticketType" required="{true}">
            <ui:select.root collection="{ticketTypes}" class="field">
                <ui:select.label>Ticket Type</ui:select.label>
                <ui:select.control>
                    <ui:select.trigger placeholder="Select a ticket type" />
                </ui:select.control>
                <ui:select.content>
                    <ui:select.list>
                        <f:for each="{ticketTypes.items}" as="item">
                            <ui:select.item item="{item}">
                                <ui:select.itemText>{item.label}</ui:select.itemText>
                                <ui:select.itemIndicator />
                            </ui:select.item>
                        </f:for>
                    </ui:select.list>
                </ui:select.content>
            </ui:select.root>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="studentId" required="{true}" hidden="{true}" disabled="{true}" listenTo="{0: 'ticketType'}">
            <ui:input.root>
                <ui:input.label>Student ID</ui:input.label>
                <ui:input.input />
            </ui:input.root>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="ticketCount" required="{true}">
            <ui:numberInput.root min="1" max="10">
                <ui:numberInput.scrubber>
                    <ui:numberInput.label>How many tickets?</ui:numberInput.label>
                </ui:numberInput.scrubber>
                <ui:numberInput.control>
                    <ui:numberInput.decrementTrigger />
                    <ui:numberInput.input />
                    <ui:numberInput.incrementTrigger />
                </ui:numberInput.control>
            </ui:numberInput.root>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="donationAmount">
            <ui:slider.root min="0" max="200" step="5">
                <div class="flex items-center justify-between">
                    <ui:slider.label>Optional Donation</ui:slider.label>
                    <span class="text-sm text-muted-foreground">$<ui:slider.valueText /></span>
                </div>
                <ui:slider.control>
                    <ui:slider.track>
                        <ui:slider.range />
                    </ui:slider.track>
                    <ui:slider.thumb index="0" />
                </ui:slider.control>
                <ui:slider.markerGroup>
                    <ui:slider.marker value="0">$0</ui:slider.marker>
                    <ui:slider.marker value="25">$25</ui:slider.marker>
                    <ui:slider.marker value="50">$50</ui:slider.marker>
                    <ui:slider.marker value="100">$100</ui:slider.marker>
                </ui:slider.markerGroup>
            </ui:slider.root>
            <ui:field.helperText>Help cover event costs with an optional donation.</ui:field.helperText>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="mode" required="{true}">
            <ui:radioGroup.root>
                <ui:radioGroup.label>Attendance Mode</ui:radioGroup.label>
                <ui:radioGroup.item value="person">
                    <ui:radioGroup.itemControl />
                    <ui:radioGroup.itemText>In Person</ui:radioGroup.itemText>
                </ui:radioGroup.item>
                <ui:radioGroup.item value="virtual">
                    <ui:radioGroup.itemControl />
                    <ui:radioGroup.itemText>Virtual</ui:radioGroup.itemText>
                </ui:radioGroup.item>
            </ui:radioGroup.root>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="person.name" required="{true}">
            <ui:input.root autocomplete="name">
                <ui:input.label>Name</ui:input.label>
                <ui:input.input />
            </ui:input.root>
            <ui:field.helperText>Your full name as it will appear on the ticket.</ui:field.helperText>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="person.email" required="{true}">
            <ui:input.root type="email" autocomplete="email">
                <ui:input.label>Email</ui:input.label>
                <ui:input.input />
            </ui:input.root>
            <ui:field.helperText>Your email address will be used for registration confirmation and updates.</ui:field.helperText>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="person.phone">
            <ui:input.root type="tel" autocomplete="tel">
                <ui:input.label>Phone</ui:input.label>
                <ui:input.input />
            </ui:input.root>
            <ui:field.helperText>Only used if we need to contact you about your registration.</ui:field.helperText>
            <ui:field.errorText />
        </ui:field.root>

        <ui:listCollection
            items="{
                0: {value: 'us', label: 'United States'},
                1: {value: 'uk', label: 'United Kingdom'},
                2: {value: 'de', label: 'Germany'},
                3: {value: 'fr', label: 'France'},
                4: {value: 'nl', label: 'Netherlands'},
                5: {value: 'se', label: 'Sweden'},
                6: {value: 'no', label: 'Norway'},
                7: {value: 'dk', label: 'Denmark'},
                8: {value: 'fi', label: 'Finland'},
                9: {value: 'it', label: 'Italy'},
                10: {value: 'es', label: 'Spain'},
                11: {value: 'pt', label: 'Portugal'}
            }"
            as="countries" />

        <ui:field.root name="person.country" required="{true}">
            <ui:combobox.root collection="{countries}">
                <ui:combobox.label>Country</ui:combobox.label>
                <ui:combobox.control class="min-w-64">
                    <ui:combobox.input placeholder="Search your country" />
                    <ui:combobox.clearTrigger />
                    <ui:combobox.trigger>
                        <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 opacity-70">
                            <path d="m7 15 5 5 5-5"></path>
                            <path d="m7 9 5-5 5 5"></path>
                        </svg>
                    </ui:combobox.trigger>
                </ui:combobox.control>
                <ui:combobox.content>
                    <ui:combobox.empty>No countries found.</ui:combobox.empty>
                    <ui:combobox.list>
                        <f:for each="{countries.items}" as="item">
                            <ui:combobox.item item="{item}">
                                <ui:combobox.itemText>{item.label}</ui:combobox.itemText>
                                <ui:combobox.itemIndicator />
                            </ui:combobox.item>
                        </f:for>
                    </ui:combobox.list>
                </ui:combobox.content>
            </ui:combobox.root>
            <ui:field.helperText>Used for your badge and invoice details.</ui:field.helperText>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="badgePhoto">
            <ui:fileUpload.root accept="image/jpeg,image/png" maxFiles="1">
                <ui:fileUpload.label>Badge Photo (optional)</ui:fileUpload.label>
                <ui:fileUpload.dropzone>
                    <div class="grid gap-1">
                        <div class="text-sm font-medium">Upload a photo for your badge</div>
                        <div class="text-muted-foreground text-sm">JPG or PNG, up to 5MB.</div>
                    </div>
                    <ui:fileUpload.trigger>Choose file</ui:fileUpload.trigger>
                </ui:fileUpload.dropzone>

                <primitives:fileUpload.itemTemplate>
                    <ui:fileUpload.fileItem>
                        <ui:fileUpload.itemPreview match="image/*">
                            <ui:fileUpload.itemPreviewImage />
                        </ui:fileUpload.itemPreview>
                        <ui:fileUpload.itemPreview match=".*">
                            <ui:fileUpload.filePreviewFallback />
                        </ui:fileUpload.itemPreview>
                        <div class="grid min-w-0 flex-1 gap-0.5">
                            <ui:fileUpload.fileName />
                            <ui:fileUpload.fileMeta />
                            <ui:fileUpload.fileError />
                        </div>
                        <ui:fileUpload.fileDeleteTrigger />
                    </ui:fileUpload.fileItem>
                </primitives:fileUpload.itemTemplate>

                <ui:fileUpload.itemGroup>
                    <ui:fileUpload.emptyState>No file selected yet.</ui:fileUpload.emptyState>
                </ui:fileUpload.itemGroup>
            </ui:fileUpload.root>
            <ui:field.helperText>Shown on your badge if provided. You can skip this.</ui:field.helperText>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="a11yNeeds[]">
            <ui:checkboxGroup.root>
                <ui:checkboxGroup.label>Accessibility Needs</ui:checkboxGroup.label>
                <ui:checkbox.root value="wheelchair">
                    <ui:checkbox.control />
                    <ui:checkbox.label class="font-normal">
                        Wheelchair Access
                    </ui:checkbox.label>
                </ui:checkbox.root>
                <ui:checkbox.root value="sign-language">
                    <ui:checkbox.control />
                    <ui:checkbox.label class="font-normal">
                        Sign Language Interpretation
                    </ui:checkbox.label>
                </ui:checkbox.root>
            </ui:checkboxGroup.root>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="comment">
            <ui:textarea.root placeholder="Type your message here...">
                <ui:textarea.label>Additional Comments</ui:textarea.label>
                <ui:textarea.textarea />
            </ui:textarea.root>
            <ui:field.errorText />
        </ui:field.root>

        <ui:field.root name="privacy" required="{true}">
            <ui:checkbox.root name="privacy">
                <ui:checkbox.control />
                <ui:checkbox.label>
                    I consent to the processing of my data in accordance with the privacy policy.
                </ui:checkbox.label>
            </ui:checkbox.root>
            <ui:field.errorText />
        </ui:field.root>

        <f:variable name="submitLabelId" value="{ui:id()}" />
        <ui:button
            type="submit"
            focusableWhenDisabled="{true}"
            aria-labelledby="{submitLabelId}"
            autoMount="{false}"
            rootId="{rootId}-submit">
            <span id="{submitLabelId}">
                <ui:button.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ButtonIndicatorState::Idle')}">Register</ui:button.indicator>
                <ui:button.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ButtonIndicatorState::Loading')}">Submitting...</ui:button.indicator>
            </span>
        </ui:button>
    </ui:form.content>

    <ui:form.indicator
        state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FormState::Error')}"
        class="space-y-3">
        <h2 class="font-medium">Error</h2>
        <ui:form.errorText class="block">There was an error submitting your registration. Please try again.</ui:form.errorText>
        <ui:button type="reset" class="mt-4">
            Back to form
        </ui:button>
    </ui:form.indicator>

    <ui:form.indicator
        state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FormState::Success')}"
        class="space-y-3">
        <h2 class="font-medium">Success</h2>
        <ui:form.successText class="block">Your registration was submitted successfully. Thank you!</ui:form.successText>
    </ui:form.indicator>
</ui:form.root>

<vite:asset entry="EXT:docs/Resources/Private/Components/EventRegistration/EventRegistration.entry.ts" />

import { extbase, mount, mountAll } from 'fluid-primitives';
import { Button } from 'fluid-primitives/button';
import { Form, type FormValues } from 'fluid-primitives/form';
import { z } from 'zod';

mountAll('ui:eventRegistration', ({ props }) => {
    const submitButton = mount('ui:button', props.id + '-submit', ({ props }) =>
        new Button(props).init()
    );

    const schema = z.object({
        ticketType: z.enum(['vip', 'standard', 'student'], 'Please select a ticket type'),
        ticketCount: z.coerce
            .number('Please enter a valid number of tickets')
            .min(1, 'You must register at least 1 ticket')
            .max(10, 'You can only register up to 10 tickets'),
        donationAmount: z.coerce
            .number()
            .min(0, 'The donation amount cannot be negative')
            .max(500, 'The donation amount cannot exceed $500')
            .optional(),
        person: z.object({
            name: z.string('Please enter your name').min(1, 'Please enter your name'),
            email: z.email('Please enter your email'),
            phone: z.string().optional(),
            country: z.string('Please select your country').min(1, 'Please select your country'),
        }),
        mode: z.enum(['person', 'virtual'], 'Please select a mode of attendance'),
        studentId: z.string().optional(),
        a11yNeeds: z.array(z.string()).optional(),
        comment: z.string().optional(),
        privacy: z.literal('1', 'You must agree to the privacy policy'),
    });

    const needsStudentId = (values: FormValues) => values.get('ticketType') === 'student';

    const form = mount('ui:form', props.id + '-form', ({ props }) =>
        new Form({
            ...props,
            // We need to manually validate the schema because of the conditional logic for studentId.
            // Zod's refine or discriminatedUnion would result in inconsistent validation while the user interacts with the form
            // otherwise we could just pass the schema instead of the callback
            validation: ({ values, validateWithStandardSchema }) => {
                let errors = validateWithStandardSchema(schema);

                const hasStudentId =
                    values.get('studentId') !== null && values.get('studentId') !== '';

                if (needsStudentId(values) && !hasStudentId) {
                    errors = {
                        ...errors,
                        studentId: {
                            messages: ['You need to provide a student id for the student ticket'],
                        },
                    };
                }

                return errors;
            },
            onSubmit: async ({ api, values }) => {
                // Wait at least 800ms so we dont flash a loading state and show were working very hard
                const [response] = await Promise.all([
                    extbase.post(api.getAction(), values.toObject(), {
                        prefix: api.getFieldNamePrefix(),
                        objectName: api.getObjectName(),
                    }),
                    new Promise(resolve => setTimeout(resolve, 800)),
                ]);

                const data = await response.json();

                if (!response.ok) {
                    api.setErrorText(
                        data.message ||
                            'There was an error submitting your registration. Please try again.'
                    );
                    return false;
                }

                api.setSuccessText(
                    data.message || 'Your registration was submitted successfully. Thank you.'
                );

                return true;
            },
            render: form => submitButton?.api.setLoading(form.api.isSubmitting),
        }).init()
    );
    if (!form) return;

    // Conditionally hide and show the studentId field based on the ticket type, via `listenTo`
    // on studentId itself (see the template) rather than recomputing this on every form state
    // change. Also disables it while hidden, so it's omitted by FormData and therefore not
    // validated or passed to the server.
    const studentIdField = form.api.getField('studentId')!;

    const applyStudentIdVisibility = (show: boolean) => {
        studentIdField.getRootEl()!.hidden = !show;
        studentIdField.setDisabled(!show);
    };

    applyStudentIdVisibility(needsStudentId(form.api.getValues()));
    studentIdField.addDependencyChangeListener(({ values }) => {
        applyStudentIdVisibility(needsStudentId(values));
    });
});

<?php

declare(strict_types=1);

namespace FluidPrimitives\Docs\Controller;

use FluidPrimitives\Docs\Domain\Model\EventRegistration;
use FluidPrimitives\Docs\Domain\Repository\EventRegistrationRepository;
use FluidPrimitives\Docs\Domain\Validator\EventRegistrationValidator;
use Jramke\FluidPrimitives\Traits\JsonValidationErrorsTrait;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Core\Http\PropagateResponseException;
use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
use TYPO3\CMS\Extbase\Persistence\PersistenceManagerInterface;

final class EventRegistrationController extends ActionController
{
    use JsonValidationErrorsTrait;

    public function __construct(
        private readonly EventRegistrationRepository $eventRegistrationRepository,
        private readonly PersistenceManagerInterface $persistenceManager,
    ) {}

    public function registrationAction(
        #[Validate(validator: EventRegistrationValidator::class)]
        EventRegistration $eventRegistration,
    ): ResponseInterface {
        // Reject VIP tickets as a server-side business rule without a validator.
        // Simply moving this into the validator and calling addErrorForProperty would result in the same behavior.
        if ($eventRegistration->getTicketType() === 'vip') {
            $payload = ['eventRegistration.ticketType' => ['VIP tickets are sold out.']];
            $response = $this->jsonResponse(json_encode($payload) ?: null)->withStatus(422);
            throw new PropagateResponseException($response, 422);
        }

        $this->eventRegistrationRepository->add($eventRegistration);
        // Flushed explicitly since we escape the normal response cycle via PropagateResponseException
        // below - Extbase's own end-of-request persistAll would otherwise never run.
        $this->persistenceManager->persistAll();

        // Send confirmation email, etc.

        $response = $this->jsonResponse(
            json_encode([
                'success' => true,
                'message' => 'Your registration was submitted successfully. Thank you.',
            ]) ?: null,
        )->withStatus(200);
        throw new PropagateResponseException($response, 200);
    }
}

<?php

declare(strict_types=1);

namespace FluidPrimitives\Docs\Domain\Model;

use TYPO3\CMS\Extbase\Attribute\FileUpload;
use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;

class EventRegistration extends AbstractEntity
{
    #[Validate(validator: 'String')]
    #[Validate(validator: 'NotEmpty')]
    #[Validate(validator: 'RegularExpression', options: ['regularExpression' => '/^(vip|standard|student)$/'])]
    protected string $ticketType = '';

    #[Validate(validator: 'NumberRange', options: ['minimum' => 1, 'maximum' => 10])]
    protected int $ticketCount = 1;

    #[Validate(validator: 'NumberRange', options: ['minimum' => 0, 'maximum' => 500])]
    protected int $donationAmount = 0;

    protected EventRegistrationPerson $person;

    #[Validate(validator: 'String')]
    #[Validate(validator: 'NotEmpty')]
    #[Validate(validator: 'RegularExpression', options: ['regularExpression' => '/^(person|virtual)$/'])]
    protected string $mode = '';

    #[Validate(validator: 'String')]
    protected string $studentId = '';

    #[FileUpload(validation: [
        'fileSize' => ['maximum' => '5M'],
        'mimeType' => ['allowedMimeTypes' => ['image/jpeg', 'image/png']],
        'fileExtension' => ['allowedFileExtensions' => ['jpg', 'jpeg', 'png']],
    ], uploadFolder: '1:/user_upload/event_registrations/badge_photos/')]
    protected ?FileReference $badgePhoto = null;

    /**
     * KNOWN LIMITATION: this never round-trips through a read. Persistence writes it correctly as a
     * comma-separated string (Extbase's `getPlainValue()` implodes arrays for storage), but reading
     * it back (e.g. `$repository->findByUid()`, so an edit form can pre-check these boxes) always
     * yields an empty array, for two compounding reasons:
     * - Extbase's `DataMapper::thawProperties()` has no support at all for hydrating a plain
     *   `array`-typed property from a column (`'array' => null, // Not supported, yet!`).
     * - Renaming the backing property so it no longer collides with these `array`-typed accessors
     *   (tried: a `string $a11yNeedsRaw` + a `Configuration/Extbase/Persistence/Classes.php` column
     *   mapping) does make the DB value hydrate correctly, but then breaks *writing* instead: Extbase's
     *   `PersistentObjectConverter::getTypeOfChildProperty()` requires a property literally named
     *   `a11yNeeds` to exist on the class before it will map the submitted `a11yNeeds[]` checkbox
     *   values onto it at all, independent of that property's declared type.
     * Properly fixing this needs a custom `PropertyMappingConfiguration` (to point the converter at a
     * differently-named target property) rather than a plain property rename - out of scope for now.
     */
    /** @var array<string> */
    #[Validate(validator: 'Collection', options: ['elementValidator' => 'String'])]
    protected array $a11yNeeds = [];

    #[Validate(validator: 'Text')]
    #[Validate(validator: 'StringLength', options: ['maximum' => 500])]
    protected string $comment = '';

    #[Validate(validator: 'Boolean', options: ['is' => true])]
    protected bool $privacy = false;

    public function getTicketType(): string
    {
        return $this->ticketType;
    }

    public function setTicketType(string $ticketType): void
    {
        $this->ticketType = $ticketType;
    }

    public function getTicketCount(): int
    {
        return $this->ticketCount;
    }

    public function setTicketCount(int $ticketCount): void
    {
        $this->ticketCount = $ticketCount;
    }

    public function getDonationAmount(): int
    {
        return $this->donationAmount;
    }

    public function setDonationAmount(int $donationAmount): void
    {
        $this->donationAmount = $donationAmount;
    }

    public function getPerson(): EventRegistrationPerson
    {
        return $this->person;
    }

    public function setPerson(EventRegistrationPerson $person): void
    {
        $this->person = $person;
    }

    public function getMode(): string
    {
        return $this->mode;
    }

    public function setMode(string $mode): void
    {
        $this->mode = $mode;
    }

    public function getStudentId(): string
    {
        return $this->studentId;
    }

    public function setStudentId(string $studentId): void
    {
        $this->studentId = $studentId;
    }

    public function getBadgePhoto(): ?FileReference
    {
        return $this->badgePhoto;
    }

    public function setBadgePhoto(?FileReference $badgePhoto): void
    {
        $this->badgePhoto = $badgePhoto;
    }

    /** @return array<string> */
    public function getA11yNeeds(): array
    {
        return $this->a11yNeeds;
    }

    /** @param array<string> $a11yNeeds */
    public function setA11yNeeds(array $a11yNeeds): void
    {
        $this->a11yNeeds = $a11yNeeds;
    }

    public function getComment(): string
    {
        return $this->comment;
    }

    public function setComment(string $comment): void
    {
        $this->comment = $comment;
    }

    public function getPrivacy(): bool
    {
        return $this->privacy;
    }

    public function setPrivacy(bool $privacy): void
    {
        $this->privacy = $privacy;
    }
}

<?php

declare(strict_types=1);

namespace FluidPrimitives\Docs\Domain\Model;

use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;

class EventRegistrationPerson extends AbstractEntity
{
    #[Validate(validator: 'String')]
    #[Validate(validator: 'NotEmpty')]
    #[Validate(validator: 'StringLength', options: ['maximum' => 255])]
    protected string $name = '';

    #[Validate(validator: 'EmailAddress')]
    #[Validate(validator: 'NotEmpty')]
    #[Validate(validator: 'StringLength', options: ['maximum' => 255])]
    protected string $email = '';

    #[Validate(validator: 'String')]
    #[Validate(validator: 'StringLength', options: ['maximum' => 255])]
    protected string $phone = '';

    #[Validate(validator: 'String')]
    #[Validate(validator: 'NotEmpty')]
    protected string $country = '';

    public function getName(): string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }

    public function getEmail(): string
    {
        return $this->email;
    }

    public function setEmail(string $email): void
    {
        $this->email = $email;
    }

    public function getPhone(): string
    {
        return $this->phone;
    }

    public function setPhone(string $phone): void
    {
        $this->phone = $phone;
    }

    public function getCountry(): string
    {
        return $this->country;
    }

    public function setCountry(string $country): void
    {
        $this->country = $country;
    }
}

<?php

declare(strict_types=1);

namespace FluidPrimitives\Docs\Domain\Validator;

use FluidPrimitives\Docs\Domain\Model\EventRegistration;
use TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator;

final class EventRegistrationValidator extends AbstractValidator
{
    protected function isValid(mixed $value): void
    {
        if (!$value instanceof EventRegistration) {
            // addError will result in a full form error in the frontend
            $this->addError(
                'The ' .
                self::class .
                ' can only handle classes of type ' .
                EventRegistration::class .
                '. ' .
                // The validator framework contract guarantees an object here, just not necessarily
                // one of our expected type - that's exactly the mismatch being reported.
                // @mago-expect analysis:mixed-operand
                $value::class .
                ' given instead.',
                1782582413,
            );

            return;
        }

        if ($this->needsStudentId($value) && $value->getStudentId() === '') {
            // addErrorForProperty will result in a field error in the frontend
            $this->addErrorForProperty(
                'studentId',
                'You need to provide a student id for the student ticket',
                1782582859,
            );
        }
    }

    private function needsStudentId(EventRegistration $eventRegistration): bool
    {
        return $eventRegistration->getTicketType() === 'student';
    }
}