Review main Merged

88557[DOCS] Unify VH descriptions, move examples to Fluid Reference

Lina Wolf CR +2 V +2 Nightmare +778 −2208 updated 04/15/25, 19:34

Commit message

This patch performs no code changes.

The phpDoc blocks of each ViewHelper class are updated:

- Streamlined wording, beginning with "ViewHelper which does/formats X"
- Only provide a very basic example, linking to docs.typo3.org for more
- Be more precise in short descriptions
- Use markdown code blocks so that IDEs can better display them
- Use bold "Notes" instead of (not interpreted) ReST
- Remove specific ReST attribution like :html:, :php:, :file: which is
  not rendered in markdown

The idea of this patch is that properly formatted examples will
be maintained in the TYPO3 docs at [1], keeping the code in the
core repository clean and simple. Still, developers are able to
see a very brief usage examples.

Changes in ViewHelper arguments or new features will need to
be brought up to the Documentation team, or a Changelog feature/important
ReST file will trigger the documentation workflow of updating
the documentation about them.

The XSD schema generation of ViewHelpers allows developers to see
argument hinting within their IDE. Tooltips of IDEs like PHPStorm
will present class usage with a clickable "@see" link, directly
leading to the docs (see issue screenshot [2]). Code blocks are
now properly formatted/highlighted.

[1] https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/Index.html
[2] https://forge.typo3.org/attachments/39526

Review

  • Code review CR +2 Done
    • Garvin Hicking +2
    • Christian Kuhn +1
  • Verified V +2 Done
    • Garvin Hicking +2
    • Christian Kuhn +1
    • core-ci +1 CI

Issues 1

Files 105

Show 85 more files

Review log 4354

