Review main Merged

90027[FEATURE] Simplify registration of custom form elements

Josua Vogel CR +2 V +2 Expert +1231 −157 updated 02/16/26, 10:45

Commit message

The registration of custom form elements in the TYPO3 Form Framework
has been significantly simplified by introducing automatic rendering
via Web Components.

Previously, registering a custom form element required:
- Custom Fluid templates in formEditorPartials configuration
- JavaScript event subscription to view/stage/abstract/render/template/perform
- Manual rendering logic implementation

With this change, custom form elements can now be registered without
any custom JavaScript or Fluid templates by simply omitting the
formEditorPartials configuration in the YAML definition.

Two new Web Components have been introduced:
- typo3-form-form-element-stage-item: Generic rendering for form elements
- typo3-form-page-stage-item: Rendering for top-level page elements

The generic Web Component automatically renders:
- Element type, identifier and label
- Required indicator and validators
- Select options with selection state
- Allowed MIME types for file uploads
- Element toolbar
- Hidden state visualization

Benefits:
- Significantly reduced complexity for custom form elements
- No JavaScript knowledge required for basic form elements
- Automatic support for common element properties
- Consistent UI across all form elements
- Easier maintenance and better extensibility

The existing formEditorPartials configuration continues to work
for custom form elements that require specialized rendering.

Review

  • Code review CR +2 Done
    • Garvin Hicking +2
    • Anja Leichsenring +1
    • Sven Liebert +1
  • Verified V +2 Done
    • Garvin Hicking +2
    • Anja Leichsenring +1
    • Sven Liebert +1
    • core-ci +1 CI

Issues 1

Files 44

Show 24 more files

Review log 5776

