Image manipulation 

New in version 13.0

The type "imageManipulation" generates a button showing an image cropper in the backend for image files. It is typically only used in FAL relations. The crop information is stored as an JSON array into the field.

The according database field is generated automatically.

Table of contents:

Example: A basic image manipulation field 

EXT:my_extension/Configuration/TCA/tx_myextension_mytable.php 
<?php

return [
  'ctrl' => [
    'title' => 'My table',
    'label' => 'my_image_manipulation',
  ],
  'columns' => [
    'my_image_manipulation' => [
      'label' => 'LLL:my_extension.db:my_image_manipulation',
      'config' => [
        'type' => 'imageManipulation',
        // The default crop variants of the core are used
      ],
    ],

    'crop_area' => [
      'label' => 'Crop variant field',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'cropArea' => [
              'x' => 0.1,
              'y' => 0.1,
              'width' => 0.8,
              'height' => 0.8,
            ],
          ],
        ],
      ],
    ],

    'focus_area' => [
      'label' => 'Crop variant field with a focus area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'focusArea' => [
              'x' => 1 / 3,
              'y' => 1 / 3,
              'width' => 1 / 3,
              'height' => 1 / 3,
            ],
          ],
        ],
      ],
    ],

    'cover_area' => [
      'label' => 'Crop variant field with a cover area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'coverAreas' => [
              [
                'x' => 0.05,
                'y' => 0.85,
                'width' => 0.9,
                'height' => 0.1,
              ],
            ],
          ],
        ],
      ],
    ],

    'multiple' => [
      'label' => 'Field with multiple crop variants',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
          'desktop' => [
            'title' => 'LLL:my_extension.db:imageManipulation.desktop',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
        ],
      ],
    ],
  ],
  'types' => [
    '0' => [
      'showitem' => 'my_image_manipulation',
    ],
  ],
];
Copied!

Properties of the TCA column type imageManipulation 

Name Type Scope
allowedExtensions
 string (list of file extensions) Display / Proc.
behaviour
allowLanguageSynchronization
 boolean Proc.
cropVariants
 array Display / Proc.
fieldControl
elementBrowser
 array Display
fieldInformation
fieldWizard
defaultLanguageDifferences
 array
localizationStateSelector
 array
otherLanguageContent
 array
file_field
 string (field name) Display / Proc.
readOnly
 boolean Display
allowedExtensions
Type
string (list of file extensions)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['allowedExtensions']
Scope
Display / Proc.

List of image types (by file extension) which can be cropped. Defaults to $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'] which is usually gif,jpg,jpeg,png.

behaviour
allowLanguageSynchronization
Type
boolean
Default
false
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
Scope
Proc.

Allows an editor to select in a localized record whether the value is copied over from default or source language record, or if the field has an own value in the localization. If set to true and if the table supports localization and if a localized record is edited, this setting enables FieldWizard LocalizationStateSelector: Two or three radio buttons shown below the field input. The state of this is stored in a json encoded array in the database table called l10n_state. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.

EXT:my_extension/Configuration/TCA/Overrides/tx_myextension_mytable.php 
<?php

defined('TYPO3') or die();

$GLOBALS['TCA']['tx_myextension_mytable']['columns']['my_image']['config']
  ['behaviour']['allowLanguageSynchronization'] = true;
Copied!
cropVariants
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['cropVariants']
Scope
Display / Proc.

Main crop, focus area and cover area configuration. For details see crop variants.

fieldControl

The field of type imageManipulation can enable all common field control options. Furthermore the following are available:

elementBrowser
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']['elementBrowser']
Scope
Display

The element browser field control used in type='imageManipulation' renders a button to open an element browser to choose a imageManipulation.

It is enabled by default if rendering a imageManipulation element.

fieldInformation

For details see fieldInformation.

fieldWizard
defaultLanguageDifferences
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']

For details see defaultLanguageDifferences.

localizationStateSelector
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']

For details see localizationStateSelector.

otherLanguageContent
Type
array
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']

For details see otherLanguageContent.

file_field
Type
string (field name)
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['file_field']
Scope
Display / Proc.

Name of the database field that contains the uid of the file record. By default set to uid_local.

readOnly
Type
boolean
TCA path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['readOnly']
Scope
Display

Renders the field in a way that the user can see the value but cannot edit it.

Image manipulation: Crop variants 

If no cropVariants are configured, the following default configuration is used:

EXT:backend/Classes/Form/Element/ImageManipulationElement.php (excerpt) 
'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,
      ],
    ],
    'excludeFromSync' => false,
    'selectedRatio' => 'NaN',
    'cropArea' => [
      'x' => 0.0,
      'y' => 0.0,
      'width' => 1.0,
      'height' => 1.0,
    ],
  ],
],
Copied!

Define multiple crop variants 

It is possible to define multiple crop variants. The array key is used as identifier for the ratio and the label is specified with the "title" and the actual (floating point) ratio with the "value" key. The value must be of PHP type float, not only a string.

EXT:my_extension/Configuration/TCA/tx_myextension_mytable.php 
<?php

