Image manipulation

New in version 13.0

When using the imageManipulation type, TYPO3 takes care of generating the according database field. A developer does not need to define this field in an extension's ext_tables.sql file.

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

The file references of the core have a field of type imageManipulation. Every image in a field of type file shows it, for example the photo of a speaker:

The button that opens the image editor for the photo of a speaker

EXT:core/Configuration/TCA/sys_file_reference.php (excerpt)

'crop' => [
    'label' => 'LLL:EXT:core/Resources/Private/Language/locallang_tca.xlf:sys_file_reference.crop',
    'config' => [
        'type' => 'imageManipulation',
    ],
],

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/155-tx_myextension_conference-media.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'logo' => [
    'label' => 'my_extension.db:conference.logo',
    'config' => [
      'type' => 'file',
      'maxitems' => 1,
      'allowed' => 'common-image-types',
      'relationship' => 'manyToOne',
    ],
  ],
  'impressions' => [
    'label' => 'my_extension.db:conference.impressions',
    'config' => [
      'type' => 'file',
      'allowed' => 'common-image-types',
      'overrideChildTca' => [
        'columns' => [
          'crop' => [
            'config' => [
              'cropVariants' => [
                'desktop' => [
                  'title' => 'my_extension.db:conference.impressions.desktop',
                  'allowedAspectRatios' => [
                    '16:9' => [
                      'title' => 'core.wizards:imwizard.ratio.16_9',
                      'value' => 16 / 9,
                    ],
                    'NaN' => [
                      'title' => 'core.wizards:imwizard.ratio.free',
                      'value' => 0.0,
                    ],
                  ],
                ],
                'mobile' => [
                  'title' => 'my_extension.db:conference.impressions.mobile',
                  'allowedAspectRatios' => [
                    '4:3' => [
                      'title' => 'core.wizards:imwizard.ratio.4_3',
                      'value' => 4 / 3,
                    ],
                  ],
                  // Initially the middle of the image, without the edges
                  'cropArea' => [
                    'x' => 0.1,
                    'y' => 0.1,
                    'width' => 0.8,
                    'height' => 0.8,
                  ],
                ],
              ],
              // A translated image keeps the crop of the default language,
              // unless the editors crop it anew
              'behaviour' => [
                'allowLanguageSynchronization' => true,
              ],
            ],
          ],
        ],
      ],
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_conference']['palettes']['media'] = [
  'showitem' => 'logo, impressions',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  '--palette--;;media',
  '',
  'before:--div--;core.form.tabs:categories',
);

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.

Warning

This property affects only the display. It is still possible to write to those fields when using the DataHandler.

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,
    ],
  ],
],

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.