Show 2329 earlier messages
  1. Lina Wolf uploaded patch set 1 03/10/25, 13:55

  2. Lina Wolf marked it work in progress 03/10/25, 13:56

  3. core-ci voted on patch set 1 V -1 03/10/25, 14:01 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/75419

  4. Lina Wolf uploaded patch set 2 V -1 03/12/25, 13:34

  5. Lina Wolf marked it ready for review 03/12/25, 13:36

  6. Lina Wolf updated the commit message in patch set 3 03/12/25, 13:37

  7. core-ci voted on patch set 2 V +1 03/12/25, 13:40 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/75511

  8. core-ci voted on patch set 3 V +1 03/12/25, 13:43 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/75512

  9. Georg Ringer voted on patch set 3 CR +1 V +1 03/13/25, 20:59

  10. Garvin Hicking commented on patch set 3 03/13/25, 21:01

    backport note: we should probably attach @13.4 to the permalink URL, right @112@linawolf.de ? Is this patch finished from your side?
  11. Lina Wolf commented on patch set 3 03/15/25, 16:08

    Reply

    The patch is finished. I would not suggest to edit the comments for back versions, Development is usually done in in main versions so only there developers will click the links directly from the code. Changed comments would just increase the likely hood of conflicts during backport
  12. Benni Mack commented on patch set 3 CR -1 03/17/25, 10:58

    Reply

    I do not understand why this change should be merged into main & 12.4 but NOT in 13.4. Can you elaborate this?
  13. Lina Wolf updated the commit message in patch set 4 CR +1 V +1 03/17/25, 11:10

  14. Lina Wolf commented on patch set 4 03/17/25, 11:11

    Reply

    duh, was living in the past. 13.4 of course
  15. core-ci voted on patch set 4 V +1 03/17/25, 11:19 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/75708

  16. Jörg Bösche voted on patch set 4 CR +1 03/24/25, 09:00

  17. Garvin Hicking commented on patch set 4 CR -1 03/28/25, 13:32

    I see two problems with this: 1. Some Viewhelpers have unneeded examples (be.pageInfo), there it's ok to remove examples. But for others I would now have to lookup a URL outside my IDE to see usage info - I always found it helpful to see inline basic examples. So maybe we could leave some simple examples in?! 2. What do we do for patches that change viewhelpers? Must contributors create a docs patch explaining this? will it be unexplained until the docs team addresses it? Would it need a Rst entry every time a VH is enhanced with an attribute? I think maybe the easiest way is to keep all current docs and just insert the link. Docs will start to differ in their content, that's the downside. I see no fully ideal variant here. Thoughts?
  18. Lina Wolf commented on patch set 4 03/29/25, 07:37

    Reply

    We already had this discussion in https://review.typo3.org/c/Packages/TYPO3.CMS/+/88555. I rolled this out across all Core ViewHelpers on the grounds that you already agreed on the general course. A Fluid ViewHelper (in the TYPO3 Core) can in future just be handled like any other Core change. A short description and definition of all arguments within the class itself. A changelog entry with some examples. Uppon writing the docs we enhance these examples and make them closer to the reality of integrators. This principle works fine for other features as well. If you absolutely want to stay within the Core you can find these examples in the Core Changelog then. Also if you look at the examples in detail you will see that many are outdated. Most of them reflect a Core developers point of view and are hard to understand for integrators. Compare for example https://docs.typo3.org/other/typo3/view-helper-reference/13.4/en-us/Global/FlashMessages.html (written manually) and https://docs.typo3.org/other/typo3/view-helper-reference/12.4/en-us/Global/FlashMessages.html (still from the Core).
  19. Lina Wolf commented on patch set 4 03/29/25, 07:43

    Reply

    Done
  20. Garvin Hicking commented on patch set 4 CR 0 03/29/25, 08:32

    Reply

    Thanks for the response. I must admit I only understood the full consequences of this when seeing so many useful examples removed. I think if we iterate on this we will achieve a better DX and workflow. i've explicitly now commented where I think we should keep basic examples and what can be easily removed. Of course I can be overruled/overvoted and will not be blocking.

    ActionMenuItemViewHelper.php:40

    Let's keep the examples here (without descriptions/text)?

    ActionMenuViewHelper.php:38

    keep basic examples, no text

    PageInfoViewHelper.php:36

    good to remove

    PagePathViewHelper.php:37

    good to remove

    PageRendererViewHelper.php:38

    keep basic examples, no text

    IfAuthenticatedViewHelper.php:35

    good to remove

    IfHasRoleViewHelper.php:35

    keep basic examples, no text

    TableListViewHelper.php:52

    keep this example

    UriViewHelper.php:30

    keep basic examples, no text

    DebugViewHelper.php:43

    keep basic examples, no text

    FeatureViewHelper.php:37

    keep basic examples, no text

    FlashMessagesViewHelper.php:80

    keep basic examples, no text

    ButtonViewHelper.php:37

    keep basic examples, no text

    CheckboxViewHelper.php:42

    keep basic examples, no text

    CountrySelectViewHelper.php:37

    keep basic examples, no text

    CountrySelectViewHelper.php:69

    keep this example, less text

    HiddenViewHelper.php:28

    keep basic examples, no text

    PasswordViewHelper.php:28

    keep basic examples, no text

    RadioViewHelper.php:42

    keep basic examples, no text

    SelectViewHelper.php:33

    keep basic examples, less text

    SubmitViewHelper.php:42

    keep basic examples, no text

    TextareaViewHelper.php:30

    keep basic examples, no text

    TextfieldViewHelper.php:28

    keep basic examples, no text

    UploadDeleteCheckboxViewHelper.php:40

    keep basic examples, no text

    UploadViewHelper.php:30

    keep basic examples, no text

    ValidationResultsViewHelper.php:58

    keep basic example here, no text

    FormViewHelper.php:62

    keep basic examples, no text - maybe we need to include all the params for a full example

    BytesViewHelper.php:57

    keep basic examples, no text

    CropViewHelper.php:74

    keep basic examples, no text

    CurrencyViewHelper.php:44

    keep basic examples, no text

    DateViewHelper.php:38

    keep all basic examples, less text

    HtmlViewHelper.php:57

    keep basic examples, no text

    HtmlentitiesDecodeViewHelper.php:32

    keep basic examples, no text

    HtmlentitiesViewHelper.php:24

    good to remove

    PaddingViewHelper.php:57

    keep basic examples, no text

    ImageViewHelper.php:40

    keep all basic examples, less text

    ActionViewHelper.php:35

    we might want to provide a full argument list example here

    EmailViewHelper.php:36

    imo very self explanatory, good to remove

    ExternalViewHelper.php:25

    imo self explanatory, good to remove

    FileViewHelper.php:42

    keep basic examples, no text

    PageViewHelper.php:39

    keeo a "ull argument" example here, no text

    TypolinkViewHelper.php:76

    keep basic examples, small text keeping the typolink format description

    MediaViewHelper.php:65

    keep basic example, no text

    HtmlViewHelper.php:34

    imo self explanatory, good to remove

    IfAuthenticatedViewHelper.php:28

    good to remove

    IfHasRoleViewHelper.php:37

    keep one example for named and uid role each

    NonceViewHelper.php:35

    keep basic example, no text. also link to CSP docs?

    HtmlViewHelper.php:34

    keep basic examples, no text

    TranslateViewHelper.php:34

    keeo some basic variants with "key", no text

    ActionViewHelper.php:39

    keep basic example, no text

    ExternalViewHelper.php:26

    imo self explanatory, good to remove

    ImageViewHelper.php:61

    keep basic examples, no text

    PageViewHelper.php:58

    keep example with full params, no text

    ResourceViewHelper.php:45

    keep basic examples with full args, no text

    ResourceViewHelper.php:64

    keep this sentence

    TypolinkViewHelper.php:33

    maybe add a mention to f:typolinkviewhelper so that all examples can be removed here
  21. Lina Wolf commented on patch set 4 03/29/25, 08:38

    NonceViewHelper.php:35 Reply

    Extended docs such as a link to CSP docs belong in the documentation in my eyes?
  22. Lina Wolf marked it work in progress 04/01/25, 11:13

  23. Lina Wolf commented on patch set 4 04/01/25, 11:14

    Talked to Garvin and He would prefere to keep basic examples. He will make a suggestion, so putting this on WIP for now
  24. Garvin Hicking commented on patch set 4 04/01/25, 11:18

    Reply

    Thanks. I've also tried to get a hold of the core team and hear their input on this before I begin to spent much time on this.
  25. Garvin Hicking uploaded patch set 5 CR +1 V +1 04/09/25, 13:48

  26. Garvin Hicking commented on patch set 5 04/09/25, 13:50

    This change is ready for review.

    Reply

    We had a 4:1 vote on using this patch, keeping simple examples. See updated patchset.

    Reply

    Done

    ActionMenuItemViewHelper.php:40 Reply

    Done

    ActionMenuViewHelper.php:38 Reply

    Done

    PageInfoViewHelper.php:36 Reply

    Done

    PagePathViewHelper.php:37 Reply

    Done

    PageRendererViewHelper.php:38 Reply

    Done

    IfAuthenticatedViewHelper.php:35 Reply

    Done

    IfHasRoleViewHelper.php:35 Reply

    Done

    TableListViewHelper.php:52 Reply

    Done

    UriViewHelper.php:30 Reply

    Done

    DebugViewHelper.php:43 Reply

    Done

    FeatureViewHelper.php:37 Reply

    Done

    FlashMessagesViewHelper.php:80 Reply

    Done

    ButtonViewHelper.php:37 Reply

    Done

    CheckboxViewHelper.php:42 Reply

    Done

    CountrySelectViewHelper.php:37 Reply

    Done

    CountrySelectViewHelper.php:69 Reply

    Done

    HiddenViewHelper.php:28 Reply

    Done

    PasswordViewHelper.php:28 Reply

    Done

    RadioViewHelper.php:42 Reply

    Done

    SelectViewHelper.php:33 Reply

    Done

    SubmitViewHelper.php:42 Reply

    Done

    TextareaViewHelper.php:30 Reply

    Done

    TextfieldViewHelper.php:28 Reply

    Done

    UploadDeleteCheckboxViewHelper.php:40 Reply

    Done

    UploadViewHelper.php:30 Reply

    Done

    ValidationResultsViewHelper.php:58 Reply

    Done

    FormViewHelper.php:62 Reply

    Done

    BytesViewHelper.php:57 Reply

    Done

    CropViewHelper.php:74 Reply

    Done

    CurrencyViewHelper.php:44 Reply

    Done

    DateViewHelper.php:38 Reply

    Done

    HtmlViewHelper.php:57 Reply

    Done

    HtmlentitiesDecodeViewHelper.php:32 Reply

    Done

    HtmlentitiesViewHelper.php:24 Reply

    Done

    PaddingViewHelper.php:57 Reply

    Done

    ImageViewHelper.php:40 Reply

    Done

    ActionViewHelper.php:35 Reply

    Done

    EmailViewHelper.php:36 Reply

    Done

    ExternalViewHelper.php:25 Reply

    Done

    FileViewHelper.php:42 Reply

    Done

    PageViewHelper.php:39 Reply

    Done

    TypolinkViewHelper.php:76 Reply

    Done

    MediaViewHelper.php:65 Reply

    Done

    HtmlViewHelper.php:34 Reply

    Done

    IfAuthenticatedViewHelper.php:28 Reply

    Done

    IfHasRoleViewHelper.php:37 Reply

    Done

    NonceViewHelper.php:35 Reply

    Done

    HtmlViewHelper.php:34 Reply

    Done

    TranslateViewHelper.php:34 Reply

    Done

    ActionViewHelper.php:39 Reply

    Done

    ExternalViewHelper.php:26 Reply

    Done

    ImageViewHelper.php:61 Reply

    Done

    PageViewHelper.php:58 Reply

    Done

    ResourceViewHelper.php:45 Reply

    Done

    ResourceViewHelper.php:64 Reply

    Done

    TypolinkViewHelper.php:33 Reply

    Done
  27. core-ci voted on patch set 5 V +1 04/09/25, 13:57 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/77284

  28. Garvin Hicking uploaded patch set 6 V +1 04/09/25, 15:00

  29. core-ci voted on patch set 6 V +1 04/09/25, 15:06 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/77292

  1. Christian Kuhn voted on patch set 6 CR +1 V +1 04/09/25, 15:47

  2. Garvin Hicking commented on patch set 6 CR -1 04/09/25, 15:51

    (Just setting a blocker for merging this, I need/want Linas approval for this before rolling this out, mostly to be sure that the changes will have no negative impact on the Fluid reference rendering or the API docs)
  3. Garvin Hicking commented on patch set 7 CR +1 V +1 04/10/25, 07:21

    Published edit on patch set 6.
  4. core-ci voted on patch set 7 V +1 04/10/25, 07:31 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/77393

  5. Lina Wolf commented on patch set 7 CR +1 V +1 04/10/25, 07:32

    From the ViewHelper Reference and API docs point of view this is a good solution
  6. Garvin Hicking commented on patch set 7 CR -1 04/10/25, 07:59

    doing the other VHs too now
  7. Garvin Hicking uploaded patch set 8 CR +1 V +1 04/10/25, 08:26

  8. core-ci voted on patch set 8 V +1 04/10/25, 08:33 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/77403

  9. Garvin Hicking commented on patch set 8 CR +1 V +1 04/10/25, 13:57

    Reply

    Done

    Reply

    Done
  10. Lina Wolf voted on patch set 8 CR +1 V +1 04/10/25, 13:58

  11. Christian Kuhn voted on patch set 8 CR +1 V +1 04/10/25, 18:08

  12. Garvin Hicking voted on patch set 8 CR +2 04/10/25, 18:09

  13. Garvin Hicking voted on patch set 8 CR +1 04/11/25, 06:19

  14. Garvin Hicking rebased onto patch set 9 CR +1 V +1 04/11/25, 15:41

    The following files contain Git conflicts: * typo3/sysext/redirects/Classes/ViewHelpers/TargetPageIdViewHelper.php
  15. Garvin Hicking commented on patch set 10 04/11/25, 15:42

    Published edit on patch set 9.
  16. Garvin Hicking marked it ready for review 04/11/25, 15:43

  17. core-ci voted on patch set 10 V +1 04/11/25, 15:55 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/77555

  18. core-ci voted on patch set 9 V -1 04/11/25, 16:02 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/77554

  19. Garvin Hicking commented on patch set 10 CR -1 04/11/25, 16:04

    needs to adapt the renamed TargetPageRecordVH from TargetPageIdVH earlier now due to https://review.typo3.org/89045
  20. Garvin Hicking uploaded patch set 11 CR -1 V +1 04/15/25, 18:36

  21. Garvin Hicking commented on patch set 11 CR +1 V +1 04/15/25, 18:38

    Reply

    Done
  22. core-ci voted on patch set 11 V +1 04/15/25, 18:42 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/77774

  23. Christian Kuhn voted on patch set 11 CR +1 V +1 04/15/25, 19:08

  24. Garvin Hicking voted on patch set 11 CR +2 V +2 04/15/25, 19:34

  25. Garvin Hicking merged patch set 12 04/15/25, 19:34