TYPO3: Using image crop variants with focus and cover areas

TYPO3 provides a sophisticated image manipulation wizard, that allows editors to choose image cropping and focus areas while making sure no important information is covered. While I often used the crop wizard itself, I never really configured the other two (focus and cover areas). Today, while reviewing documentation pull requests, I stumbled over the brand new docs - and decided to give it a try.

This is my basic custom card content element:

I created the content element following the guides at https://usetypo3.com/custom-fsc-element.html and https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/ApiOverview/ContentElements/AddingYourOwnContentElements.html

As you can see, it contains an image with a headline on top - a "classic" case for using a cover area. When an editor adds new images, we want to make sure she doesn't accidentally position the image in a way where the headline covers anything important. As this is pretty specific to this content element type, I'll try to add the configuration only for the card element. This is what I want to achieve:

And this is how we do it - in an extension of your choice (mostly: use the one where you also defined the corresponding content element) add the following in Configuration/TCA/Overrides/tt_content.php:

$GLOBALS['TCA']['tt_content']['types']['card']['columnsOverrides']['assets']['config']['overrideChildTca']['columns']['crop']['config'] = [
    'cropVariants' => [
        'default' => [
            'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.crop_variant.default',
            'cropArea' => [
                'x' => 0.1,
                'y' => 0.1,
                'width' => 0.8,
                'height' => 0.8,
            'focusArea' => [
                'x' => 1 / 3,
                'y' => 1 / 3,
                'width' => 1 / 3,
                'height' => 1 / 3,
            'coverAreas' => [
                    'x' => 0,
                    'y' => 0.8,
                    'width' => 0.8,
                    'height' => 0.1,
            'allowedAspectRatios' => [
                '4:3' => [
                    'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
                    'value' => 4 / 3

This overwrites the default cropping configuration for this specific content element (card) via overrideChildTca. It configures a 4:3 ratio for the cropping, configures a default crop area, a centered focus area and a cover area corresponding to the frontend CSS used to render the headline onto the image.

Basically, this works pretty well, however, you need to do a bit of math to get the values right (or you do it like me and just kind of guess until it looks ok 🙃).

And this is how it looks in the frontend after we applied the cropping:

That's it. Check out the new docs and kudos to Henrik who wrote them.

Example libraries with focus point / area functionality are