Episerver Adaptive Images add-on
Developer documentation
- Introduction
- Installing
- Adding adaptive image properties
- Rendering adaptive images
- Configuration and settings
- Image providers
- Local development
See the web editor documentation on how to use the add-on in edit mode.
Introduction
This add-on makes it easy to add a new type of image property to content types, with a user-friendly user interface for web editors.
Developers are able to easily define image constraints, such as minimum size and proportions, and web editors can customize images for different screen sizes without risk of violating those restrictions.
Images can reside in Episerver or in external systems for digital asset management (DAM).
End-user images are automatically optimized, cropped, and rescaled, and served through a CDN.
Note: This is optional for local development, but production/high-load environments should always use a CDN for image transformation and delivery.
Installation
- Add NuGet package TedGustaf.Episerver.AdaptiveImages to your Episerver website
- For TinyMCE support, add TinyMCE plugin TinyMceAdaptiveImagePlugin (optional)
- Restart the website
Add an adaptive image property
public virtual AdaptiveImage HomePageHero { get; set; }
Set minimum image size
[Size(1024, 768, FormFactor.Small | FormFactor.Medium)] // Mobile and tablet images must be at least 1024x768 pixels
[Size(1920, 1080, FormFactor.Large)] // Desktop image must be at least 1920x1080 pixels
public virtual AdaptiveImage HomePageHero { get; set; }
Set proportion constraints
[Proportions(16, 9, FormFactor.Large)] // Desktop image should have widescreen proportions
[Proportions(1, 1, FormFactor.Small | FormFactor.Medium)] // Square images for mobile and tablet
public virtual AdaptiveImage HomePageHero { get; set; }
Combining constraints
When a web editor selects or crops images they're validated against these constraints:
[Proportions(16, 9, FormFactor.Large)] // Widescreen proportions
[Size(1920, FormFactor = FormFactor.Large)] // Minimum width of 1920 pixels (height determined by proportions constraint)
public virtual AdaptiveImage HomePageHero { get; set; }
Rendering adaptive images
Default rendering
This will render the image(s) using default breakpoints, automatically cropped according to any constraints:
@Html.PropertyFor(x => x.HomePageHero)
See the Configuration section on how to change the default breakpoints and other settings.
Override default breakpoints and image width(s)
You can specify desired image widths and/or breakpoints, if different from the defaults:
@Html.PropertyFor(m => m.HomePageHero, new {
largeBreakpoint: 1280, // Desktop breakpoint
mediumBreakpoint: 768, // Tablet breakpoint (767 and below is considered mobile)
largeWidth = 1920, // Desktop image width
mediumWidth = 1279, // Tablet image width
smallWidth = 500 // Mobile image width
})
Apply image transformations
For other custom rendering scenarios, use ImageRenderSettings to apply transformations using a fluent syntax:
// Get the large ("desktop") image, cropped according to constraints and resized to a width of 1280 pixels
var largeImage = new ImageRenderSettings(currentContent.HomePageHero.Large)
.Crop(Model.Large.GetCropSettings())
.ResizeToWidth(1280);
// Create a 300x300 square version of the large ("desktop") image, regardless of proportions constraints
var squareImage = new ImageRenderSettings(currentContent.HomePageHero.Large)
.Crop(new Proportions(1, 1))
.ResizeToWidth(300);
Render a specific image
You can render an <img> element based on above render settings:
@Html.RenderImage(squareImage)
Get image URLs
If you need to get the final URL of an image, for example to set a background image, create an ImageRenderSettings instance based on the image you want to use and apply any transformations before invoking GetUrl():
@{
// Get the large ("desktop") image scaled to a width of 1920 pixels
var backgroundImageUrl = new ImageRenderSettings(currentContent.HomePageHero.Large)
.ResizeToWidth(1920)
.GetUrl();
}
<div style="background-image: url(@backgroundImageUrl)"></div>
Resolving property image constraints and settings
When creating a view with a model type of AdaptiveImage, size and proportion constraints are not accessible as they're defined through attributes on the parent content, i.e. block or page, instance. However, constraints and crop settings can be retrieved like:
// "Model" below is a page or block instance with an AdaptiveImage property:
// Get all applicable constraints for all form factors
var imageConstraints = Model.GetImageConstraints(x => x.JumbotronImage);
// Get crop settings for the large, i.e. "desktop", image
var largeImageCropSettings = Model.JumbotronImage.GetCropSettings(x => x.Large);
// Get proportions constraints for the large, i.e. "desktop", image
var largeImageProportionsConstraints = Model.JumbotronImage.GetProportionsConstraint(m => m.Large);
// Get size constraints for the large, i.e. "desktop", image
var largeImageSizeConstraints = Model.JumbotronImage.GetSizeConstraint(m => m.Large);
Configuration
Add-on settings
Global add-on settings, such as default breakpoints, are configured through the AddonSettings class:
AddonSettings.LargeBreakpoint = 1200;
AddonSettings.MaximumWidth = 1920;
Image providers
The add-on supports multiple image providers.
There are ready-made image providers for some digital asset management (DAM) systems. Please contact us if you want to integrate an existing DAM or looking for a suitable one.
Add/remove image providers
Image providers are types implenting the IImageProvider interface:
var customProvider = new MyCustomProvider();
ImageProviderFactory.Instance.Register(customProvider);
To remove an image provider:
ImageProviderFactory.Instance.Remove(customProvider.Name);
The user interface lists image providers in the order they appear in ImageProviderFactory:
Dropdowns are displayed for the selected image provider's options. For hierarchical options, multiple dropdowns are displayed.
Note: Only image providers with at least one searchable option (ImageProviderOptionCapability.Search capability) are displayed.
Note that commercial use of image providers requires a "Standard" add-on license or above. Visit episerverimages.com for more information.
Development environment
When using a CDN, it requires access to the website to retrieve images for transformation, so your development environment needs to be accessible over the internet.
In other words, if the website is run locally on localhost, you need to make it accessible over the internet when CDN features are enabled.
For local development, we recommend not enabling CDN features other than for testing. However, this will affect auto-cropping features. Note that production or high-load environments should always have a CDN enabled.
ngrok is one viable option for enabling a proxy to make your local development environment accessible over the internet.