Extend cropVariants from sitepackage

Typo3 v12 with fluid_styled_content.

I would like to define a custom cropVariant without overwriting the default cropVariant. The reason I want to do that is to use the <f:image> view helper to load an optimally sized square preview of an image.

I thought this would work:

local_packages/mysitepackage/Configuration/TCA/Overrides/sys_file_reference.php:

<?php
defined('TYPO3') or die('Access denied.');

call_user_func(function() {
    $GLOBALS['TCA']['sys_file_reference']['columns']['crop']['config']['cropVariants']['square'] = [
        'title' => 'square',
        'allowedAspectRatios' => [
            '1:1' => [
                'title' => '1:1',
                'value' => 1.0
            ],
        ],
        'selectedRatio' => '1:1',
        'cropArea' => [
            'x' => 0.0,
            'y' => 0.0,
            'width' => 1.0,
            'height' => 1.0,
        ],
    ];
});

--> but this sadly overwrites the default cropVariant.

Additional info:

I tried merging it with the preexisting ['TCA']['sys_file_reference']['columns']['crop']['config']['cropVariants'], but it is not defined (yet) at the point in time my TCA override function is called.
I managed to hard code the original default cropVariant into my file to preserve it but obviously I would rather extend the cropVariants dynamically for future proofing reasons.
the linked source code mentions cropVariantcollections, but I could not find information about that in the docs.

Any help or hints are greatly appreciated.

Solution

Short answer

Nope, it's not possible to keep the default if custom crop variants on sys_file_reference level are defined. See below for the long answer and variant 1. generic on sys_file_reference level.

That means, you need to define it manually or define cropVariants on contentElement / field level (see also long answer below).

Long Answer - Introduction

There are basically two ways to define cropVariants:

generic on sys_file_reference level
as override for specific content element(s)

1. generic on `sys_file_reference` level

The code you provide is basically the way to define cropVariants globally for all file references.

That is documented here:

The point is, that as soon as some extensions defines cropVariants on that level, the default cropVariant is removed. Following code is responsible for this:

// see: https://github.com/TYPO3/typo3/blob/db1408d90d8b62df2b86116af55163ffcab9362b/typo3/sysext/backend/Classes/Form/Element/ImageManipulationElement.php#L228-L231

// If ratios are set do not add default options
if (isset($baseConfiguration['cropVariants'])) {
    unset($defaultConfig['cropVariants']);
}

That is by intention. That means, you need to additionally set the "default" by your own, copy&paste it as default variant in your override file from here: https://github.com/TYPO3/typo3/blob/db1408d90d8b62df2b86116af55163ffcab9362b/typo3/sysext/backend/Classes/Form/Element/ImageManipulationElement.php#L48-L85

A simplyfied example without pre-existing check from other extensions and overrides:

$GLOBALS['TCA']['sys_file_reference']['columns']['crop'] = [
  'config' => [
    'cropVariants' => [
        'default' => [
            'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.crop_variant.default',
            'allowedAspectRatios' => [
                '16:9' => [
                    'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.16_9',
                    'value' => 16 / 9,
                ],
                '3:2' => [
                    'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.3_2',
                    'value' => 3 / 2,
                ],
                '4:3' => [
                    'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
                    'value' => 4 / 3,
                ],
                '1:1' => [
                    'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.1_1',
                    'value' => 1.0,
                ],
                'NaN' => [
                    'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.free',
                    'value' => 0.0,
                ],
            ],
            'selectedRatio' => 'NaN',
            'cropArea' => [
                'x' => 0.0,
                'y' => 0.0,
                'width' => 1.0,
                'height' => 1.0,
            ],
        ], // default
        'square' => [
            'title' => 'square',
            'allowedAspectRatios' => [
                '1:1' => [
                    'title' => '1:1',
                    'value' => 1.0
                ],
            ],
            'selectedRatio' => '1:1',
            'cropArea' => [
                'x' => 0.0,
                'y' => 0.0,
                'width' => 1.0,
                'height' => 1.0,
            ],
        ], // square
    ], // cropVariants
  ], // config
];

2. as override for specific content element(s)

If you want to override or set the cropVariants on per contentElement or field level, here is the link to the documentation for that variant: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/CropVariants/ContentElement/Index.html

Here, you do not need to redefine the "default" variant, if not removed. But you can "append/change" it per content element or event disable some.

The feature needed here is called overrideChildTca. Here an example taken from the documentation for the textmexia content element and the assets field - just with your cropVariant instead of the example from the documentation:

$GLOBALS['TCA']['tt_content']['types']['textmedia']['columnsOverrides']['assets']['config']['overrideChildTca']['columns']['crop']['config'] = [
    'cropVariants' => [
       'default' => [
           'disabled' => true,
       ],
       'square' => [
            'title' => 'square',
            'allowedAspectRatios' => [
                '1:1' => [
                    'title' => '1:1',
                    'value' => 1.0
                ],
            ],
            'selectedRatio' => '1:1',
            'cropArea' => [
                'x' => 0.0,
                'y' => 0.0,
                'width' => 1.0,
                'height' => 1.0,
            ],
       ],
    ],
];