evanshunt / lazy-focus-fit
Template methods to quickly make use of FocusPoint, LazySizes, and Object-fit
Installs: 2 368
Dependents: 0
Suggesters: 0
Security: 0
Stars: 9
Watchers: 4
Forks: 2
Open Issues: 0
Type:silverstripe-vendormodule
Requires
README
A SilverStripe module with template methods to quickly make use of FocusPoint, LazySizes and object-fit.
Requirements
PHP
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.
import 'lazysizes'; // The bgSet plugin is required for ResponsiveBgAttributes import 'lazysizes/plugins/bgset/ls.bgset';
Config values
If you wish to serve all images as WebP set the following in your yaml config.
SilverStripe\Assets\Image: default_webp: true
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
$Image.ResponsiveImg(classname, 1200, 800, 600)
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
$Image.ResponsivePicture(classname, '770-1x 1440-2x 992px', '496-1x 992-2x default')
$Image.ResponsivePicture(classname, '770-770w 992px', '496-496w default')
$Image.ResponsivePicture(classname, '770 992px', '496 default')
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
<div $Image.ResponsiveBgAttributes(classname, '770-1x 1440-2x 992px', '496-1x 992-2x default')>
...
</div>
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
$Image.AddAttribute(aria-hidden, true).ResponsivePicture(classname, '770 992px', '496 default').
AddImgAttribute()
Adds additoinal attribute to the <img>
element w/in the <picture>
generated by ResponsivePicture()
. Must be called before the markup generating method.
Example
$Image.AddImgAttribute(data-foo, bar).ResponsivePicture(classname, 770 992px, 496 default)
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
$Image.AddAspectRatio(6, 9).ResponsivePicture(classname, '770 992px', '496 default')
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
$Image.ObjectFit().ResponsivePicture(classname, '770 992px', '496 default')
$Image.ObjectFit(contain).ResponsivePicture(classname, '770 992px', '496 default')
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
$Image.UseWebP.ResponsivePicture(classname, '770 992px', '496 default')