viktor-firus/image-tools

This extension is a toolkit to generate responsive images in fluid templates (with optional lazy loading and opportunity to define animations yourself for lazy loading).

1.0.0 2019-05-13 09:35 UTC

Requires

• php: ^7.0
• ext-json: *
• typo3/cms-backend: ^8.7.25 | ^9.5.6
• typo3/cms-core: ^8.7.25 | ^9.5.6
• typo3/cms-extbase: ^8.7.25 | ^9.5.6
• typo3fluid/fluid: ^2.6.1

Requires (Dev)

• mockery/mockery: ^1.1.0
• typo3/testing-framework: ^2.0

Replaces

• image_tools: 1.0.0
• typo3-ter/image-tools: 1.0.0

GPL-3.0+

• extension
• images
• responsive
• lazy
• photo
• typo3
• picture
• lazyload

README

This extension is a toolkit to generate responsive images in fluid templates (with optional lazy loading and opportunity to define animations yourself for lazy loading).

TOC

• Image reference
• ViewHelpers Reference
  • ImgViewHelper
  • PictureViewHelper
  • SourceViewHelper
  • LazyViewHelper
  • User defined animations
• Demo

Image reference

For all view-helpers an "image-reference" is necessary, here are all options:

• fileReference:123: file reference from sys_file_reference with id 123.
• r:123: abbreviation for fileReference:123.
• file:234: file from sys_file with id 234.
• f:234: abbreviation for file:234.
• {fileObject}: instance of \TYPO3\CMS\Extbase\Domain\Model\FileReference
• {fileObject}: instance of \TYPO3\CMS\Core\Resource\FileReference
• {fileObject}: instance of \TYPO3\CMS\Core\Resource\File

or

• {fileObject}: instance of \ByteCube\ImageTools\Image\ImageInterface

ViewHelpers Reference

In all examples the xml namespace it will used. The namespace depends on the view-helper import in your template.

ImgViewHelper

Example

<it:img image="image-reference" width="1400" fallbackWidth="700" cropName="device1"/>

Arguments

Argument	Description	Type	Default
absolute	Force absolute image url.	bool	false
alt	Alternate text.	string	null
aspectRatio	Aspect ratio for image using the format 16x9.	string	null
cropName	Name of the crop variant from image manipulation.	string	null
fallbackWidth	If more than one pixelDensity is set a fallback image should be generated for the src attribute of the img tag.	int	null
image	See image reference	mixed
pixelDensities	Image variants for the srcset attribute of the img tag using the format 1,2,3. If more than one pixel density is set, the img tag will have a src attribute with the width from fallbackWidth and a srcset attribute with images generated from pixelDensities.	string	1
respectFocusArea	Respect the focus area if configured for image manipulation.	bool	true
width	Max width for image if needed. Multiplied with pixel densities.	int	null

Further arguments initialized in AbstractTagBasedViewHelper in method initializeArguments and registerUniversalTagAttributes.

PictureViewHelper

Example

<it:picture image="image-reference" cropName="device2">
    <it:source width="1400" pixelDensities="1" cropName="device1" media="(min-width: 1400px)"/>
    <it:source width="1200" pixelDensities="1" media="(min-width: 1200px)"/>
    <it:source width="1000" pixelDensities="1" cropName="device3"/>
    <it:img width="700"/>
</it:picture>

Arguments

Argument	Description	Type	Default
absolute	Force absolute image url.	bool	false
aspectRatio	Aspect ratio for image using the format 16x9.	string	null
cropName	Name of the crop variant from image manipulation.	string	null
image	See image reference	mixed
pixelDensities	Image variants for the child view-helpers using the format 1,2,3.	string	1
respectFocusArea	Respect the focus area if configured for image manipulation.	bool	true

aspectRatio, cropName, pixelDensities or respectFocusArea will apply to child source or img view-helpers if the attributes not defined in the child view-helpers.

Further arguments initialized in AbstractTagBasedViewHelper in method initializeArguments and registerUniversalTagAttributes.

SourceViewHelper

Example

<it:picture image="image-reference" cropName="device2">
    ...
    <it:source width="1200" pixelDensities="1" media="(min-width: 1200px)"/>
    ...
</it:picture>

Arguments

Argument	Description	Type	Default
aspectRatio	Aspect ratio for image using the format 16x9.	string	null
cropName	Name of the crop variant from image manipulation.	string	null
image	See image reference	mixed
pixelDensities	Image variants using the format 1,2,3.	string	1
respectFocusArea	Respect the focus area if configured for image manipulation.	bool	true
width	Max width for image if needed. Multiplied with pixel densities.	int	null

Further arguments initialized in AbstractTagBasedViewHelper in method initializeArguments and registerUniversalTagAttributes.

LazyViewHelper

Just wrap the img or the picture view-helper with the lazy view-helper.

Examples

<it:lazy placeholder="{placeholder}" animation="{animation}">
    <it:img image="image-reference" width="1400" fallbackWidth="700" cropName="device1"/>
</it:lazy>

<it:lazy placeholder="{placeholder}" animation="{animation}">
    <it:picture image="image-reference" cropName="device2">
        ...
    </it:picture>
</it:lazy>

Arguments

Argument	Description	Type	Default
placeholder	The initial loaded image. Can be a color-placeholder using the format #FFF/#FFFFFF or a blurred image using blurred.	string	#FFFFFF
animation	Animation for the lazy-loading. Current available animations overlay or top-slide-overlay. Leave it empty for no animation.	string	null

Further arguments initialized in AbstractTagBasedViewHelper in method initializeArguments and registerUniversalTagAttributes.

User defined animations

There are 3 steps to define an animation for lazy-loading only using css.

The overlay dom-object is the picture which are visible before the overlay process starts.

The original dom-object is the picture which are visible after the overlay process ends.

Step 1

The initial state of the overlay and original dom-object.

Default css rule of placeholder for this step has: opacity: 1

Default css rule of original for this step has: opacity: 0

Step 2

Some additional css attributes for the initial state for the dom-objects.

Please note! For full compatibility with most browsers css-transitions should defined in step 2.

After step 2 is set, image-tools detect the highest delay of all defined transitions to know when step 3 ends.

Step 3

This step is the end state if the dom-objects overlay and original.

Default css rule of placeholder for this step has: opacity: 0

Default css rule of original for this step has: opacity: 1

Examples

Example 1

div.imt-ll[data-imt-ll-animation="overlay"] img.placeholder.step-2 {
  transition: opacity 400ms ease-in;
}

div.imt-ll[data-imt-ll-animation="overlay"] img.original.step-2 {
  transition: opacity 400ms ease-out;
}

Example 2

div.imt-ll[data-imt-ll-animation="top-slide-overlay"] img.placeholder.step-2 {
  transition: opacity 400ms linear;
}

div.imt-ll[data-imt-ll-animation="top-slide-overlay"] img.original.step-1 {
  top: 40px;
}
div.imt-ll[data-imt-ll-animation="top-slide-overlay"] img.original.step-2 {
  transition: top 400ms linear, opacity 400ms linear;
}
div.imt-ll[data-imt-ll-animation="top-slide-overlay"] img.original.step-3 {
  top: 0;
}

Demo

To see a demo of the functionality enable the demo backend module.

TYPO3 V9: "Admin Tools" > "Settings" > "Extension Configuration" > "image_tools" > Activate "Enable demo module."