[TASK] Update 8.6 Documentation
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 8.6 / Feature-75880-ImplementMultipleCroppingVariantsInImageManipulationTool.rst
1 .. include:: ../../Includes.txt
2
3 =================================================================================
4 Feature: #75880 - Implement multiple cropping variants in image manipulation tool
5 =================================================================================
6
7 See :issue:`75880`
8
9 Description
10 ===========
11
12 The `imageManipulation` TCA type is now capable to handle multiple crop variants if configured.
13
14 The default configuration is to have only one variant with the same possible aspect ratios
15 like in older TYPO3 versions.
16
17 For that the TCA configuration has been extended.
18 The following example configures two crop variants, one with the id "mobile",
19 one with the id "desktop". The array key defines the crop variant id, which will be used
20 when rendering an image with the image view helper.
21
22 The allowed crop areas are now also configured differently.
23 The array key is used as identifier for the ratio and the label is specified with the "title"
24 and the actual (floating point) ratio with the "value" key.
25 The value **should** be of PHP type float, not only a string.
26
27 .. code-block:: php
28
29     'config' => [
30          'type' => 'imageManipulation',
31          'cropVariants' => [
32              'mobile' => [
33                  'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
34                  'allowedAspectRatios' => [
35                      '4:3' => [
36                          'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
37                          'value' => 4 / 3
38                      ],
39                      'NaN' => [
40                          'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.free',
41                          'value' => 0.0
42                      ],
43                  ],
44              ],
45              'desktop' => [
46                  'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.desktop',
47                  'allowedAspectRatios' => [
48                      '4:3' => [
49                          'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
50                          'value' => 4 / 3
51                      ],
52                      'NaN' => [
53                          'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.free',
54                          'value' => 0.0
55                      ],
56                  ],
57              ],
58          ]
59     ]
60
61
62 It is now 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.
63 Crop areas are defined relatively with floating point numbers. The x and y coordinates and width and height must be specified for that.
64 The below example has an initial crop area in the size the previous image cropper provided by default.
65
66 .. code-block:: php
67
68     'config' => [
69         'type' => 'imageManipulation',
70         'cropVariants' => [
71             'mobile' => [
72                 'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
73                 'cropArea' => [
74                     'x' => 0.1,
75                     'y' => 0.1,
76                     'width' => 0.8,
77                     'height' => 0.8,
78                 ],
79             ],
80         ],
81     ]
82
83 Users can also select a focus area, when configured. The focus area is always **inside**
84 the crop area and mark the area in the image which must be visible for the image to transport
85 its meaning. The selected area is persisted to the database but will have no effect on image processing.
86 The data points are however made available as data attribute when using the `<f:image />` view helper.
87
88 The below example adds a focus area, which is initially one third of the size of the image
89 and centered.
90
91 .. code-block:: php
92
93     'config' => [
94         'type' => 'imageManipulation',
95         'cropVariants' => [
96             'mobile' => [
97                 'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
98                 'focusArea' => [
99                     'x' => 1 / 3,
100                     'y' => 1 / 3,
101                     'width' => 1 / 3,
102                     'height' => 1 / 3,
103                 ],
104             ],
105         ],
106     ]
107
108 Very often images are used in a context, where there are overlaid with other DOM elements
109 like a headline. To give editors a hint which area of the image is affected, when selecting a crop area,
110 it is possible to define multiple so called cover areas. These areas are shown inside
111 the crop area. The focus area cannot intersect with any of the cover areas.
112
113 .. code-block:: php
114
115     'config' => [
116         'type' => 'imageManipulation',
117         'cropVariants' => [
118             'mobile' => [
119                 'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
120                 'coverAreas' => [
121                     [
122                         'x' => 0.05,
123                         'y' => 0.85,
124                         'width' => 0.9,
125                         'height' => 0.1,
126                     ]
127                 ],
128             ],
129         ],
130     ]
131
132 The above configuration examples are basically meant to add one single cropping configuration
133 to sys_file_reference, which will then apply in every record, which reference images.
134
135 It is however also possible to provide a configuration per content element. If you for example want a different
136 cropping configuration for tt_content images, then you can add the following to your `image` field configuration of tt_content records:
137
138 .. code-block:: php
139
140     'config' => [
141          'overrideCropVariants' => [
142             'crop' => [
143                'mobile' => [
144                    'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
145                    'cropArea' => [
146                        'x' => 0.1,
147                        'y' => 0.1,
148                        'width' => 0.8,
149                        'height' => 0.8,
150                    ],
151                ],
152             ],
153          ],
154     ]
155
156 Please note, that you need to specify the target column name as array key. Most of the time this will be `crop`
157 as this is the default field name for image manipulation in `sys_file_reference`
158
159 It is also possible to set the cropping configuration only for a specific tt_content element type by using the
160 `columnOverrides` feature:
161
162     $GLOBALS['TCA']['tt_content']['types']['textmedia']['columnsOverrides']['assets']['config']['overrideCropVariants'] = [
163         'crop' => [
164            'mobile' => [
165                'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
166                'cropArea' => [
167                    'x' => 0.1,
168                    'y' => 0.1,
169                    'width' => 0.8,
170                    'height' => 0.8,
171                ],
172                'allowedAspectRatios' => [
173                    '4:3' => [
174                        'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
175                        'value' => 4 / 3
176                    ],
177                    'NaN' => [
178                        'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.free',
179                        'value' => 0.0
180                    ],
181                ],
182            ],
183         ],
184     ];
185
186
187 To render crop variants, the variants can be specified as argument to the image view helper:
188
189 .. code-block:: html
190
191     <f:image image="{data.image}" cropVariant="mobile" width="800" />
192
193 Impact
194 ======
195
196 TCA configuration for field type "imageManipulation" has changed. Old configuration options
197 still work but are deprecated and issue a warning when used.
198
199 The TCA configuration option `enableZoom` has been removed for now. It wasn't really usable
200 anyway and will need some proper UX design before re-implementation. Setting the option
201 will have no effect.
202
203 .. index:: Backend, TCA