Show 3851 earlier messages
  1. Josua Vogel uploaded patch set 1 07/08/25, 14:18

  2. core-ci voted on patch set 1 V +1 07/08/25, 14:26 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/81494

  3. Garvin Hicking commented on patch set 1 07/08/25, 15:41

    stage-component.ts:191

    maybe for clarity we could move all these cases here instead of removing them?
  4. Sven Liebert commented on patch set 1 07/08/25, 15:45

    stage-component.ts:191 Reply

    Acknowledged
  5. Garvin Hicking commented on patch set 1 07/08/25, 15:46

    how about: Use simple template for custom EXT:form components by default
  6. Sven Liebert commented on patch set 1 07/08/25, 16:01

    stage-component.ts:191 Reply

    unresolved
  7. Josua Vogel commented on patch set 1 07/08/25, 19:45

    stage-component.ts:191 Reply

    Yes, I initially did that, but I don’t see much benefit in it. If we list the elements in addition to the default case, chances are that when someone adds a new element to ext:form, they won’t update this snippet — and the list will become incomplete.
  8. Garvin Hicking commented on patch set 1 07/08/25, 19:52

    stage-component.ts:191 Reply

    Hm, that's not my experience - I would search for existing elements and would be happy to find all places similar to the element I boilerplate. But I understand that its a subjective matter. Resolving here :)
  9. Garvin Hicking commented on patch set 1 07/08/25, 19:53

    (if we label this as a festure, we would need a Feature-rst file entry, too)
  10. Sven Liebert commented on patch set 1 07/08/25, 20:08

    Reply

    I'm not sure, but I would label it as task or even as bug, because that behaviour is weired. Some thoughts about that?
  11. Josua Vogel commented on patch set 1 07/08/25, 20:08

    Reply

    I can add one tomorrow - or should we label it as TASK?
  12. Josua Vogel updated the commit message in patch set 2 V +1 07/08/25, 20:10

  13. Josua Vogel commented on patch set 2 07/08/25, 20:10

    Reply

    Done
  14. Josua Vogel updated the commit message in patch set 3 07/08/25, 20:14

  15. Josua Vogel commented on patch set 3 07/08/25, 20:15

    Reply

    Relabeled as TASK, because it´s just a small improvement, no real feature (although it makes the developer / integrator life easier).
  16. core-ci voted on patch set 2 V +1 07/08/25, 20:17 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/81498

  17. core-ci voted on patch set 3 V +1 07/08/25, 20:21 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/81499

  18. Sven Liebert voted on patch set 3 CR +1 V +1 07/08/25, 20:57

  19. Benjamin Franzke commented on patch set 3 CR -1 07/11/25, 06:55

    stage-component.ts:190

    The `default` case must not perform any rendering, since it's documented that custom types shall trigger the desired rendering in the event (publishsubscriber that is triggered after this switch block) in their own. See https://docs.typo3.org/permalink/typo3-cms-form:apireference-formeditor-basicjavascriptconcepts-events-view-stage-abstract-render-template-perform Especially: https://docs.typo3.org/c/typo3/cms-form/13.4/en-us/D/FormEditor/Index.html#view-stage-abstract-render-template-perform:~:text=getFormEditorApp().getViewModel().getStage().renderSelectTemplates(args%5B0%5D%2C%20args%5B1%5D)%3B That means all core types that should render via `renderSimpleTemplateWithValidators` need to be listed explicitly as already desired by Garvin https://review.typo3.org/c/Packages/TYPO3.CMS/+/90027/comment/beb33d38_80cf0cf6/
  20. Josua Vogel commented on patch set 3 07/11/25, 07:41

    stage-component.ts:190 Reply

    Thank you for your feedback! I would like to simplify the process. I know some developers (myself included) who find it complicated to add a new form element. The documentation is complex, a newbie can't find this place. If you need a custom stage component, the event is great. In most cases, however, the SimpleTemplate is sufficient. Do you have an alternative idea to simplify it for developers?
  21. Benjamin Franzke commented on patch set 3 07/15/25, 08:25

    stage-component.ts:190 Reply

    I'm sorry, but I have no idea :( I understand the desire for simplification, but the problem basically is the status quo: We have no signal, whether a custom component was/will be rendered in the `'view/stage/abstract/render/template/perform'` event, therefore this change does not just add a "default", but the rendering is *always* triggered, and there is no way for developers to opt-out from this "default"-rendering. The "best" idea I could come up with would be to replace the `formEditorPartials` concept by a new one, where php-based-backend templating and js-based-hydration are streamlined to be always in sync, instead of relying on descriptive form configuration and imperative JS to properly work together. That could ideally be pure js-based rendering and no fluid templates, but I would not touch existing `formEditorPartials` and `'view/stage/abstract/render/template/perform'` rendering flow, but consider that as a legacy part that is rather to be replaced in the long term, without breaking it short term.
  22. Josua Vogel commented on patch set 3 07/15/25, 09:52

    stage-component.ts:190 Reply

    Discussed: Check whether you can implement a new way, similar to the (site) settings types. These also only receive data (the settings definition) and the current value.
  23. Josua Vogel uploaded patch set 4 CR +1 V +1 01/20/26, 16:11

  24. core-ci voted on patch set 4 V +1 01/20/26, 16:20 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/93876

  25. Josua Vogel commented on patch set 4 01/20/26, 16:24

    stage-component.ts:190 Reply

    @ben@bnf.dev I'm currently working on this topic again because I want to simplify the creation of new FormElement types (probably hardly anyone finds the JS part great or intuitive). As you can see in the WIP, a web component is being introduced to replace the Stage template. The templates are all structured quite similarly, so in my opinion, they can be easily mapped in a component. The web component is always rendered if there is no “formEditorPartials: FormElement-DatePicker: Stage/SimpleTemplate” (or similar) part in the YAML configuration. Less configuration for everyone. If someone wants to render their own template, the YAML part is ignored as before and the event is fired. What do you think?
  26. Josua Vogel uploaded patch set 5 V +1 01/23/26, 11:11

  27. core-ci voted on patch set 5 V -1 01/23/26, 11:26 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/94155

  28. Josua Vogel uploaded patch set 6 V -1 01/23/26, 11:58

  29. Josua Vogel uploaded patch set 7 01/23/26, 12:05

  30. Josua Vogel commented on patch set 7 01/23/26, 12:07

    stage-component.ts:190 Reply

    Done
  31. core-ci voted on patch set 6 V -1 01/23/26, 12:09 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/94163

  32. core-ci voted on patch set 7 V +1 01/23/26, 12:15 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/94164

  33. Josua Vogel marked it work in progress 01/23/26, 12:17

  34. Josua Vogel uploaded patch set 8 V +1 01/26/26, 09:50

  35. core-ci voted on patch set 8 V +1 01/26/26, 09:58 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/94351

  36. Josua Vogel uploaded patch set 9 V +1 01/26/26, 10:41

  37. Josua Vogel marked it ready for review 01/26/26, 10:48

  38. core-ci voted on patch set 9 V +1 01/26/26, 10:49 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/94352

  39. Sven Liebert voted on patch set 9 CR +1 V +1 01/28/26, 12:06

  40. Georg Ringer voted on patch set 9 CR +1 V +1 01/29/26, 18:38

  41. Georg Ringer commented on patch set 9 CR -1 02/06/26, 18:53

    please provide a **working** example in the docs (linked in the rst), how it is done. as extending form is always not a pleasure! it would be also interesting if it is "just" for own elements or also custom finishers
  42. Josua Vogel uploaded patch set 10 CR +1 V +1 02/06/26, 20:11

  43. Josua Vogel uploaded patch set 11 02/06/26, 20:12

  44. core-ci voted on patch set 10 V -1 02/06/26, 20:20 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95342

  45. Josua Vogel uploaded patch set 12 02/06/26, 20:25

  46. core-ci voted on patch set 11 V -1 02/06/26, 20:25 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95343

  47. core-ci voted on patch set 12 V +1 02/06/26, 20:33 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95344

  48. Josua Vogel commented on patch set 12 02/06/26, 20:36

    Reply

    It´s only for own form elements, I added a "How To". The only fundamental change is that you don't need JavaScript if you provide your own element.
  49. Josua Vogel uploaded patch set 13 V +1 02/06/26, 20:39

  50. core-ci voted on patch set 13 V +1 02/06/26, 20:47 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95345

  51. Garvin Hicking commented on patch set 12 02/06/26, 20:57

    I LOVE that you took the initiative to add a howto. I firmly believe we need this. I need this 🙃 I have a few "damn you docs guy!" comments and hope you can bear with me. We can also do a followup, but everything we fixate now helps for this patch to be reviewable. Thanks!

    Index.rst:5

    Please line up the equal signs to the text

    Index.rst:6

    Please use sentence case (no uppercasing), in all headlines here

    Index.rst:22

    please use "sitepackage" as the established term

    Index.rst:28

    ```suggestion defines how the element behaves in both form editor and frontend. ```

    Index.rst:33

    ```suggestion Create the following file in your extension (also create the directories if they do not yet exist): ```

    Index.rst:35

    ```suggestion :file:`EXT:my_extension/Configuration/Form/CustomFormSetup.yaml` ``` Please use "my_extension" which we try to use commonly in the docs

    Index.rst:49

    When I read "editors" I often think of "people who do editing" or "IDE". Could you maybe explain this term or link to the form docs where it is established? Do we have a terminology section, I only found "concepts" but these are huge pages and they did not seem to explain what "editors" are (other than the sectoons "For Editors", and you don't mean that)

    Index.rst:92

    ```suggestion After adding the configuration, you must clear all TYPO3 caches. ``` (Just to be sure that there is no form/specific cache)

    Index.rst:98

    With the earlier section I would think there are multiple editors like "Form editor", thats where confusion could happen. So here it helps that you exactly describe whst you refer to.

    Index.rst:99

    ```suggestion 1. Open the Form Editor (:guilabel:`Forms > [Your Form] > Edit`) ```

    Index.rst:104

    "Via the top bar button" or so?

    Index.rst:120

    Use .fluid.html extension

    Index.rst:133

    you can use ":emphasize-lines:" to highlight the key lines here

    Index.rst:149

    ```suggestion If you want to make the options editable in the form editor (instead of using hard-codes values within your YAML), add this editor ```

    Index.rst:153

    Please mention filename to be sure

    Index.rst:167

    Emphassize these lines

    Index.rst:172

    Maybe explain "grid editor", terminology?

    _CustomFormSetup.yaml:14

    Thanks for being inclusive here, that means a lot. Maybe also add "does not matter" or so for extra care :)

    _CustomFormSetup.yaml:21

    Could you add a bit of inline comments here, maybe also say why the options are container twice in here and not just once

    _CustomFormSetup.yaml:27

    (I really think having this element called "editors" is a major source of confusion for me, Kuch more than "fieldExplanationText" 🤓)

    _CustomFormSetup.yaml:34

    Maybe explain why is it label.label 🤪

    _GenderSelect.html:3

    Could you maybe add <f:comment> lines here that roughly(!) explain the sections? Also maybe more spacing for sections so that it looks less intimidating?

    locallang_formEditor_javascript.xlf:2

    ease use snake case for filenames "form_editor_javascript"
  1. Josua Vogel commented on patch set 14 V +1 02/06/26, 21:10

    Published edit on patch set 13.
  2. Josua Vogel commented on patch set 14 02/06/26, 21:12

    Index.rst:28 Reply

    Fix applied.

    Index.rst:33 Reply

    Fix applied.

    Index.rst:35 Reply

    Fix applied.

    Index.rst:92 Reply

    Fix applied.

    Index.rst:99 Reply

    Fix applied.
  3. core-ci voted on patch set 14 V +1 02/06/26, 21:19 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95347

  4. Josua Vogel uploaded patch set 15 V +1 02/10/26, 14:25

  5. Josua Vogel commented on patch set 15 02/10/26, 14:25

    Index.rst:5 Reply

    Done

    Index.rst:6 Reply

    Done

    Index.rst:22 Reply

    Done

    Index.rst:49 Reply

    Done

    Index.rst:98 Reply

    Done

    Index.rst:104 Reply

    Done

    Index.rst:120 Reply

    Done

    Index.rst:133 Reply

    Done

    Index.rst:149 Reply

    Done

    Index.rst:153 Reply

    Done

    Index.rst:167 Reply

    Done

    Index.rst:172 Reply

    Done

    _CustomFormSetup.yaml:14 Reply

    Done

    _CustomFormSetup.yaml:21 Reply

    Done

    _CustomFormSetup.yaml:27 Reply

    Acknowledged

    _CustomFormSetup.yaml:34 Reply

    Done

    _GenderSelect.html:3 Reply

    Done

    locallang_formEditor_javascript.xlf:2 Reply

    Done
  6. core-ci voted on patch set 15 V +1 02/10/26, 14:34 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95555

  7. Josua Vogel commented on patch set 16 V +1 02/11/26, 15:49

    Published edit on patch set 15.
  8. core-ci voted on patch set 16 V +1 02/11/26, 15:58 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95635

  9. Sven Liebert voted on patch set 16 CR +1 V +1 02/11/26, 16:54

  10. Anja Leichsenring commented on patch set 16 CR +1 V +1 02/11/26, 19:26

    very nice improvement, thank you Josua.
  11. Garvin Hicking commented on patch set 16 02/12/26, 11:44

    Feature-107058-SimplifyRegistrationOfCustomFormElement.rst:60

    ```suggestion :ref:`Creating a Custom Form Element <typo3/cms-form:howtos-custom-form-element>`. ```
  12. Garvin Hicking commented on patch set 16 V -1 02/12/26, 11:52

    Now that "fieldExplanationText" change has been merged, the docs and example core are wrong for this and need adaptation. In the inspector I only see an empty label: formEditor.elements.FormElement.editor.gridColumnViewPortConfiguration.numbersOfColumnsToUse.fieldExplanationText but not any contents. Is that a breaking change related to that merged patch for other custom integrations then that needs inspection (and a separate fixup, or here?) I uploaded a screenshot into the issue.
  13. Josua Vogel uploaded patch set 17 CR +1 V +1 02/12/26, 13:12

  14. Josua Vogel commented on patch set 17 02/12/26, 13:12

    Feature-107058-SimplifyRegistrationOfCustomFormElement.rst:60 Reply

    Fix applied.
  15. Josua Vogel commented on patch set 18 02/12/26, 13:12

    Published edit on patch set 17.
  16. core-ci voted on patch set 17 V +1 02/12/26, 13:26 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95726

  17. core-ci voted on patch set 18 V -1 02/12/26, 13:28 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95727

  18. Josua Vogel uploaded patch set 19 V -1 02/12/26, 13:37

  19. Josua Vogel commented on patch set 19 02/12/26, 13:38

    Reply

    changed the how-to / example
  20. core-ci voted on patch set 19 V +1 02/12/26, 14:21 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95731

  21. Anja Leichsenring voted on patch set 19 CR +1 V +1 02/12/26, 19:20

  22. Josua Vogel commented on patch set 19 02/12/26, 21:00

    Reply

    Short notice: As discussed with Garvin, I added the removed labels as a drive-by and marked them as unused (so there won't be any problems due to possible breaking changes).
  23. Sven Liebert voted on patch set 19 CR +1 V +1 02/12/26, 21:43

  24. Garvin Hicking voted on patch set 19 CR +2 V +2 02/16/26, 10:44

  25. Garvin Hicking merged patch set 20 02/16/26, 10:45