From 4e9bb4082ff6a26e3d4adbc7653f9a3e66b92fbb Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Tue, 2 Apr 2024 20:55:30 -0400 Subject: [PATCH 1/7] docs: Docs cleanup --- docs/docs/using.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/docs/using.md b/docs/docs/using.md index dea828b..876fae5 100644 --- a/docs/docs/using.md +++ b/docs/docs/using.md @@ -303,7 +303,12 @@ Any attributes with empty values will not be rendered, so you can use that to re ##### The `.loading()` Parameter -With `.loading()`, you can control how the image will be loaded. +With `.loading()`, you can control how the image will be loaded.It can one of the following: + +* `'eager'` - (default) load the image normally (no lazy loading) +* `'lazy'` - us the browser's built-in lazy loading via the `loading="lazy"` attribute +* `'lazySizes'` - use the lazysizes JavaScript library for lazy loading the image +* `'lazySizesFallback'` - use the browser's built-in lazy loading, falling back on the lazysizes JavaScript library if the browser doesn't support native lazy loading ###### Using `.loading('eager')` @@ -733,17 +738,17 @@ Which will generate the following HTML markup for you: height="675" data-sizes="100vw" data-srcset="/assets/site/_576x432_crop_center-center_60_line/christmas-selfie.jpg.webp 576w, - /assets/site/_768x576_crop_center-center_60_line/christmas-selfie.jpg.webp 768w, - /assets/site/_992x558_crop_center-center_82_line/christmas-selfie.jpg.webp 992w, - /assets/site/_1200x675_crop_center-center_82_line/christmas-selfie.jpg.webp 1200w" + /assets/site/_768x576_crop_center-center_60_line/christmas-selfie.jpg.webp 768w, + /assets/site/_992x558_crop_center-center_82_line/christmas-selfie.jpg.webp 992w, + /assets/site/_1200x675_crop_center-center_82_line/christmas-selfie.jpg.webp 1200w" > Date: Tue, 2 Apr 2024 21:02:13 -0400 Subject: [PATCH 2/7] feat: Added the ability to pass in a config array to `.imgTag()`, `.pictureTag()` and `.linkPreloadTag()` --- src/models/OptimizedImage.php | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/models/OptimizedImage.php b/src/models/OptimizedImage.php index 65f00ae..32c2133 100644 --- a/src/models/OptimizedImage.php +++ b/src/models/OptimizedImage.php @@ -382,31 +382,34 @@ public function colorPaletteRgb(): array * Generate a complete tag for this OptimizedImages model * ref: https://web.dev/preload-responsive-images/#imagesrcset-and-imagesizes * + * @param array $config * @return LinkPreloadTag */ - public function linkPreloadTag(): LinkPreloadTag + public function linkPreloadTag(array $config = []): LinkPreloadTag { - return new LinkPreloadTag(['optimizedImage' => $this]); + return new LinkPreloadTag(array_merge($config, ['optimizedImage' => $this])); } /** * Generate a complete tag for this OptimizedImage model * + * @param array $config * @return ImgTag */ - public function imgTag(): ImgTag + public function imgTag(array $config = []): ImgTag { - return new ImgTag(['optimizedImage' => $this]); + return new ImgTag(array_merge($config, ['optimizedImage' => $this])); } /** * Generate a complete tag for this OptimizedImage model * + * @param array $config * @return PictureTag */ - public function pictureTag(): PictureTag + public function pictureTag(array $config = []): PictureTag { - return new PictureTag(['optimizedImage' => $this]); + return new PictureTag(array_merge($config, ['optimizedImage' => $this])); } /** From 3e3962ef65bc6b207433584da099cd358a18c015 Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Tue, 2 Apr 2024 21:03:00 -0400 Subject: [PATCH 3/7] chore: Version 5.0.0-beta.2 --- CHANGELOG.md | 4 ++++ composer.json | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee17bae..88e30aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # ImageOptimize Changelog +## 5.0.0-beta.2 - UNRELEASED +### Added +* Added the ability to pass in a config array to `.imgTag()`, `.pictureTag()` and `.linkPreloadTag()` + ## 5.0.0-beta.1 - 2024.04.02 ### Added * Initial Craft CMS 5 compatibility diff --git a/composer.json b/composer.json index d36b36e..d443933 100644 --- a/composer.json +++ b/composer.json @@ -2,7 +2,7 @@ "name": "nystudio107/craft-imageoptimize", "description": "Automatically create & optimize responsive image transforms, using either native Craft transforms or a service like imgix, with zero template changes.", "type": "craft-plugin", - "version": "5.0.0-beta.1", + "version": "5.0.0-beta.2", "keywords": [ "craft", "cms", From 884d374932bbbe0e24633a10eb7ebafa00cb90e4 Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Wed, 3 Apr 2024 00:02:46 -0400 Subject: [PATCH 4/7] docs: Document passing in config & shortcut tags overview --- docs/docs/overview.md | 2 +- docs/docs/using.md | 218 +++++++++++++++++++++++------------------- 2 files changed, 121 insertions(+), 99 deletions(-) diff --git a/docs/docs/overview.md b/docs/docs/overview.md index 896620b..3db1a95 100644 --- a/docs/docs/overview.md +++ b/docs/docs/overview.md @@ -18,7 +18,7 @@ As configured by default, all of these are _lossless_ image optimizations that r Out of the box, ImageOptimize allows for the optimization of `JPG`, `PNG`, `SVG`, & `GIF` images, but you can add whatever additional types you want. It also supports using [imgix](https://www.imgix.com/), [Thumbor](http://thumbor.org/), or [Sharp JS](https://nystudio107.com/blog/setting-up-your-own-image-transform-service) to create the responsive image transforms. -It’s important to create optimized images for frontend delivery, especially for mobile devices. To learn more about it, read the [Creating Optimized Images in Craft CMS](https://nystudio107.com/blog/creating-optimized-images-in-craft-cms) article. +It’s important to create optimized images for frontend delivery, especially for mobile devices. Thankfully, ImageOptimize includes `.imgTag()`, `pictureTag()` (with the ability to do "art direction"), and `linkPreloadTag()` convenience methods to make it easy to output modern optimized responsive images. Once ImageOptimize is installed, optimized versions of image transforms are created without you having to do anything. This makes it great for client-proofing sites. diff --git a/docs/docs/using.md b/docs/docs/using.md index 876fae5..651f601 100644 --- a/docs/docs/using.md +++ b/docs/docs/using.md @@ -126,104 +126,6 @@ Normally ImageOptimize will regenerate image variants if you change an Optimized If you plan to do this manually via the above console commands, you can disable this behavior via the `automaticallyResaveImageVariants` setting in `config.php`. -## Dynamically creating Optimized Image Variants - -To dynamically create Optimized Image Variants in your templates without having to use the Field. - -**N.B.:** We recommend _against_ using Image Optimize via Twig if you can avoid it. If you create the Optimized Image Variants in your templates, the image transforms, placeholder images, and color palette extraction will all be done at pageload time. This means you’ll miss out on the advantages of using the OptimizedImages field, where all of that computation is done when an Asset is saved. - -To create Optimized Image Variants dynamically in your templates, you can do: - -```twig -{% set optimizedImages = craft.imageOptimize.createOptimizedImages( - someAsset, - [ - { - 'width': 200, - 'useAspectRatio': true, - 'aspectRatioX': 1.0, - 'aspectRatioY': 1.0, - 'retinaSizes': ['1'], - 'quality': 82, - 'format': 'jpg', - }, - ] -) %} - -``` - -All of these fields are required, and they are analogous to the settings provided by the Field. The `retinaSizes` is an array of multipliers for the retina variants. For instance, if we wanted both normal resolution and 2x variants of the above image, we’d do: - -```twig -{% set optimizedImages = craft.imageOptimize.createOptimizedImages( - someAsset, - [ - { - 'width': 200, - 'useAspectRatio': true, - 'aspectRatioX': 1.0, - 'aspectRatioY': 1.0, - 'retinaSizes': ['1', '2'], - 'quality': 82, - 'format': 'jpg', - }, - ] -) %} - -``` - -You can create as many Optimized Image Variants as you like, by just including another array of settings. For example, to create both 200x and 400x image variants, we could do: - -```twig -{% set optimizedImages = craft.imageOptimize.createOptimizedImages( - someAsset, - [ - { - 'width': 200, - 'useAspectRatio': true, - 'aspectRatioX': 1.0, - 'aspectRatioY': 1.0, - 'retinaSizes': ['1'], - 'quality': 82, - 'format': 'jpg', - }, - { - 'width': 400, - 'useAspectRatio': true, - 'aspectRatioX': 1.0, - 'aspectRatioY': 1.0, - 'retinaSizes': ['1'], - 'quality': 82, - 'format': 'jpg', - }, - ] -) %} -``` - -The `optimizedImages` object that is returned to you can be used in your templates as described in the *Displaying images on the frontend* section. - -**N.B.:** Because they are lengthy operations, by default the generation of the dominant color palette and the generation of the placeholder silhouette are off. You can enable them via an additional parameter passed down to `craft.imageOptimize.createOptimizedImages`: - -```twig -{% set optimizedImages = craft.imageOptimize.createOptimizedImages( - someAsset, - [ - { - 'width': 200, - 'useAspectRatio': true, - 'aspectRatioX': 1.0, - 'aspectRatioY': 1.0, - 'retinaSizes': ['1'], - 'quality': 82, - 'format': 'jpg', - }, - ], - true, -) %} -``` - -The third parameter is the `generatePlacholders` setting, which disables generating all placeholders and dominant color palette extraction. - ## Displaying images on the frontend ImageOptimize makes it easy to create responsive images in your frontend templates. There are two primary ways to create responsive images: using the `` element or using the `` element. @@ -245,6 +147,28 @@ This allows the images to have `height` and `width` attributes applied to them s ImageOptimize knows all about your images, and so can create the HTML markup for your `` and `` tags quickly and easily. +It uses a synthesis of modern best practices to generate the tags in an optimal way, without you having to worry about the details, or maintain a myriad of out of date Twig template partials. + +All of the tag methods below support an Element Query-like chained syntax that lets you customize them: + +```twig + {% set asset = entry.myAssetField.one() %} + {{ asset.optimizedImagesField.imgTag() + .loading('lazy') + .render() }} +``` + +...or you can pass the config into them as an object if you prefer that method: + +```twig + {% set asset = entry.myAssetField.one() %} + {{ asset.optimizedImagesField.imgTag({ + 'loading': 'lazy', + }).render() }} +``` + +Either way, the result is the same, so pick whichever method you prefer. The example presented below will use the chained syntax. + #### Using `.imgTag()` to create `` tags An OptimizedImages field has a `.imgTag()` method that will generate a complete `` tag for you. In its simplest form, it looks like this: @@ -1271,4 +1195,102 @@ If you have `devMode` on, ImageOptimize will log stats for images that it create 2017-09-10 07:28:23 [192.168.10.1][1][-][info][nystudio107\imageoptimize\services\Optimize::createImageVariants] painted-face_170903_02341359b54c06c953b6.23303620.jpg -> painted-face_170903_02341359b54c06c953b6.23303620.jpg.webp -> Original: 36.9K, Variant: 12.8K -> Savings: 65.3% ``` +## Dynamically creating Optimized Image Variants + +To dynamically create Optimized Image Variants in your templates without having to use the Field. + +**N.B.:** We recommend _against_ using Image Optimize via Twig if you can avoid it. If you create the Optimized Image Variants in your templates, the image transforms, placeholder images, and color palette extraction will all be done at pageload time. This means you’ll miss out on the advantages of using the OptimizedImages field, where all of that computation is done when an Asset is saved. + +To create Optimized Image Variants dynamically in your templates, you can do: + +```twig +{% set optimizedImages = craft.imageOptimize.createOptimizedImages( + someAsset, + [ + { + 'width': 200, + 'useAspectRatio': true, + 'aspectRatioX': 1.0, + 'aspectRatioY': 1.0, + 'retinaSizes': ['1'], + 'quality': 82, + 'format': 'jpg', + }, + ] +) %} + +``` + +All of these fields are required, and they are analogous to the settings provided by the Field. The `retinaSizes` is an array of multipliers for the retina variants. For instance, if we wanted both normal resolution and 2x variants of the above image, we’d do: + +```twig +{% set optimizedImages = craft.imageOptimize.createOptimizedImages( + someAsset, + [ + { + 'width': 200, + 'useAspectRatio': true, + 'aspectRatioX': 1.0, + 'aspectRatioY': 1.0, + 'retinaSizes': ['1', '2'], + 'quality': 82, + 'format': 'jpg', + }, + ] +) %} + +``` + +You can create as many Optimized Image Variants as you like, by just including another array of settings. For example, to create both 200x and 400x image variants, we could do: + +```twig +{% set optimizedImages = craft.imageOptimize.createOptimizedImages( + someAsset, + [ + { + 'width': 200, + 'useAspectRatio': true, + 'aspectRatioX': 1.0, + 'aspectRatioY': 1.0, + 'retinaSizes': ['1'], + 'quality': 82, + 'format': 'jpg', + }, + { + 'width': 400, + 'useAspectRatio': true, + 'aspectRatioX': 1.0, + 'aspectRatioY': 1.0, + 'retinaSizes': ['1'], + 'quality': 82, + 'format': 'jpg', + }, + ] +) %} +``` + +The `optimizedImages` object that is returned to you can be used in your templates as described in the *Displaying images on the frontend* section. + +**N.B.:** Because they are lengthy operations, by default the generation of the dominant color palette and the generation of the placeholder silhouette are off. You can enable them via an additional parameter passed down to `craft.imageOptimize.createOptimizedImages`: + +```twig +{% set optimizedImages = craft.imageOptimize.createOptimizedImages( + someAsset, + [ + { + 'width': 200, + 'useAspectRatio': true, + 'aspectRatioX': 1.0, + 'aspectRatioY': 1.0, + 'retinaSizes': ['1'], + 'quality': 82, + 'format': 'jpg', + }, + ], + true, +) %} +``` + +The third parameter is the `generatePlacholders` setting, which disables generating all placeholders and dominant color palette extraction. + Brought to you by [nystudio107](https://nystudio107.com) From eaf816c8dbf24a6ba5836facc9d1d714712010fe Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Thu, 4 Apr 2024 00:39:10 -0400 Subject: [PATCH 5/7] =?UTF-8?q?refactor:=20Changed=20`.loading()`=20?= =?UTF-8?q?=E2=86=92=20`.loadingStrategy()`,=20`.artDirection()`=20?= =?UTF-8?q?=E2=86=92=20`addSourceFrom()`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/models/ImgTag.php | 10 +++++----- src/models/PictureTag.php | 21 ++++++++------------- 2 files changed, 13 insertions(+), 18 deletions(-) diff --git a/src/models/ImgTag.php b/src/models/ImgTag.php index 7e085a4..d20ed7c 100644 --- a/src/models/ImgTag.php +++ b/src/models/ImgTag.php @@ -24,7 +24,7 @@ class ImgTag extends BaseImageTag /** * @var string The loading scheme to use: 'eager', 'lazy', 'lazySizes', 'lazySizesFallback' */ - public string $loading = 'eager'; + public string $loadingStrategy = 'eager'; /** * @var string The type of placeholder image to use: 'box', 'color', 'image', 'silhouette' @@ -61,9 +61,9 @@ public function __construct($config = []) * @param string $value * @return $this */ - public function loading(string $value): ImgTag + public function loadingStrategy(string $value): ImgTag { - $this->loading = $value; + $this->loadingStrategy = $value; return $this; } @@ -103,8 +103,8 @@ public function render(): Markup { $attrs = $this->imgAttrs; // Handle lazy loading - if ($this->loading !== 'eager') { - $attrs = $this->swapLazyLoadAttrs($this->loading, $this->placeholder, $attrs); + if ($this->loadingStrategy !== 'eager') { + $attrs = $this->swapLazyLoadAttrs($this->loadingStrategy, $this->placeholder, $attrs); } // Remove any empty attributes $attrs = array_filter($attrs); diff --git a/src/models/PictureTag.php b/src/models/PictureTag.php index afe802b..d38d2a1 100644 --- a/src/models/PictureTag.php +++ b/src/models/PictureTag.php @@ -24,7 +24,7 @@ class PictureTag extends BaseImageTag /** * @var string The loading scheme to use: 'eager', 'lazy', 'lazySizes', 'lazySizesFallback' */ - public string $loading = 'eager'; + public string $loadingStrategy = 'eager'; /** * @var string The type of placeholder image to use: 'box', 'color', 'image', 'silhouette' @@ -46,11 +46,6 @@ class PictureTag extends BaseImageTag */ public array $imgAttrs = []; - /** - * @var OptimizedImage[] array OptimizedImage models to add as art direction - */ - public array $artDirection = []; - /** * @param $config */ @@ -78,9 +73,9 @@ public function __construct($config = []) * @param string $value * @return $this */ - public function loading(string $value): PictureTag + public function loadingStrategy(string $value): PictureTag { - $this->loading = $value; + $this->loadingStrategy = $value; return $this; } @@ -147,7 +142,7 @@ public function imgAttrs(array $value): PictureTag * @param array $sourceAttrs * @return PictureTag */ - public function artDirection(OptimizedImage $optimizedImage, array $sourceAttrs = []): PictureTag + public function addSourceFrom(OptimizedImage $optimizedImage, array $sourceAttrs = []): PictureTag { $this->populateSourceAttrs($optimizedImage, $sourceAttrs); @@ -165,8 +160,8 @@ public function render(): Markup // Handle the tag(s) foreach ($this->sourceAttrs as $attrs) { // Handle lazy loading - if ($this->loading !== 'eager') { - $attrs = $this->swapLazyLoadAttrs($this->loading, $this->placeholder, $attrs); + if ($this->loadingStrategy !== 'eager') { + $attrs = $this->swapLazyLoadAttrs($this->loadingStrategy, $this->placeholder, $attrs); } // Remove any empty attributes $attrs = array_filter($attrs); @@ -176,8 +171,8 @@ public function render(): Markup // Handle the tag $attrs = $this->imgAttrs; // Handle lazy loading - if ($this->loading !== 'eager') { - $attrs = $this->swapLazyLoadAttrs($this->loading, $this->placeholder, $attrs); + if ($this->loadingStrategy !== 'eager') { + $attrs = $this->swapLazyLoadAttrs($this->loadingStrategy, $this->placeholder, $attrs); } // Remove any empty attributes $attrs = array_filter($attrs); From c319f2682dfd14a3b0a2ecc65b64bb1031ef1cbe Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Thu, 4 Apr 2024 00:39:15 -0400 Subject: [PATCH 6/7] =?UTF-8?q?docs:=20Changed=20`.loading()`=20=E2=86=92?= =?UTF-8?q?=20`.loadingStrategy()`,=20`.artDirection()`=20=E2=86=92=20`add?= =?UTF-8?q?SourceFrom()`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docs/using.md | 72 +++++++++++++++++++++++----------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/docs/using.md b/docs/docs/using.md index 651f601..b35d8d9 100644 --- a/docs/docs/using.md +++ b/docs/docs/using.md @@ -154,7 +154,7 @@ All of the tag methods below support an Element Query-like chained syntax that l ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.imgTag() - .loading('lazy') + .loadingStrategy('lazy') .render() }} ``` @@ -163,7 +163,7 @@ All of the tag methods below support an Element Query-like chained syntax that l ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.imgTag({ - 'loading': 'lazy', + 'loadingStrategy': 'lazy', }).render() }} ``` @@ -225,25 +225,25 @@ Which will generate the following HTML markup for you: Any attributes with empty values will not be rendered, so you can use that to remove any of the prepopulated attributes should you need to. -##### The `.loading()` Parameter +##### The `.loadingStrategy()` Parameter -With `.loading()`, you can control how the image will be loaded.It can one of the following: +With `.loadingStrategy()`, you can control how the image will be loaded.It can one of the following: * `'eager'` - (default) load the image normally (no lazy loading) * `'lazy'` - us the browser's built-in lazy loading via the `loading="lazy"` attribute * `'lazySizes'` - use the lazysizes JavaScript library for lazy loading the image * `'lazySizesFallback'` - use the browser's built-in lazy loading, falling back on the lazysizes JavaScript library if the browser doesn't support native lazy loading -###### Using `.loading('eager')` +###### Using `.loadingStrategy('eager')` -`.loading('eager')` is the default, which causes the image to be loader eagerly. +`.loadingStrategy('eager')` is the default, which causes the image to be loader eagerly. You'd typically want this for "above the fold" images that should be rendered as soon as possible. ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.imgTag() - .loading('eager') + .loadingStrategy('eager') .render() }} ``` @@ -261,9 +261,9 @@ Which will generate the following HTML markup for you: > ``` -###### Using `.loading('lazy')` +###### Using `.loadingStrategy('lazy')` -`.loading('lazy')` will load the image lazily via native browser [lazing loading](https://web.dev/articles/browser-level-image-lazy-loading) by adding `class="lazyload"` and `loading="lazy"` attributes to the image. +`.loadingStrategy('lazy')` will load the image lazily via native browser [lazing loading](https://web.dev/articles/browser-level-image-lazy-loading) by adding `class="lazyload"` and `loading="lazy"` attributes to the image. This leverages native browser lazy loading of images, without the need for additional JavaScript code. @@ -272,7 +272,7 @@ You'd typically want this for "below the fold" images that the browser can load ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.imgTag() - .loading('lazy') + .loadingStrategy('lazy') .render() }} ``` @@ -295,9 +295,9 @@ Which will generate the following HTML markup for you: Note that it sets the background image to the OptimizedImage's placeholder via the `style` attribute, sp the placeholder image will be visible until the actual image loads. -###### Using `.loading('lazySizes')` +###### Using `.loadingStrategy('lazySizes')` -`.loading('lazySizes')` will load the image lazily via the [lazysizes](https://github.com/aFarkas/lazysizes) library. You'd typically want this for "below the fold" images that the browser can load lazily as needed. +`.loadingStrategy('lazySizes')` will load the image lazily via the [lazysizes](https://github.com/aFarkas/lazysizes) library. You'd typically want this for "below the fold" images that the browser can load lazily as needed. This allows you to support lazy loading of images even with browsers that don't support native lazy loading. @@ -306,7 +306,7 @@ You'd typically want this for "below the fold" images that the browser can load ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.imgTag() - .loading('lazySizes') + .loadingStrategy('lazySizes') .render() }} ``` @@ -335,9 +335,9 @@ It's expected that you will have loaded the lazysizes library already on the fro Note that it sets the background image to the OptimizedImage's placeholder via the `style` attribute, sp the placeholder image will be visible until the actual image loads. -###### `.loading('lazySizesFallback')` +###### `.loadingStrategy('lazySizesFallback')` -`.loading('lazySizesFallback')` will load the image lazily via the native browser [lazing loading](https://web.dev/articles/browser-level-image-lazy-loading), but will fall back on using the [lazysizes](https://github.com/aFarkas/lazysizes) library if the browser doesn't support native lazy loading. +`.loadingStrategy('lazySizesFallback')` will load the image lazily via the native browser [lazing loading](https://web.dev/articles/browser-level-image-lazy-loading), but will fall back on using the [lazysizes](https://github.com/aFarkas/lazysizes) library if the browser doesn't support native lazy loading. This is the best of both worlds, in terms of using native browser lazy loading if it's available, and falling back on lazysizes JavaScript if it is not. @@ -346,7 +346,7 @@ You'd typically want this for "below the fold" images that the browser can load ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.imgTag() - .loading('lazySizesFallback') + .loadingStrategy('lazySizesFallback') .render() }} ``` @@ -389,7 +389,7 @@ With `.placeholder()`, you can set the type of placeholder image that should be {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.imgTag() .placeholder('image') - .loading('lazy') + .loadingStrategy('lazy') .render() }} ``` @@ -491,20 +491,20 @@ Which will generate the following HTML markup for you: Any attributes with empty values will not be rendered, so you can use that to remove any of the prepopulated attributes should you need to. -##### The `.loading()` Parameter +##### The `.loadingStrategy()` Parameter -With `.loading()`, you can control how the image will be loaded. +With `.loadingStrategy()`, you can control how the image will be loaded. -###### Using `.loading('eager')` +###### Using `.loadingStrategy('eager')` -`.loading('eager')` is the default, which causes the image to be loader eagerly. +`.loadingStrategy('eager')` is the default, which causes the image to be loader eagerly. You'd typically want this for "above the fold" images that should be rendered as soon as possible. ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.pictureTag() - .loading('eager') + .loadingStrategy('eager') .render() }} ``` @@ -536,9 +536,9 @@ Which will generate the following HTML markup for you: ``` -###### Using `.loading('lazy')` +###### Using `.loadingStrategy('lazy')` -`.loading('lazy')` will load the image lazily via native browser [lazing loading](https://web.dev/articles/browser-level-image-lazy-loading) by adding `class="lazyload"` and `loading="lazy"` attributes to the image. +`.loadingStrategy('lazy')` will load the image lazily via native browser [lazing loading](https://web.dev/articles/browser-level-image-lazy-loading) by adding `class="lazyload"` and `loading="lazy"` attributes to the image. This leverages native browser lazy loading of images, without the need for additional JavaScript code. @@ -547,7 +547,7 @@ You'd typically want this for "below the fold" images that the browser can load ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.pictureTag() - .loading('lazy') + .loadingStrategy('lazy') .render() }} ``` @@ -584,9 +584,9 @@ Which will generate the following HTML markup for you: Note that it sets the background image to the OptimizedImage's placeholder via the `style` attribute, sp the placeholder image will be visible until the actual image loads. -###### Using `.loading('lazySizes')` +###### Using `.loadingStrategy('lazySizes')` -`.loading('lazySizes')` will load the image lazily via the [lazysizes](https://github.com/aFarkas/lazysizes) library. You'd typically want this for "below the fold" images that the browser can load lazily as needed. +`.loadingStrategy('lazySizes')` will load the image lazily via the [lazysizes](https://github.com/aFarkas/lazysizes) library. You'd typically want this for "below the fold" images that the browser can load lazily as needed. This allows you to support lazy loading of images even with browsers that don't support native lazy loading. @@ -595,7 +595,7 @@ You'd typically want this for "below the fold" images that the browser can load ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.pictureTag() - .loading('lazySizes') + .loadingStrategy('lazySizes') .render() }} ``` @@ -638,9 +638,9 @@ It's expected that you will have loaded the lazysizes library already on the fro Note that it sets the background image to the OptimizedImage's placeholder via the `style` attribute, sp the placeholder image will be visible until the actual image loads. -###### `.loading('lazySizesFallback')` +###### `.loadingStrategy('lazySizesFallback')` -`.loading('lazySizesFallback')` will load the image lazily via the native browser [lazing loading](https://web.dev/articles/browser-level-image-lazy-loading), but will fall back on using the [lazysizes](https://github.com/aFarkas/lazysizes) library if the browser doesn't support native lazy loading. +`.loadingStrategy('lazySizesFallback')` will load the image lazily via the native browser [lazing loading](https://web.dev/articles/browser-level-image-lazy-loading), but will fall back on using the [lazysizes](https://github.com/aFarkas/lazysizes) library if the browser doesn't support native lazy loading. This is the best of both worlds, in terms of using native browser lazy loading if it's available, and falling back on lazysizes JavaScript if it is not. @@ -649,7 +649,7 @@ You'd typically want this for "below the fold" images that the browser can load ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.pictureTag() - .loading('lazySizesFallback') + .loadingStrategy('lazySizesFallback') .render() }} ``` @@ -706,7 +706,7 @@ With `.placeholder()`, you can set the type of placeholder image that should be {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.pictureTag() .placeholder('image') - .loading('lazy') + .loadingStrategy('lazy') .render() }} ``` @@ -829,21 +829,21 @@ Which will generate the following HTML markup for you: Any attributes with empty values will not be rendered, so you can use that to remove any of the prepopulated attributes should you need to. -##### The `.artDirection()` Parameter +##### The `.addSourceFrom()` Parameter Since each OptimizedImages field can be thought of as encapsulating a [srcset](https://cloudfour.com/thinks/responsive-images-101-part-4-srcset-width-descriptors/) for your images, if you require art direction where images change aspect ratios at different screen sizes, then you should use another OptimizedImages field for each art direction. -With `.artDirection()`, you can add the `` tags from additional OptimizedImages fields to an output `` tag. The first argument is the OptimizedImages field, and the second argument is any `sourceAttrs` you want to set on the `` tags: +With `.addSourceFrom()`, you can add the `` tags from additional OptimizedImages fields to an output `` tag for art direction purposes. The first argument is the OptimizedImages field to pull the art direction `srcset` from, and the second argument is any `sourceAttrs` you want to set on the `` tags: ```twig {% set asset = entry.myAssetField.one() %} {{ asset.optimizedImagesField.pictureTag() - .loading('lazy') + .loadingStrategy('lazy') .sourceAttrs({ 'media': '(min-width: 800px)', 'sizes': '80vw', }) - .artDirection(asset.mobileOptimizedImagesField, { + .addSourceFrom(asset.mobileOptimizedImagesField, { 'media': '(max-width: 799px)', 'sizes': '60vw', }) From 6540fdad567262605ed4c5b91aac8423da354b84 Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Thu, 4 Apr 2024 00:43:42 -0400 Subject: [PATCH 7/7] chore: Version 5.0.0-beta.2 --- CHANGELOG.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 88e30aa..73cd66d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,12 @@ # ImageOptimize Changelog -## 5.0.0-beta.2 - UNRELEASED +## 5.0.0-beta.2 - 2024.04.04 ### Added * Added the ability to pass in a config array to `.imgTag()`, `.pictureTag()` and `.linkPreloadTag()` +### Changed +* Changed `.loading()` → `.loadingStrategy()`, `.artDirection()` → `addSourceFrom()` + ## 5.0.0-beta.1 - 2024.04.02 ### Added * Initial Craft CMS 5 compatibility