return [
  'ctrl' => [
    'title' => 'My table',
    'label' => 'my_image_manipulation',
  ],
  'columns' => [
    'my_image_manipulation' => [
      'label' => 'LLL:my_extension.db:my_image_manipulation',
      'config' => [
        'type' => 'imageManipulation',
        // The default crop variants of the core are used
      ],
    ],

    'crop_area' => [
      'label' => 'Crop variant field',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'cropArea' => [
              'x' => 0.1,
              'y' => 0.1,
              'width' => 0.8,
              'height' => 0.8,
            ],
          ],
        ],
      ],
    ],

    'focus_area' => [
      'label' => 'Crop variant field with a focus area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'focusArea' => [
              'x' => 1 / 3,
              'y' => 1 / 3,
              'width' => 1 / 3,
              'height' => 1 / 3,
            ],
          ],
        ],
      ],
    ],

    'cover_area' => [
      'label' => 'Crop variant field with a cover area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'coverAreas' => [
              [
                'x' => 0.05,
                'y' => 0.85,
                'width' => 0.9,
                'height' => 0.1,
              ],
            ],
          ],
        ],
      ],
    ],

    'multiple' => [
      'label' => 'Field with multiple crop variants',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
          'desktop' => [
            'title' => 'LLL:my_extension.db:imageManipulation.desktop',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
        ],
      ],
    ],
  ],
  'types' => [
    '0' => [
      'showitem' => 'my_image_manipulation',
    ],
  ],
];
Copied!

Define initial crop area 

It is also possible to define an initial crop area. If no initial crop area is defined, the default selected crop area will cover the complete image. Crop areas are defined relatively with floating point numbers. The x and y coordinates and width and height must be specified for that. The below example has an initial crop area in the size the previous image cropper provided by default.

EXT:my_extension/Configuration/TCA/tx_myextension_mytable.php 
<?php

return [
  'ctrl' => [
    'title' => 'My table',
    'label' => 'my_image_manipulation',
  ],
  'columns' => [
    'my_image_manipulation' => [
      'label' => 'LLL:my_extension.db:my_image_manipulation',
      'config' => [
        'type' => 'imageManipulation',
        // The default crop variants of the core are used
      ],
    ],

    'crop_area' => [
      'label' => 'Crop variant field',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'cropArea' => [
              'x' => 0.1,
              'y' => 0.1,
              'width' => 0.8,
              'height' => 0.8,
            ],
          ],
        ],
      ],
    ],

    'focus_area' => [
      'label' => 'Crop variant field with a focus area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'focusArea' => [
              'x' => 1 / 3,
              'y' => 1 / 3,
              'width' => 1 / 3,
              'height' => 1 / 3,
            ],
          ],
        ],
      ],
    ],

    'cover_area' => [
      'label' => 'Crop variant field with a cover area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'coverAreas' => [
              [
                'x' => 0.05,
                'y' => 0.85,
                'width' => 0.9,
                'height' => 0.1,
              ],
            ],
          ],
        ],
      ],
    ],

    'multiple' => [
      'label' => 'Field with multiple crop variants',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
          'desktop' => [
            'title' => 'LLL:my_extension.db:imageManipulation.desktop',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
        ],
      ],
    ],
  ],
  'types' => [
    '0' => [
      'showitem' => 'my_image_manipulation',
    ],
  ],
];
Copied!

Add a focus area 

Users can also select a focus area, when configured. The focus area is always inside the crop area and marks the area in the image which must be visible for the image to transport its meaning. The selected area is persisted to the database but will have no effect on image processing. The data points are however made available as data attribute when using the <f:image /> view helper.

The below example adds a focus area, which is initially one third of the size of the image and centered.

EXT:my_extension/Configuration/TCA/tx_myextension_mytable.php 
<?php

return [
  'ctrl' => [
    'title' => 'My table',
    'label' => 'my_image_manipulation',
  ],
  'columns' => [
    'my_image_manipulation' => [
      'label' => 'LLL:my_extension.db:my_image_manipulation',
      'config' => [
        'type' => 'imageManipulation',
        // The default crop variants of the core are used
      ],
    ],

    'crop_area' => [
      'label' => 'Crop variant field',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'cropArea' => [
              'x' => 0.1,
              'y' => 0.1,
              'width' => 0.8,
              'height' => 0.8,
            ],
          ],
        ],
      ],
    ],

    'focus_area' => [
      'label' => 'Crop variant field with a focus area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'focusArea' => [
              'x' => 1 / 3,
              'y' => 1 / 3,
              'width' => 1 / 3,
              'height' => 1 / 3,
            ],
          ],
        ],
      ],
    ],

    'cover_area' => [
      'label' => 'Crop variant field with a cover area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'coverAreas' => [
              [
                'x' => 0.05,
                'y' => 0.85,
                'width' => 0.9,
                'height' => 0.1,
              ],
            ],
          ],
        ],
      ],
    ],

    'multiple' => [
      'label' => 'Field with multiple crop variants',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
          'desktop' => [
            'title' => 'LLL:my_extension.db:imageManipulation.desktop',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
        ],
      ],
    ],
  ],
  'types' => [
    '0' => [
      'showitem' => 'my_image_manipulation',
    ],
  ],
];
Copied!

