Back to Index / back to README
Learn the usage of CropVariants Builder by reading the code examples! You get a good overview just by comparing with/-out the builder:
- Example 1: Set a global default cropVariants configuration: Global/Default cropVariants configuration for TYPO3 instance
- Example 2: Set custom cropVariants for a specific field of a specific table (
pages.tx_my_nice_site_extension_nav_image): Custom cropVariants configuration for a specific field of a specific table - Example 3: Set custom cropVariants for
tx_news_domain_model_news.fal_media - Example 4: Set custom cropVariants for
tt_content.imagefor CTypetx_my_nice_site_extension_custom_ce1
The CropVariants Builder uses centralized configured defaults and presets:
- aspectRatio presets
- coverArea presets
- Predefined focusAreas
- cropArea presets
- List of default cropVariants
The code examples shown in Example 1 can be seen as the content of files
in your own site package extension named my_nice_site_extension.
The "default" cropVariants configuration is set as a project default. 6 allowed aspect ratios are configured in this example.
The downside:
- All options are set without defaults
- writing the configuration is error-prone (because you have no autocompletion)
- the cropArea is set manually (no centralized preset)
- allowed aspect ratios are set manually (no centralized presets)
- manual title option string
EXT:my_nice_site_extension/Configuration/TCA/Overrides/sys_file_reference.php:
<?php
defined('TYPO3') || die('Access denied.');
call_user_func(
static function ($extKey, $table) {
$languageFileBePrefix = 'LLL:EXT:' . $extKey . '/Resources/Private/Language/locallang_be.xlf:';
$tca = [
'columns' => [
'crop' => [
'config' => [
'cropVariants' => [
'default' => [
'title' => $languageFileBePrefix . 'crop_variants.default.label',
'coverAreas' => [],
'cropArea' => [
'x' => '0.0',
'y' => '0.0',
'width' => '1.0',
'height' => '1.0'
],
'allowedAspectRatios' => [
'3:2' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.3_2',
'value' => 3 / 2
],
'2:3' => [
'title' => '2:3',
'value' => 2 / 3
],
'4:3' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
'value' => 4 / 3
],
'3:4' => [
'title' => '3:4',
'value' => 3 / 4
],
'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'
],
],
],
],
]
];
$GLOBALS['TCA'][$table] = array_replace_recursive($GLOBALS['TCA'][$table], $tca);
},
'my_nice_site_extension',
'sys_file_reference'
);imageManipulation:
cropVariants:
defaults:
#################################################################################
### Set default cropVariants for sys_file_reference.columns.crop
###
### Each cropVariant must have a minimum of one aspectRatio
### for sys_file_reference.columns.crop
### (Look for "persistToDefaultTableTca")
###
defaultCropVariantsConfiguration:
default:
aspectRatios:
- "3:2"
- "2:3"
- "4:3"
- "3:4"
- "1:1"
- "NaN"If you want to use a custom aspectRatio for the defaults, you just have to configure it in the same YAML configuration file!
Example 2: Set custom cropVariants for a specific field of a specific table (pages.tx_my_nice_site_extension_nav_image)
EXT:my_nice_site_extension/Configuration/TCA/Overrides/pages.php
A common usecase: You add a custom field to the pages table and want a
custom cropVariants configuration for this particular field. The TYPO3
editor can add 1 image per page and have to set 3 crops for breakpoint
xs'n'up, md'n'up and lg'n'up. All three with same allowed aspectRatios.
The downside:
- All options are set without defaults and aren't configured centralized
- writing the configuration is error-prone (because you have no autocompletion)
- cropAreas are always set manually (no centralized preset, no automatic fallback to default cropArea)
- e.g. if you add some additional cropVariant for the project as default, you have to disable the new default cropVariant here (and in every other file)
- allowed aspect ratios are set manually (no centralized presets)
- cropVariant title LLL string isn't automatically fetched from you xliff file by convention
<?php
defined('TYPO3') || die('Access denied.');
call_user_func(
static function ($extKey, $table) {
$languageFileBePrefix = 'LLL:EXT:' . $extKey . '/Resources/Private/Language/locallang_BackendGeneral.xlf:';
$additionalColumns = [
'tx_my_nice_site_extension_nav_image' => [
'exclude' => true,
'label' => $languageFileBePrefix . 'field.pages.tx_my_nice_site_extension_nav_image.label',
'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig('tx_my_nice_site_extension_nav_image', [
'overrideChildTca' => [
'types' => [
\TYPO3\CMS\Core\Resource\File::FILETYPE_IMAGE => [
'showitem' => '
alternative,title,
--linebreak--,crop,
--palette--;;filePalette',
'columnsOverrides' => [],
],
],
'columns' => [
'crop' => [
'config' => [
'cropVariants' => [
'default' => [
'disabled' => true
],
'xs' => [
'title' => $languageFileBePrefix . 'crop_variants.xs.label',
'coverAreas' => [],
'cropArea' => [
'x' => '0.0',
'y' => '0.0',
'width' => '1.0',
'height' => '1.0'
],
'allowedAspectRatios' => [
'4:3' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
'value' => 4 / 3
],
],
],
'md' => [
'title' => $languageFileBePrefix . 'crop_variants.md.label',
'coverAreas' => [],
'cropArea' => [
'x' => '0.0',
'y' => '0.0',
'width' => '1.0',
'height' => '1.0'
],
'allowedAspectRatios' => [
'4:3' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
'value' => 4 / 3
],
],
],
'lg' => [
'title' => $languageFileBePrefix . 'crop_variants.lg.label',
'coverAreas' => [],
'cropArea' => [
'x' => '0.0',
'y' => '0.0',
'width' => '1.0',
'height' => '1.0'
],
'allowedAspectRatios' => [
'4:3' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
'value' => 4 / 3
],
],
],
],
],
],
],
],
'maxitems' => 1,
],
$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']
)
],
];
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns($table, $additionalColumns);
},
'my_nice_site_extension',
'pages'
);The advantages:
- add cropVariants configuration after adding the custom TCA column
- Enjoy IDE auto completion
- 32 lines of code less
- easy to read
- add cropVariants with much fewer lines of code
- finally persist the cropVariants configuration with a oneliner
(
persistToTca()) - combine other cropVariants configurations to this code block, so you have a good overview
<?php
defined('TYPO3') || die('Access denied.');
call_user_func(
static function ($extKey, $table) {
$languageFileBePrefix = 'LLL:EXT:' . $extKey . '/Resources/Private/Language/locallang_BackendGeneral.xlf:';
$additionalColumns = [
'tx_my_nice_site_extension_nav_image' => [
'exclude' => true,
'label' => $languageFileBePrefix . 'field.pages.tx_my_nice_site_extension_nav_image.label',
'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig('tx_my_nice_site_extension_nav_image', [
'overrideChildTca' => [
'types' => [
\TYPO3\CMS\Core\Resource\File::FILETYPE_IMAGE => [
'showitem' => '
alternative,title,
--linebreak--,crop,
--palette--;;filePalette',
'columnsOverrides' => [],
],
],
],
'maxitems' => 1,
],
$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']
)
],
];
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns($table, $additionalColumns);
/**
* Set cropVariants configuration
*/
\JosefGlatz\CropVariantsBuilder\Builder::getInstance($table, 'tx_my_nice_site_extension_nav_image')
->disableDefaultCropVariants()
->addCropVariant(
\JosefGlatz\CropVariantsBuilder\CropVariant::create('xs')
->addAllowedAspectRatios(\JosefGlatz\CropVariantsBuilder\Defaults\AspectRatio::get(['4:3']))
->get()
)
->addCropVariant(
\JosefGlatz\CropVariantsBuilder\CropVariant::create('md')
->addAllowedAspectRatios(\JosefGlatz\CropVariantsBuilder\Defaults\AspectRatio::get(['4:3']))
->get()
)
->addCropVariant(
\JosefGlatz\CropVariantsBuilder\CropVariant::create('lg')
->addAllowedAspectRatios(\JosefGlatz\CropVariantsBuilder\Defaults\AspectRatio::get(['4:3']))
->get()
)
->persistToTca();
},
'my_nice_site_extension',
'pages'
);EXT:my_nice_site_extension/Configuration/TCA/Overrides/tx_news_domain_model_news.php
A common usecase: You want to configure cropVariants for the fal_media
column of EXT:news. The default cropVariant was removed and two new
cropVariants was added. The first is called teaser with one
aspectRatio 3:2. The other one called teaser-big-md with one
aspectRatio 16:9.
The two different cropVariants are used for a news list design, where not every news item has the same aspect ratio.
<?php
defined('TYPO3') || die('Access denied.');
call_user_func(
static function ($extKey, $table) {
/**
* Set cropVariants configuration with EXT:cropvariantsbuilder
*/
\JosefGlatz\CropVariantsBuilder\Builder::getInstance($table, 'fal_media')
->disableDefaultCropVariants()
->addCropVariant(
\JosefGlatz\CropVariantsBuilder\CropVariant::create('teaser')
->setCropArea(\JosefGlatz\CropVariantsBuilder\Defaults\CropArea::get())
->addAllowedAspectRatios(\JosefGlatz\CropVariantsBuilder\Defaults\AspectRatio::get(['3:2']))
->get()
)
->addCropVariant(
\JosefGlatz\CropVariantsBuilder\CropVariant::create('teaser-big-md')
->setCropArea(\JosefGlatz\CropVariantsBuilder\Defaults\CropArea::get())
->addAllowedAspectRatios(\JosefGlatz\CropVariantsBuilder\Defaults\AspectRatio::get(['16:9']))
->get()
)
->persistToTca();
},
'my_nice_site_extension',
'tx_news_domain_model_news'
);Example 4: Set custom cropVariants for tt_content.image for CType tx_my_nice_site_extension_custom_ce1
EXT:my_nice_site_extension/Configuration/TCA/Overrides/tt_content_custom_ce1.php
A common usecase: You want a custom cropVariants configuration for a
content element (CType)
tx_my_nice_site_extension_custom_ce1 for the column
tt_content.image.
<?php
defined('TYPO3') || die('Access denied.');
call_user_func(
static function ($extKey, $table, $type) {
/**
* Set cropVariants configuration with EXT:cropvariantsbuilder
*/
\JosefGlatz\CropVariantsBuilder\Builder::getInstance($table, 'image', $type)
->disableDefaultCropVariants()
->addCropVariant(
\JosefGlatz\CropVariantsBuilder\CropVariant::create('xs')
->addAllowedAspectRatios(\JosefGlatz\CropVariantsBuilder\Defaults\AspectRatio::get(['1:1']))
->setCropArea(\JosefGlatz\CropVariantsBuilder\Defaults\CropArea::get())
->get()
)
->addCropVariant(
\JosefGlatz\CropVariantsBuilder\CropVariant::create('md')
->addAllowedAspectRatios(\JosefGlatz\CropVariantsBuilder\Defaults\AspectRatio::get(['3:2']))
->setCropArea(\JosefGlatz\CropVariantsBuilder\Defaults\CropArea::get())
->get()
)
->addCropVariant(
\JosefGlatz\CropVariantsBuilder\CropVariant::create('lg')
->addAllowedAspectRatios(\JosefGlatz\CropVariantsBuilder\Defaults\AspectRatio::get(['16:9']))
->setCropArea(\JosefGlatz\CropVariantsBuilder\Defaults\CropArea::get())
->get()
)
->persistToTca();
},
'my_nice_site_extension',
'tt_content',
'tx_my_nice_site_extension_custom_ce1'
);