Automatically Optimizing Images in 2SXC

An important part of reducing website load times is ensuring the loaded images are properly optimized. Luckily, 2SXC offers a lot of customizability regarding automatic cropping and resizing of images. However, they must be implemented properly in both the entity settings and the razor template to take advantage of this.

Entity Field Settings

To allow the user to choose custom crop settings, the option must be turned on in the settings for the image field. In the General Field Settings panel for the entity's image field, enable the "Enable image configuration if the file is an image" option shown below:

This enables the user to access the following options for images:

Implementation in the Razor Template

There are three primary ways to implement images, each with pros and cons:

1. Kit.Image.Picture
   Implementing images this way will output a full HTML5 <picture> tag. You do not have perfect control over the output, as the <picture> tag is dynamically generated.
2. Kit.Image.Img
   Implementing images this way will output a standalone <img> tag. You do not have perfect control over the output, as the <img> tag is dynamically generated.
3. Custom Markup
   Implementing images this way allows you to define exactly what markup to output but has the drawback of not including the image settings toolbar. This means users must access the image settings via the image field in the primary edit modal.

If done correctly, these implementations will support custom crop settings and dynamic image resizing. Below is an example of a template that outputs the source image in all three ways:

@inherits Custom.Hybrid.RazorTyped
@using ToSic.Razor.Blade;

@{
    var imageSettings = Kit.Image.Settings("Content", width: 400, height: 200, quality: 0.8);
}

<div @Kit.Toolbar.Default(MyItem)>
    
    @* Output full <picture> tag *@
    @Kit.Image.Picture(MyItem.Field("Image"), settings: imageSettings, imgClass: "img-fluid", imgAlt: "alt text here")

    @* Output standalone <img> tag *@
    @Kit.Image.Img(MyItem.Field("Image"), settings: imageSettings, imgClass: "img-fluid", imgAlt: "alt text here")

    @* Output fully custom markup using data from Kit.Image.Img *@
    @{
        var imgFullControl = Kit.Image.Img(MyItem.Field("Image"), settings: imageSettings);
    }
    <img
        src="@(imgFullControl.Src)"
        srcSet="@(imgFullControl.SrcSet)"
        class="img-fluid"
        alt="alt text here"
    />
</div>

Image Resize Settings

The image settings at the top (line 4) determine the resizing options for the image output. The image will be resized to a 400x400 square at 0.8 quality in this case. If the desired height is not known, the height property can be substituted with an aspect ratio:

aspectRatio: ((double)16 / 9)

The (double) here is vital, as it serves to cast one of the integers to a double, which prevents the use of integer division. Without this, integer division will cause the aspect ratio to be evaluated incorrectly. In this case, 16/9 would evaluate to 1, resulting in a square image.

Using both a height value and an aspectRatio value in the same set of settings will result in an error.