Review main Merged

81319[TASK] Document pitfalls between f:(uri.)image vs f:uri.resource

Garvin Hicking CR +2 V +2 Easy +26 −0 updated 11/20/23, 16:47

Commit message

Review

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

Issues 1

Files 3

Review log 3240

Show 1215 earlier messages
  1. Garvin Hicking uploaded patch set 1 10/04/23, 12:33

  2. Garvin Hicking uploaded patch set 2 10/04/23, 12:36

  3. core-ci voted on patch set 1 V -1 10/04/23, 12:42 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47396

  4. core-ci voted on patch set 2 V +1 10/04/23, 12:44 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47397

  5. Mathias Brodala commented on patch set 2 10/04/23, 12:47

    ImageViewHelper.php:32

    > This viewhelper should only be used for images within FAL storages. > For extension resource files use f:uri.resource instead.

    ResourceViewHelper.php:32

    > This viewhelper should be used for extension resource files. > For images within FAL storages use f:uri.image instead.
  6. Garvin Hicking uploaded patch set 3 V +1 10/04/23, 12:49

  7. Garvin Hicking commented on patch set 3 10/04/23, 12:50

    Thanks for the much better wording improvement, implemented.

    ImageViewHelper.php:32 Reply

    Done

    ResourceViewHelper.php:32 Reply

    Done
  8. core-ci voted on patch set 3 V +1 10/04/23, 12:57 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47399

  9. Oliver Klee commented on patch set 3 V +1 10/04/23, 13:13

    Looks very good in general! I've commented on some smaller punctuation and formatting issues.

    ImageViewHelper.php:32

    ``` For extension resource files, use `f:uri.resource` instead. ```

    ResourceViewHelper.php:32

    ``` For images within FAL storages, use `f:uri.image` instead. ```
  10. Lina Wolf commented on patch set 3 10/04/23, 13:40

    ImageViewHelper.php:32 Reply

    I would actually link the viewhelper to be really usefull: :ref:`f:uri.resource <typo3-fluid-uri-resource>`
  11. Oliver Klee commented on patch set 3 10/04/23, 15:08

    ImageViewHelper.php:32 Reply

    I'm not sure if ReST works in PHPDoc (when it's displayed on GitHub). Maybe we can add an `@see` annotation instead with the URL to the docs.
  12. Lina Wolf commented on patch set 3 10/04/23, 15:23

    ImageViewHelper.php:32 Reply

    Such comments would not be rendered in the ViewHelper reference. And we are using rst all over here
  13. Oliver Klee commented on patch set 3 10/04/23, 15:50

    ImageViewHelper.php:32 Reply

    I'm confused: I had assumed that the class PHPDoc of the view helpers would only be rendered on GitHub (when you look at the source code), but the view helper reference at https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/Index.html is not directly sourced from the VH class PHPDoc. Is my assumption incorrect?
  14. Lina Wolf commented on patch set 3 10/04/23, 15:53

    ImageViewHelper.php:32 Reply

    The ViewHelper Reference is rendered by https://github.com/TYPO3-Documentation/fluid-documentation-generator based on these doc comments
  15. Garvin Hicking commented on patch set 3 10/04/23, 15:54

    ImageViewHelper.php:32 Reply

    Another thing about using rst there: Tools like phpstoem wouldnt render that. I'd be in favor of either not using a link there or really just using an absolute link in there (which might break, so... I'm afraid there's no solution which would work in all of github, spginx and IDEs...?
  1. Oliver Klee commented on patch set 3 10/04/23, 16:03

    ImageViewHelper.php:32 Reply

    Ah, I see. I've learned something here - Thanks for the explanations! Then I reduce my suggestion to adding the missing commas.
  2. Simon Praetorius commented on patch set 3 V -1 10/04/23, 16:14

    For most cases, I agree with that documentation change. However, there are valid cases where you would use f:uri.image with images that are not in FAL. Maybe we can adjust the sentence to cover this? One example that comes to mind is to have a fallback image in an extension which will be scaled down or cropped in the template. In that case, you would use f:uri.image with an EXT: path instead of f:uri.resource.

    ImageViewHelper.php:32 Reply

    I think that it would make more sense to use rst references here, because this is already implemented in the automatic documentation rendering and rst is used for other parts of the ViewHelper documentation (e. g. code examples). It also can be used inline in the text, not separately like @see. Regarding @see I'm not sure if it is a good idea to put absolute documentation links in the code. Is that used anywhere else in the core?
  3. Garvin Hicking uploaded patch set 4 V +1 10/04/23, 17:38

  4. Garvin Hicking commented on patch set 4 10/04/23, 17:40

    Reply

    Done
    I tried to add a :ref: insertion, not sure how I can test how it's applied. Also I reworded it a bit to address Simons good remarks, and placed, some, commas. Hope this comes closer to a satisfiable result. :-)

    ImageViewHelper.php:32 Reply

    Done

    ResourceViewHelper.php:32 Reply

    Done
  5. core-ci voted on patch set 4 V -1 10/04/23, 17:45 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47408

  6. Garvin Hicking uploaded patch set 5 V -1 10/04/23, 17:48

  7. core-ci voted on patch set 5 V +1 10/04/23, 17:55 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47409

  8. Simon Praetorius commented on patch set 5 10/04/23, 19:30

    Apart from the typo, this is now fine by me. Good addition to the documentation. 😊

    ImageViewHelper.php:33

    typo: resoure => resource
  9. Mathias Brodala commented on patch set 5 10/05/23, 06:51

    Reply

    No, you should never use f:uri.image for EXT: paths. The simple reason being that your image will lead to a FAL record which is never updated again afterwards. Thus if you e.g. replace the image with one having different dimensions, these will not be respected and your image will be rendered distorted. You will need to either manually update the FAL record or drop it.
  10. Lina Wolf commented on patch set 5 10/05/23, 06:54

    Reply

    This sounds like a Core Bug and not a documentation issue to me. Why don't you open a bug report?
  11. Garvin Hicking uploaded patch set 6 V +1 10/05/23, 07:07

  12. Garvin Hicking commented on patch set 6 10/05/23, 07:08

    Reply

    Hm. I'd argue though the normal use case would be that static assets won't change, and if they do, they get a different name? So the more common use case would be to scale a non-changing static asset? Also it probably can be fixed be rremoving the processed image cache, so this should not block you from being able to resize image assets? I'd personally also rather file a "bug" or feature request so that the image generation needs to check the file hash, and use that to decide if an existing FAL record can be (re)used. I even believe a file hash is already existing? As for then, I've updated the note again to indicate this...?

    ImageViewHelper.php:33 Reply

    Done
  13. core-ci voted on patch set 6 V -1 10/05/23, 07:14 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47416

  14. Garvin Hicking uploaded patch set 7 V -1 10/05/23, 07:17

  15. core-ci voted on patch set 7 V +1 10/05/23, 07:24 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47417

  16. Stefan Bürk commented on patch set 7 10/05/23, 12:32

    Reply

    *.image ViewHelper should not deal with non-fal image resources. Helmut has already stated that in other patches and discussions. However, no-one took the time to depreacte/remove the non-fal support out of these helpers. For non-fal resources the *.resource ViewHelper should be used. Image processing is bound to FAL, and the buggy and flacky non-fal support needs to vanish. That means, there is no valid case for *.image to use with non fal images.
  17. Garvin Hicking commented on patch set 7 10/05/23, 12:51

    Reply

    OK, but then this definitely needs to be documentat at that point! So the docs need to mention that and say "manually create asset variants". IMO this is very important to be documented, I did not know this.
  18. Simon Praetorius commented on patch set 7 10/05/23, 12:52

    Reply

    Ok, I wasn't aware of these plans. I found a forge ticket that describes the planned changes for v13: https://forge.typo3.org/issues/101608 It would be interesting which alternative solutions exist for the "default image" example described above. For example, the news extension does exactly that: https://github.com/georgringer/news/blob/main/Configuration/TypoScript/setup.typoscript#L154 https://github.com/georgringer/news/blob/main/Resources/Private/Partials/List/Item.html#L43
  19. Garvin Hicking uploaded patch set 8 V +1 10/11/23, 07:17

  20. Garvin Hicking commented on patch set 8 10/11/23, 07:18

    @Mathias Brodala @Stefan Bürk Thank you for the additional feedback on these non-FAL operations. Personally I think, the TYPO3 Core must provide a supported way to perform cropping, scaling and converting also static assets, be it from within an extension, or by editors specifying asset locations. This is a task that a Framework-like system needs to provide, especially if it already gets used (i.e. EXT:news) and most people are not aware of the pitfalls. To adress these pitfalls, the documentation MUST be improved on this and indicate this, to educate people that this may change. Especially because the current `<f:image>` documentation specifically gives examples to operate on non-FAL images. IMO it would be perfectly fine to remove image operations on non-FAL files from the `<f:image>` viewhelper, and make it solely operate on FAL images. But then, a `<f:resource>` viewhelper would be needed that can perform the same operations on non-FAL assets. Before this non-FAL operations get "silently" dropped, please let us put a workable alternative without pitfalls into effect, I'd be happy to help, but am missing in-depth FAL knowledge here. Since it is part of the v13 initiative, maybe this can be factored in. I updated my patch to try to find a wording expressing these thoughts.
  21. core-ci voted on patch set 8 V +1 10/11/23, 07:25 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/47673

  22. Christian Kuhn commented on patch set 8 V +1 CR +1 11/20/23, 15:42

    Reply

    Ack

    Reply

    Ack
  23. Simon Praetorius voted on patch set 8 V +1 CR +1 11/20/23, 15:51

  24. Christian Kuhn voted on patch set 8 V +2 CR +2 11/20/23, 15:58

  25. Christian Kuhn merged patch set 9 11/20/23, 16:47