The impressions of a conference can be cropped for the desktop and for mobile devices:

        EXT:my_extension/Configuration/TCA/Overrides/155-tx_myextension_conference-media.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'logo' => [
    'label' => 'my_extension.db:conference.logo',
    'config' => [
      'type' => 'file',
      'maxitems' => 1,
      'allowed' => 'common-image-types',
      'relationship' => 'manyToOne',
    ],
  ],
  'impressions' => [
    'label' => 'my_extension.db:conference.impressions',
    'config' => [
      'type' => 'file',
      'allowed' => 'common-image-types',
      'overrideChildTca' => [
        'columns' => [
          'crop' => [
            'config' => [
              'cropVariants' => [
                'desktop' => [
                  'title' => 'my_extension.db:conference.impressions.desktop',
                  'allowedAspectRatios' => [
                    '16:9' => [
                      'title' => 'core.wizards:imwizard.ratio.16_9',
                      'value' => 16 / 9,
                    ],
                    'NaN' => [
                      'title' => 'core.wizards:imwizard.ratio.free',
                      'value' => 0.0,
                    ],
                  ],
                ],
                'mobile' => [
                  'title' => 'my_extension.db:conference.impressions.mobile',
                  'allowedAspectRatios' => [
                    '4:3' => [
                      'title' => 'core.wizards:imwizard.ratio.4_3',
                      'value' => 4 / 3,
                    ],
                  ],
                  // Initially the middle of the image, without the edges
                  'cropArea' => [
                    'x' => 0.1,
                    'y' => 0.1,
                    'width' => 0.8,
                    'height' => 0.8,
                  ],
                ],
              ],
              // A translated image keeps the crop of the default language,
              // unless the editors crop it anew
              'behaviour' => [
                'allowLanguageSynchronization' => true,
              ],
            ],
          ],
        ],
      ],
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_conference']['palettes']['media'] = [
  'showitem' => 'logo, impressions',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  '--palette--;;media',
  '',
  'before:--div--;core.form.tabs:categories',
);

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/Overrides/155-tx_myextension_conference-media.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'logo' => [
    'label' => 'my_extension.db:conference.logo',
    'config' => [
      'type' => 'file',
      'maxitems' => 1,
      'allowed' => 'common-image-types',
      'relationship' => 'manyToOne',
    ],
  ],
  'impressions' => [
    'label' => 'my_extension.db:conference.impressions',
    'config' => [
      'type' => 'file',
      'allowed' => 'common-image-types',
      'overrideChildTca' => [
        'columns' => [
          'crop' => [
            'config' => [
              'cropVariants' => [
                'desktop' => [
                  'title' => 'my_extension.db:conference.impressions.desktop',
                  'allowedAspectRatios' => [
                    '16:9' => [
                      'title' => 'core.wizards:imwizard.ratio.16_9',
                      'value' => 16 / 9,
                    ],
                    'NaN' => [
                      'title' => 'core.wizards:imwizard.ratio.free',
                      'value' => 0.0,
                    ],
                  ],
                ],
                'mobile' => [
                  'title' => 'my_extension.db:conference.impressions.mobile',
                  'allowedAspectRatios' => [
                    '4:3' => [
                      'title' => 'core.wizards:imwizard.ratio.4_3',
                      'value' => 4 / 3,
                    ],
                  ],
                  // Initially the middle of the image, without the edges
                  'cropArea' => [
                    'x' => 0.1,
                    'y' => 0.1,
                    'width' => 0.8,
                    'height' => 0.8,
                  ],
                ],
              ],
              // A translated image keeps the crop of the default language,
              // unless the editors crop it anew
              'behaviour' => [
                'allowLanguageSynchronization' => true,
              ],
            ],
          ],
        ],
      ],
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_conference']['palettes']['media'] = [
  'showitem' => 'logo, impressions',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  '--palette--;;media',
  '',
  'before:--div--;core.form.tabs:categories',
);

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 to the photo of a speaker, which is initially one third of the size of the image and centered.

The image editor with the square crop and the focus area of the photo of a speaker

        EXT:my_extension/Configuration/TCA/Overrides/320-tx_myextension_speaker-photo.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_speaker', [
  'photo' => [
    'label' => 'my_extension.db:speaker.photo',
    'config' => [
      'type' => 'file',
      'maxitems' => 1,
      'allowed' => 'common-image-types',
      'relationship' => 'manyToOne',
      'overrideChildTca' => [
        'columns' => [
          'crop' => [
            'config' => [
              'cropVariants' => [
                'default' => [
                  'title' => 'my_extension.db:speaker.photo.square',
                  'allowedAspectRatios' => [
                    '1:1' => [
                      'title' => 'core.wizards:imwizard.ratio.1_1',
                      'value' => 1.0,
                    ],
                  ],
                  // The face of the speaker, initially in the middle
                  'focusArea' => [
                    'x' => 1 / 3,
                    'y' => 1 / 3,
                    'width' => 1 / 3,
                    'height' => 1 / 3,
                  ],
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_speaker',
  'photo',
  '',
  'before:--div--;my_extension.db:tab.integration',
);

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.

The name of a location is shown on top of the lower part of its image:

        EXT:my_extension/Configuration/TCA/Overrides/401-tx_myextension_location-image.php
    

<?php

defined('TYPO3') or die();

// The name of the location is shown on top of the lower part of the image
$GLOBALS['TCA']['tx_myextension_location']['columns']['image']['config']
  ['overrideChildTca']['columns']['crop']['config']['cropVariants'] = [
    'default' => [
      'title' => 'core.wizards:imwizard.crop_variant.default',
      'allowedAspectRatios' => [
        '16:9' => [
          'title' => 'core.wizards:imwizard.ratio.16_9',
          'value' => 16 / 9,
        ],
      ],
      'coverAreas' => [
        [
          'x' => 0.05,
          'y' => 0.75,
          'width' => 0.9,
          'height' => 0.2,
        ],
      ],
    ],
  ];

The above configuration examples override the crop variants for one field of type file with overrideChildTca.

Configuration per content element

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

EXT:my_sitepackage/Configuration/TCA/Overrides/tt_content.php (excerpt)

<?php

defined('TYPO3') or die();

// The translators of this site write the headers of content elements
// themselves, so a translation starts with an unchanged copy of the header
$GLOBALS['TCA']['tt_content']['columns']['header']['l10n_mode'] = '';

// The editors of this site call a conference an event. The "New content
// element" wizard shows the teaser of the conference extension with the
// title they know.
$GLOBALS['TCA']['tt_content']['types']['myextension_conferenceteaser']['creationOptions']['title']
  = 'my_sitepackage.db:tt_content.conference_teaser.wizard_title';

// The layout of this site has room for wide and square images only
$GLOBALS['TCA']['tt_content']['columns']['image']['config']
  ['overrideChildTca']['columns']['crop']['config']['cropVariants'] = [
    'default' => [
      'title' => 'core.wizards:imwizard.crop_variant.default',
      'allowedAspectRatios' => [
        '16:9' => [
          'title' => 'core.wizards:imwizard.ratio.16_9',
          'value' => 16 / 9,
        ],
        '1:1' => [
          'title' => 'core.wizards:imwizard.ratio.1_1',
          'value' => 1.0,
        ],
      ],
    ],
  ];

// "Text and images" also shows its images on mobile devices, initially the
// middle of the image
$GLOBALS['TCA']['tt_content']['types']['textpic']['columnsOverrides']
  ['image']['config']['overrideChildTca']['columns']['crop']['config']
  ['cropVariants']['mobile'] = [
    'title' => 'my_sitepackage.db:crop_variant.mobile',
    'allowedAspectRatios' => [
      '4:3' => [
        'title' => 'core.wizards:imwizard.ratio.4_3',
        'value' => 4 / 3,
      ],
    ],
    'cropArea' => [
      'x' => 0.1,
      'y' => 0.1,
      'width' => 0.8,
      'height' => 0.8,
    ],
  ];

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_sitepackage/Configuration/TCA/Overrides/tt_content.php (excerpt)

<?php

defined('TYPO3') or die();

// The translators of this site write the headers of content elements
// themselves, so a translation starts with an unchanged copy of the header
$GLOBALS['TCA']['tt_content']['columns']['header']['l10n_mode'] = '';

// The editors of this site call a conference an event. The "New content
// element" wizard shows the teaser of the conference extension with the
// title they know.
$GLOBALS['TCA']['tt_content']['types']['myextension_conferenceteaser']['creationOptions']['title']
  = 'my_sitepackage.db:tt_content.conference_teaser.wizard_title';

// The layout of this site has room for wide and square images only
$GLOBALS['TCA']['tt_content']['columns']['image']['config']
  ['overrideChildTca']['columns']['crop']['config']['cropVariants'] = [
    'default' => [
      'title' => 'core.wizards:imwizard.crop_variant.default',
      'allowedAspectRatios' => [
        '16:9' => [
          'title' => 'core.wizards:imwizard.ratio.16_9',
          'value' => 16 / 9,
        ],
        '1:1' => [
          'title' => 'core.wizards:imwizard.ratio.1_1',
          'value' => 1.0,
        ],
      ],
    ],
  ];

// "Text and images" also shows its images on mobile devices, initially the
// middle of the image
$GLOBALS['TCA']['tt_content']['types']['textpic']['columnsOverrides']
  ['image']['config']['overrideChildTca']['columns']['crop']['config']
  ['cropVariants']['mobile'] = [
    'title' => 'my_sitepackage.db:crop_variant.mobile',
    'allowedAspectRatios' => [
      '4:3' => [
        'title' => 'core.wizards:imwizard.ratio.4_3',
        'value' => 4 / 3,
      ],
    ],
    'cropArea' => [
      'x' => 0.1,
      'y' => 0.1,
      'width' => 0.8,
      'height' => 0.8,
    ],
  ];

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_sitepackage/Configuration/TCA/Overrides/tx_myextension_conference.php (excerpt)
    

<?php

defined('TYPO3') or die();

// The suggest wizard of the related content searches only the pages
// "Program" (6) and "News" (7) of this site, and four levels below them
$GLOBALS['TCA']['tx_myextension_conference']['columns']['related_content']['config']['suggestOptions']['default']['pidList'] = '6,7';
$GLOBALS['TCA']['tx_myextension_conference']['columns']['related_content']['config']['suggestOptions']['default']['pidDepth'] = 4;

// The layout of this site shows the impressions of a conference in 16:9
// only, so the free ratio of the extension is not available
$GLOBALS['TCA']['tx_myextension_conference']['columns']['impressions']['config']
  ['overrideChildTca']['columns']['crop']['config']['cropVariants']['desktop']
  ['allowedAspectRatios']['NaN']['disabled'] = true;

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" />