Add a SingleImage property

1. Add property to block or page type

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

[ContentType]
public class MyPageType : PageData
{
    public virtual SingleImage MyImage { get; set; }
}

Note: This image may not yet be manually cropped as there is no Proportions attribute.

2. Add size constraint

The following Size attribute ensures the original image is at least 1920 pixels wide and at least 1080 pixels tall, regardless of final rendering size.

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

[ContentType]
public class MyPageType : PageData
{
    [Size(1920, 1080)]
    public virtual SingleImage MyImage { get; set; }
}

Note: Above does not constrain proportions. Any image that satisfies both minimum width and height is considered valid.

3. Add proportions constraint

The following sets the default rendering and cropping proportions to 3:2 which also allows the editor to adjust the crop area and focal point manually.

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

[ContentType]
public class MyPageType : PageData
{
    [Proportions(3,2)]
    public virtual SingleImage MyImage { get; set; }
}

Note: The original image does not have to match the specified proportions. It will be cropped as needed automatically when rendered.

4. Combine constraints

The following defines a widescreen (16:9) image with a minimum size of 1920x1080 px.

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

[ContentType]
public class MyPageType : PageData
{
    [Size(1920)]
    [Proportions(16, 9)]
    public virtual SingleImage MyImage { get; set; }
}

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

5. Add multiple proportions

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

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

[ContentType]
public class MyPageType : PageData
{
    [Size(1920)]
    [Proportions(2, 3, "Portrait")]
    [Proportions(16, 9, "Widescreen", IsDefault = true)]
    [Proportions(1, 1, "Square")]
    public virtual SingleImage MyImage { get; set; }
}

Note: The first Proportions attribute will be the default if no attribute has IsDefault=true.

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 SingleImage MyImage { get; set; }
}

7. Prevent manual cropping and focal point

By default, each format allows the web editor to manually adjust the crop area and/or focal point. To prevent one or both of these options, set AllowCropping and/or AllowFocalPoint to false.

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

[ContentType]
public class MyPageType : PageData
{
    [Proportions(3,2, AllowCropping = false, AllowFocalPoint = false)]
    public virtual SingleImage MyImage { get; set; }
}

9. Make it required

To make an image 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 SingleImage MyImage { get; set; }
}

By default this also requires an image description (i.e. alt text). You may disable this by setting AlternateText to false.

[RequiredImage(AlternateText = false)]
public virtual SingleImage MyImage { get; set; }

10. Make it localizable

To make an 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 SingleImage MyImage { get; set; }
}

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

[CultureSpecificImage(Images = false, AlternateText = true)]
public virtual SingleImage MyImage { 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