Skip to content

Commit

Permalink
[FEATURE] Add Crop Variants (#989)
Browse files Browse the repository at this point in the history
  • Loading branch information
@h3nn3s @susannemoog
h3nn3s authored and susannemoog committed Oct 4, 2020
1 parent 45da183 commit aaba726
Show file tree
Hide file tree
Showing 4 changed files with 245 additions and 0 deletions.
79 changes: 79 additions & 0 deletions Documentation/ApiOverview/CropVariants/ContentElement/Index.rst
View file
@@ -0,0 +1,79 @@
.. include:: ../../Includes.txt

.. _cropvariants:

===============================================
Crop variants configuration per content element
===============================================

It is possible to provide a configuration per content element. If you want a different
cropping configuration for tt_content images, then you can add the following to
your `image` field configuration of tt_content records:

.. code-block:: php
'config' => [
'overrideChildTca' => [
'columns' => [
'crop' => [
'config' => [
'cropVariants' => [
'mobile' => [
'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
'cropArea' => [
'x' => 0.1,
'y' => 0.1,
'width' => 0.8,
'height' => 0.8,
],
],
],
],
],
],
],
]
Please note, you need to specify the target column name as array key. Most of the time this will be `crop`
as this is the default field name for image manipulation in `sys_file_reference`

It is also possible to set the cropping configuration only for a **specific tt_content element type** by using the
`columnsOverrides` feature:

.. code-block:: php
$GLOBALS['TCA']['tt_content']['types']['textmedia']['columnsOverrides']['assets']['config']['overrideChildTca']['columns']['crop']['config'] = [
'cropVariants' => [
'default' => [
'disabled' => true,
],
'mobile' => [
'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
'cropArea' => [
'x' => 0.1,
'y' => 0.1,
'width' => 0.8,
'height' => 0.8,
],
'allowedAspectRatios' => [
'4:3' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
'value' => 4 / 3
],
'NaN' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.free',
'value' => 0.0
],
],
],
],
];
Disable crop variants
=====================

Please note, as the array for ``overrideChildTca`` is merged with the child TCA, so are the crop variants that are defined
in the child TCA (most likely sys_file_reference). 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`` as you can see in the
example above for the default variant.

143 changes: 143 additions & 0 deletions Documentation/ApiOverview/CropVariants/General/Index.rst
View file
@@ -0,0 +1,143 @@
.. include:: ../../Includes.txt

.. _cropvariants:

=====================
General Configuration
=====================

The following examples are meant to add one single
cropping configuration to sys_file_reference, which will then apply to every
record referencing images.

In this example we configure two crop variants, one with the id "mobile",
one with the id "desktop". The array key defines the crop variant id, which will be used
when rendering an image with the image view helper.

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 **should** be of PHP type float, not only a string.

.. code-block:: php
'config' => [
'type' => 'imageManipulation',
'cropVariants' => [
'mobile' => [
'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
'allowedAspectRatios' => [
'4:3' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
'value' => 4 / 3
],
'NaN' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.free',
'value' => 0.0
],
],
],
'desktop' => [
'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.desktop',
'allowedAspectRatios' => [
'4:3' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.4_3',
'value' => 4 / 3
],
'NaN' => [
'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_wizards.xlf:imwizard.ratio.free',
'value' => 0.0
],
],
],
]
]
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.

.. code-block:: php
'config' => [
'type' => 'imageManipulation',
'cropVariants' => [
'mobile' => [
'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
'cropArea' => [
'x' => 0.1,
'y' => 0.1,
'width' => 0.8,
'height' => 0.8,
],
],
],
]
Focus Area
==========

Users can also select a focus area, when configured. The focus area is always **inside**
the crop area and marks the area of 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 and
can be used by Javascript libraries.

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

.. code-block:: php
'config' => [
'type' => 'imageManipulation',
'cropVariants' => [
'mobile' => [
'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
'focusArea' => [
'x' => 1 / 3,
'y' => 1 / 3,
'width' => 1 / 3,
'height' => 1 / 3,
],
],
],
]
Cover Area
==========

Images are often 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.

.. code-block:: php
'config' => [
'type' => 'imageManipulation',
'cropVariants' => [
'mobile' => [
'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:imageManipulation.mobile',
'coverAreas' => [
[
'x' => 0.05,
'y' => 0.85,
'width' => 0.9,
'height' => 0.1,
]
],
],
],
]
Rendering crop variants
=======================

To render specific crop variants, the variant can be specified as argument of the image view helper:

.. code-block:: html

<f:image image="{data.image}" cropVariant="mobile" width="800" />
22 changes: 22 additions & 0 deletions Documentation/ApiOverview/CropVariants/Index.rst
View file
@@ -0,0 +1,22 @@
.. include:: ../../Includes.txt

.. _cropvariants:

===================
Image Crop Variants
===================

The `imageManipulation` TCA type is capable of handling multiple crop variants if configured.

The default configuration is to have only one variant with the same possible aspect ratios
as in previous TYPO3 versions.

See also :ref:`TCA reference on imageManipulation<t3tca:columns-imagemanipulation>`

.. toctree::
:maxdepth: 5
:titlesonly:
:glob:

General/Index
ContentElement/Index
1 change: 1 addition & 0 deletions Documentation/Index.rst
View file
Expand Up @@ -122,6 +122,7 @@ address the task at hand.
ApiOverview/ContentElements/Index
ApiOverview/Context/Index
ApiOverview/ContextSensitiveHelp/Index
ApiOverview/CropVariants/Index
ApiOverview/FileProcessing/Index
ApiOverview/Database/Index
ApiOverview/DependencyInjection/Index
Expand Down

0 comments on commit aaba726

Please sign in to comment.