Define cover areas 

Very often images are used in a context, where they are overlaid with other DOM elements, like a headline. To give editors a hint which area of the image is affected, when selecting a crop area, it is possible to define multiple so called cover areas. These areas are shown inside the crop area. The focus area cannot intersect with any of the cover areas.

EXT:my_extension/Configuration/TCA/tx_myextension_mytable.php 
<?php

return [
  'ctrl' => [
    'title' => 'My table',
    'label' => 'my_image_manipulation',
  ],
  'columns' => [
    'my_image_manipulation' => [
      'label' => 'LLL:my_extension.db:my_image_manipulation',
      'config' => [
        'type' => 'imageManipulation',
        // The default crop variants of the core are used
      ],
    ],

    'crop_area' => [
      'label' => 'Crop variant field',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'cropArea' => [
              'x' => 0.1,
              'y' => 0.1,
              'width' => 0.8,
              'height' => 0.8,
            ],
          ],
        ],
      ],
    ],

    'focus_area' => [
      'label' => 'Crop variant field with a focus area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'focusArea' => [
              'x' => 1 / 3,
              'y' => 1 / 3,
              'width' => 1 / 3,
              'height' => 1 / 3,
            ],
          ],
        ],
      ],
    ],

    'cover_area' => [
      'label' => 'Crop variant field with a cover area',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'coverAreas' => [
              [
                'x' => 0.05,
                'y' => 0.85,
                'width' => 0.9,
                'height' => 0.1,
              ],
            ],
          ],
        ],
      ],
    ],

    'multiple' => [
      'label' => 'Field with multiple crop variants',
      'config' => [
        'type' => 'imageManipulation',
        'cropVariants' => [
          'mobile' => [
            'title' => 'LLL:my_extension.db:imageManipulation.mobile',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
          'desktop' => [
            'title' => 'LLL:my_extension.db:imageManipulation.desktop',
            'allowedAspectRatios' => [
              '4:3' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.4_3',
                'value' => 4 / 3,
              ],
              'NaN' => [
                'title' => 'LLL:core.wizards:imwizard.ratio.free',
                'value' => 0.0,
              ],
            ],
          ],
        ],
      ],
    ],
  ],
  'types' => [
    '0' => [
      'showitem' => 'my_image_manipulation',
    ],
  ],
];
Copied!

The above configuration examples are basically meant to add one single cropping configuration to sys_file_reference, which will then apply in every record, which reference images.

Configuration per content element 

It is however also possible to provide a configuration per content element, e.g. for tt_content images:

EXT:my_extension/Configuration/TCA/Overrides/tt_content.php 
<?php

defined('TYPO3') or die();

$GLOBALS['TCA']['tt_content']['columns']['image']['config']
  ['overrideChildTca']['columns']['crop']['config'] = [
    'cropVariants' => [
      'mobile' => [
        'title' => 'LLL:my_extension.db:imageManipulation.mobile',
        'cropArea' => [
          'x' => 0.1,
          'y' => 0.1,
          'width' => 0.8,
          'height' => 0.8,
        ],
      ],
    ],
  ];
Copied!

Define a cropping configuration for a specific content element 

It is also possible to set the cropping configuration only for a specific content element type:

EXT:my_extension/Configuration/TCA/Overrides/tt_content.php 
<?php

defined('TYPO3') or die();

$GLOBALS['TCA']['tt_content']['types']['textpic']['columnsOverrides']
  ['image']['config']['overrideChildTca']['columns']['crop']['config'] = [
    'cropVariants' => [
      'mobile' => [
        'title' => 'LLL:my_extension.db:imageManipulation.mobile',
        'cropArea' => [
          'x' => 0.1,
          'y' => 0.1,
          'width' => 0.8,
          'height' => 0.8,
        ],
      ],
    ],
  ];
Copied!

Disable a crop variant 

Please note, that while the array for overrideChildTca is merged with the child TCA, the crop variants replace those defined in the child TCA (most likely sys_file_reference), as long as the default configuration is in use. If however the crop variants have already been overriden in the child TCA, the crop variants are merged.

Because you cannot remove crop variants easily, it is possible to disable them for certain field types by setting the array key for a crop variant disabled to the value true

Disable an aspect ratio 

Not only cropVariants but also aspect ratios can be disabled by adding a disabled key to the array.

EXT:my_extension/Configuration/TCA/Overrides/tt_content.php 
<?php

defined('TYPO3') or die();

$GLOBALS['TCA']['tt_content']['types']['textmedia']['columnsOverrides']
  ['assets']['config']['overrideChildTca']['columns']['crop']['config'] = [
    'cropVariants' => [
      'default' => [
        'allowedAspectRatios' => [
          '4:3' => [
            'disabled' => true,
          ],
        ],
      ],
    ],
  ];
Copied!

Crop variants in ViewHelpers 

To render crop variants, the variants can be specified as argument to the image ViewHelpers:

<f:image image="{data.image}" cropVariant="mobile" width="800" />
Copied!