Described in #167, this allows developers to bind their own customized DimensionCalculator if they have different needs.
This required to move a few things around, as some things were tied to "ratios". Breakpoints have been separted of their srcSets, and I have introduced separate Source to handle it instead (it represents tag in a way). For GraphQL the ratio property will be present if using default, filesize aspect-ratio based dimension calculator.
I introduced an object class Dimensions to better contain width and height, as having an array was a bit ugly for my liking.
If developers want to customize dimension calculations, they need to implement DimensionsCalculator interface with following three methods:
calculateForBreakpoint for calculating multiple dimensions for breakpoint srcsets
calculateForImgTag is specifically targeted for width and height in <img> tag
calculateForPlaceholder for blurry placeholder
All of these receive Breakpoint/Source objects, so developers should have plentiful freedom when it comes to calculating dimensions, as from there you can access breakpoint params and original asset.
Here is how developers can bind their implementation in AppServiceProvider, example:
$this->app->bind(DimensionCalculator::class, function () {
return new class extends ResponsiveDimensionCalculator {
public function calculateForBreakpoint(Source $source): Collection
{
// Disable JPG sources
if ($source->getFormat() === 'original') {
return collect([]);
}
// Create widths from 100 to 2000 in 100px increments with fixedHeight passed from params
return collect(range(100, 2000, 100))
->map(function ($width) use ($source) {
return new Dimensions($width, $source->breakpoint->params['fixedHeight']);
});
}
};
});
The original dimension calculator has remained unchanged. I do not currently have an idea how to solve #167 width calculations elegantly, so this is up to the individual developer, now they have the freedom to do so. Or we can improve this in a later update.
Additional side-quests:
Fix max widths config value or glide width param not being respected in some cases
Fix floating numbers for width and height values for Glide endpoint, they are now rounded integers
Add additional tests for dimension calculator and GraphQL
Placeholder can be toggled per breakpoint
<img> tag src will now go through Glide instead of pointing to original asset file, due to DimensionCalculators ability to return specific widths and heights for <img> tag
Empty media attributes won't be outputted at all
Breaking changes:
If developers have customized .blade.php template, they will need to readjust/republish. responsive-images.blade.php now loops breakpoints and then source instead of only breakpoints which then point to srcSet, srcSetWebp and srcSetAvif.
GraphQL queries have changed, any project using them will have to readjust queries and handling of the response. When getting breakpoints from responsive fieldtype, breakpoints will now have sources.
img src attribute will now always go through Glide controller now. If users relied on filename being readable, then this will be breaking change as filename is encoded by default from Statamic Glide controller.
TODO:
[x] Actually try creating a custom dimension calculator myself to test its capabilities
[x] Fixed height responsive images
[x] Breakpoints with only a single dimension for old image format (JPG)
[x] Breakpoints need to be separate from Sources
[x] Revise if DimensionCalculator methods arguments can be simplified to only Breakpoint (as it already contains asset property for Asset)
Described in #167, this allows developers to bind their own customized DimensionCalculator if they have different needs.
This required to move a few things around, as some things were tied to "ratios". Breakpoints have been separted of their tag in a way). For GraphQL the ratio property will be present if using default, filesize aspect-ratio based dimension calculator.
srcSets, and I have introduced separateSourceto handle it instead (it representsI introduced an object class
Dimensionsto better contain width and height, as having an array was a bit ugly for my liking.If developers want to customize dimension calculations, they need to implement DimensionsCalculator interface with following three methods:
calculateForBreakpointfor calculating multiple dimensions for breakpoint srcsetscalculateForImgTagis specifically targeted for width and height in<img>tagcalculateForPlaceholderfor blurry placeholderAll of these receive
Breakpoint/Sourceobjects, so developers should have plentiful freedom when it comes to calculating dimensions, as from there you can access breakpoint params and original asset.Here is how developers can bind their implementation in AppServiceProvider, example:
The original dimension calculator has remained unchanged. I do not currently have an idea how to solve #167 width calculations elegantly, so this is up to the individual developer, now they have the freedom to do so. Or we can improve this in a later update.
Additional side-quests:
<img>tagsrcwill now go through Glide instead of pointing to original asset file, due to DimensionCalculators ability to return specific widths and heights for<img>tagmediaattributes won't be outputted at allBreaking changes:
TODO:
DimensionCalculatormethods arguments can be simplified to onlyBreakpoint(as it already containsassetproperty forAsset)