Add an AdaptiveImage property

The main difference when adding an AdaptiveImage property compared to a SingleImage is that different constraints can be specified for each form factor.

1. Add property to block or page type

using AdaptiveImages.Models;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

Note: Just like for SingleImage properties, manual cropping is not available unless at least one Proportions attribute is added.

2. Add size constraints

The first Size attribute ensures the original image, or cropping thereof, is at least 1280 pixels wide, regardless of form factor.

The second Size attribute applies only to the Large image, ensuring it is at least 1920 pixels wide and at least 1080 pixels tall.

using AdaptiveImages.Core;
using AdaptiveImages.Models;
using AdaptiveImages.Validation;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    [Size(1280)]
    [Size(1920, 1080, FormFactor.Large)]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

Note: The first Size attribute applies to all form factors since FormFactor is not set, but form factor-specific attributes take precedence.

3. Add proportions constraints

In this example the Large image must have widescreen (16:9) proportions, while the Medium and Small images must be square (1:1).

using AdaptiveImages.Core;
using AdaptiveImages.Models;
using AdaptiveImages.Validation;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    [Proportions(16, 9, FormFactor.Large)]
    [Proportions(1, 1, FormFactor.Small | FormFactor.Medium)]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

Note: The original images do not have to match the specified proportions. They will be cropped as needed automatically when rendered.

4. Combine constraints

Below defines different proportions and sizes for each form factor.

using AdaptiveImages.Core;
using AdaptiveImages.Models;
using AdaptiveImages.Validation;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    // Widescreen image at least 1920x1080 for desktop
    [Size(1920, FormFactor.Large)]
    [Proportions(16, 9, FormFactor.Large)]

    // Portrait proportions at least 1280x960 for tablet
    [Size(1280, FormFactor.Medium)]
    [Proportions(4, 3, FormFactor.Medium)]

    // Square image at least 768x768 for mobile
    [Size(768, FormFactor.Small)]
    [Proportions(1, 1, FormFactor.Small)]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

Note: There is no need to explicitly specify both minimum widths and minimum heights when proportions are constrained.

5. Add multiple proportions

Adding multiple Proportions attributes gives the web editor multiple formats to choose from when cropping.

In this example, Square images (1:1) are valid for any form factor.

For Large images, Landscape and Widescreen are also valid, with Widescreen being the default.

For Medium images, Landscape and Portrait are also valid, with Portrait being the default.

For Small images, Landscape is also valid in addition to the common Square proportions.

using AdaptiveImages.Core;
using AdaptiveImages.Models;
using AdaptiveImages.Validation;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    // For any screen size
    [Proportions(1, 1, "Square")]

    // Desktop formats
    [Proportions(3, 2, FormFactor.Large, "Landscape")]
    [Proportions(16, 9, FormFactor.Large, "Widescreen", IsDefault = true)]

    // Tablet formats
    [Proportions(3, 2, FormFactor.Medium, "Landscape")]
    [Proportions(2, 3, FormFactor.Medium, "Portrait", IsDefault = true)]

    // Mobile formats
    [Proportions(3, 2, FormFactor.Small, "Landscape")]

    // Minimum widths (minimum heights are determined by proportions)
    [Size(1920, FormFactor.Large)]
    [Size(1280, FormFactor.Medium)]
    [Size(768, FormFactor.Small)]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

Note: Mobile images will be square by default since no Proportions attribute has IsDefault = true for the Small form factor.

6. Translating format names

You may use language paths for the proportions names:

using AdaptiveImages.Models;
using AdaptiveImages.Validation;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    [Proportions(2, 3, "/proportions/portrait")]
    [Proportions(3, 2, "/proportions/landscape")]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

7. Customize form factor display names

The default display names are "Desktop", "Tablet", and "Mobile" for the Large, Medium, and Small form factors, respectively.

You can customize form factor display names on a per-property basis by using the DisplayNames attribute.

using AdaptiveImages.Models;
using AdaptiveImages.Shell;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    [DisplayNames(Large = "Widescreen", Medium = "Portrait", Small = "Square")]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

8. Translate form factor display names

You may also use translation keys for the form factor names.

using AdaptiveImages.Models;
using AdaptiveImages.Shell;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    [DisplayNames(Large = "/some/translation")]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

Note: You can override the name for a specific form factor, leaving the others to their defaults.

9. Make it required

To make all form factors required, simply add a RequiredImage attribute.

using AdaptiveImages.Models;
using AdaptiveImages.Validation;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    [RequiredImage]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

By default this also requires an image description (i.e. alt text). You may disable this, and optionally only make some form factors required.

[RequiredImage(FormFactor.Large | FormFactor.Medium, AlternateText = false)]
public virtual AdaptiveImage MyAdaptiveImage { get; set; }

10. Make it localizable

To make an adaptive image localizable, i.e. culture-specific, simply add a CultureSpecificImage attribute.

using AdaptiveImages.Models;
using AdaptiveImages.Validation;
using EPiServer.Core;
using EPiServer.DataAnnotations;

[ContentType]
public class MyPageType : PageData
{
    [CultureSpecificImage]
    public virtual AdaptiveImage MyAdaptiveImage { get; set; }
}

You may optionally specify if only the images and/or the image description (i.e. alt text) should be localizable.

[CultureSpecificImage(Images = false, AlternateText = true)]
public virtual AdaptiveImage MyAdaptiveImage { get; set; }

About image sizes

Size attribute constraints don't necessarily have to match the intended rendering size. It should rather be thought of as the maximum rendering size.

In other words, if MinimumWidth is set to 1920, the image can safely be rendered with any width up to 1920 pixels.

More information: Size constraints versus rendering