Skip to content

Commit

Permalink
docs: Document passing in config & shortcut tags overview
Browse files Browse the repository at this point in the history
  • Loading branch information
@khalwat
khalwat committed Apr 3, 2024
1 parent 0b50db1 commit 94d78ea
Show file tree
Hide file tree
Showing 2 changed files with 121 additions and 99 deletions.
2 changes: 1 addition & 1 deletion docs/docs/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
218 changes: 120 additions & 98 deletions docs/docs/using.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<img srcset="">` element or using the `<picture>` element.
Expand All @@ -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 `<img>` and `<picture>` 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 `<img>` tags

An OptimizedImages field has a `.imgTag()` method that will generate a complete `<img>` tag for you. In its simplest form, it looks like this:
Expand Down Expand Up @@ -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)

0 comments on commit 94d78ea

Please sign in to comment.