Download the PHP package evanshunt/lazy-focus-fit without Composer

LazyFocusFit

A SilverStripe module with template methods to quickly make use of FocusPoint, LazySizes and object-fit.

Requirements

PHP

• FocusPoint
• Silverstripe Webp Formatter

JS/CSS

• LazySizes
• LazySizes bgset extension
• object-fit compatible browser, OR
• objectFitPolyfill

Installation

composer require evanshunt/lazy-focus-fit

After installing this module, ensure front-end requirements are installed and properly initiated within your project.

Config values

If you wish to serve all images as WebP set the following in your yaml config.

Usage

This module adds 3 primary methods to SilverStripe Image objects, to allow quick creation of responsive image markup eather as <img> or <picture> tags or attributes which can be applied to any element for use as a background image.

Additional methods allow configuring the images to use object-fit, crop according to a specific aspect ratio, or add additional html attributes.

Note: Template parsing seems to have changed in Silverstripe 5, where previously it was not required to put an argument like 770 992px in quotes, it now appears to be required.

ResponsiveImg()

This method allows generating an <img> tag with a number of possible image sizes. On page load a 32px wide image will be loaded and the correct size will be lazyloaded using LazySizes auto-sizes functionality. A future version may allow explicitly defining a sizes attribute or using the browser's built in responsive sizing w/o LazySizes.

Example

ResponsivePicture()

This method generateds a <picture> element, and allows for more explicit art direction than ResponsiveImg(). You can define media query conditions under which your images will be shown. After the first classname argument, subsequent arguments should take the following format:

{ImageWidth}-{WidthDescriptor}-{PixelDensityDescriptor} {MinWidth}

Width and Pixel density descriptors are optional as defined here: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source#Attributes

MinWidth should be a screen width for a (min-width: xxx) media query, or 'default'. Start with largest width and work your way down to default.

Examples

ResponsiveBgAttributes

Requires Lazysizes bgSet plugin

This method generates html attributes, not an entire element, it is used to apply a background image. The arguments operate the same way as ResponsivePicture()

Be aware that this method generates class and style attributes so adding these to your template code will result in dublicated attributes.

Example

Helper methods

AddAttribute()

Adds additional attribute to the <picture> element generated by ResponsivePicture() or the <img> attribute generated by ResponsiveImg(). Must be called before the markup generating method.

Example

AddImgAttribute()

Adds additoinal attribute to the <img> element w/in the <picture> generated by ResponsivePicture(). Must be called before the markup generating method.

Example

AddAspectRatio()

Crops image to a specific proportion, centered on the FocusPoint, for use with ResponsivePicture() and ResponsiveImg(). Must be called before the markup generating method.

Example

ObjectFit()

Adds object-fit styles to style tag of ResponsivePicture() and ResponsiveImg(), also adds necessary data-attributes to work with objectFitPolyfill. Object position values come from FocusPoint.

By default object-fit: cover; is applied, but alternative values (fill, contain, scale-down) can be passed as an argument.

Examples

UseWebP()

If you haven't set the global config value to serve WebP, you can opt in for an individual image by calling this method. Must be called before the markup generating method.

Example