.. include:: ../Includes.txt
.. _ViewHelpers:
===========
ViewHelpers
===========
.. contents:: :local:
:depth: 1
General
-------
Add the fluid namespace declaration to fluid templates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before version 0.1.5 registering of the global viewhelper namespace *ai* was not working.
Even if you use a version >= 0.1.5 you might still want to add this namespace declaration to your templates and
partials:
.. code-block:: html
...
ai:getCropVariants
------------------
Returns a CropVariantCollection as array of cropVariants this FileReference has.
Arguments
^^^^^^^^^
=========== =========== =========== ==================================================================================
argument required default Description
=========== =========== =========== ==================================================================================
file yes FileReference to get the cropVariants from.
asString no false Return the result as string (instaed array)
=========== =========== =========== ==================================================================================
Examples
^^^^^^^^
.. code-block:: html
will return (if the FileReference has two cropVariants):
.. code-block:: none
array(2 items)
default => array(7 items)
id => 'default' (7 chars)
title => '' (0 chars)
cropArea => array(4 items)
x => 0 (double)
y => 0.09925 (double)
width => 0.999 (double)
height => 0.8991 (double)
allowedAspectRatios => array(empty)
selectedRatio => NULL
focusArea => array(4 items)
x => 0.33333333333333 (double)
y => 0.33333333333333 (double)
width => 0.33333333333333 (double)
height => 0.33333333333333 (double)
coverAreas => NULL
mobile => array(7 items)
ai:getSrcSet
------------
Get a srcset string for a given cropVariant and widths and generate images for srcset candidates
Arguments
^^^^^^^^^
=============== =========== =========================== ===============================================================
argument required Default Description
=============== =========== =========================== ===============================================================
file yes FileReference to use
cropVariant no default select a cropping variant, in case multiple croppings have been
specified or stored in FileReference
widths no [320,640,1024,1440,1920] create srcset candidates with these widths
debug no 0 Add debug output (width, height, ratio) to the generated images
=============== =========== =========================== ===============================================================
Examples
^^^^^^^^
.. code-block:: html
returns
.. code-block:: none
/fileadmin/_processed_/7/9/image_2269306f6a.jpg 360w,/fileadmin/_processed_/7/9/image_5f0de63291.jpg 720w
or for cropVariant mobile and widths as array
.. code-block:: html
returns
.. code-block:: none
/fileadmin/_processed_/7/9/image_cbb4289869.jpg 0w,/fileadmin/_processed_/7/9/image_3e7a2d9258.jpg 720w
ai:ratioBox
-----------
Wraps an image or picture tag in a ratio box. This also adds generated css style to the header of the page to set the
correct padding-bottom to always maintain the ratio and thus prevent page reflows.
Arguments
^^^^^^^^^
=============== =========== =========================== ===============================================================
argument required Default Description
=============== =========== =========================== ===============================================================
file yes FileReference to use
mediaQueries no [['default' => '']] Array of arrays containing ratio and media for cropVariants
=============== =========== =========================== ===============================================================
Examples
^^^^^^^^
.. code-block:: html
Your picture/image tag (f:image, ai:image etc.)
Assuming that the image has cropVariants default (16:9) and mobile (4:3) this will add css style to the head of the
website and return:
.. code-block:: html
Your picture/image tag (f:image, ai:image etc.)
ai:placeholder.image
--------------------
Returns a placeholder image (base64 encoded data OR uri) width reduced quality and size, but original aspect ratio.
Arguments
^^^^^^^^^
=============== =========== =========================== ===============================================================
argument required Default Description
=============== =========== =========================== ===============================================================
file yes FileReference to use
cropVariant no default select a cropping variant, in case multiple croppings have been
specified or stored in FileReference
width no 128 create placeholder image with this width
height no create placeholder image with this height
absolute no false Force absolute URL
dataUri no true Returns the base64 encoded dataUri of the image
(for inline usage)
=============== =========== =========================== ===============================================================
Examples
^^^^^^^^
.. code-block:: html
returns the images as base64 encoded data-uri
.. code-block:: none
data:image/jpeg;base64,/9j/4AAQSkZJ[...]
or return image uri instead:
.. code-block:: html
returns
.. code-block:: none
/fileadmin/_processed_/7/9/image_702e24791e.jpg
ai:placeholder.svg
------------------
Returns a placeholder SVG image (base64 encoded data uri) keeping original aspect ratio by replacing the SVG's width/and
height of that of the generated image.
Arguments
^^^^^^^^^
=============== =========== =========================== ===============================================================
argument required Default Description
=============== =========== =========================== ===============================================================
file yes FileReference to use
cropVariant no default select a cropping variant, in case multiple croppings have been
specified or stored in FileReference
=============== =========== =========================== ===============================================================
Examples
^^^^^^^^
.. code-block:: html
returns the SVG as base64 encoded data-uri
.. code-block:: none
data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0[...]
ai:image
--------
This viewHelper outputs a complete adaptive image *img* tag, optionally with ratio box and a placeholder image.
Use this when you don't need art direction/different cropVariants. If you need art direction see
:ref:`aiPictureViewHelper`.
Arguments
^^^^^^^^^
This viewHelper has all arguments which are available to the
`f:image viewHelper `_
including `fluids universal tag attributes `_
plus the following:
================== =========== =========================== ===============================================================
argument required Default Description
================== =========== =========================== ===============================================================
lazy no false lazy load images and auto-sizes with lazysizes.js
debug no false Add debug output (width, height, ratio) to the generated images using IM/GM
jsdebug no false Add debug output (width, height, ratio) near the image using javascript
srcsetWidths no [320,640,1024,1440,1920] create srcset candidates with these widths
cropVariant no default select a cropping variant, in case multiple croppings have been
specified or stored in FileReference
sizes no 100vw sizes attribute for the img tag.
Takes precedence over additionalAttributes["sizes"] if both are given.
placeholderInline no true Include placeholder inline in HTML (base64 encoded)
ratiobox no false The image is wrapped in a ratio box if true.
================== =========== =========================== ===============================================================
Examples
^^^^^^^^
.. code-block:: html
returns a complete image tag with lazysizes loading and a placeholder image.
**Important** For lazysizes to work you have to add the class *lazyload* here.
.. _aiPictureViewHelper:
ai:picture
----------
This viewHelper outputs a complete adaptive image *picture* tag, optionally with ratio box and a placeholder image.
If you need to show different cropVariants for different device widths you need to use this viewHelper.
Arguments
^^^^^^^^^
This viewHelper has all arguments which are available to the
`f:image viewHelper `_
including `fluids universal tag attributes `_
plus the following:
================== =========== =========================== ===============================================================
argument required Default Description
================== =========== =========================== ===============================================================
lazy no false lazy load images and auto-sizes with lazysizes.js
debug no false Add debug output (width, height, ratio) to the generated images using IM/GM
jsdebug no false Add debug output (width, height, ratio) near the image using javascript
srcsetWidths no [320,640,1024,1440,1920] create srcset candidates with these widths
cropVariant no default select a cropping variant, in case multiple croppings have been
specified or stored in FileReference
sizes no 100vw sizes attribute for the img tag.
Takes precedence over additionalAttributes["sizes"] if both are given.
placeholderInline no true Include placeholder inline in HTML (base64 encoded)
ratiobox no false The image is wrapped in a ratio box if true.
sources no [['default' => '']] Array of arrays containing candidates for source tags
================== =========== =========================== ===============================================================
Examples
^^^^^^^^
.. code-block:: html
returns a complete picture tag with one source for the cropVariant mobile. With lazysizes loading and a placeholder image.
**Important** For lazysizes to work you have to add the class *lazyload* here.