Defining image variants

Image variants are user-defined versions of page attachments. You can define each image variant differently so that you have images for various scenarios. For example, you can create image variant definitions for different browser viewports or for various devices such as mobile phones, tablets, desktops, etc.

Each image variant is described by one image variant definition. The image variant definition describes what operations need to be applied to page attachments in order to create image variants.

The image operations are defined by filters. How you use the filters in an image variant definition is up to you. For example, you can use multiple filters or use a filter repeatedly in an image variant definition to achieve the desired effect.

By default, no definitions of image variants are included in the system. To add an image variant definition, you need to create a new class in the Kentico project and implement the image variant definition in code.

Example

Creating image variant definitions

The following example describes how to create a sample image variant definition for a low resolution image variant. The definition uses the sample crop filter to modify images.

1. Open your Kentico solution in Visual Studio (using the WebSite.sln or WebApp.sln file).

2. Create a new Class Library project in the Kentico solution (or reuse an existing custom project), and add the required references.

   • See the Defining image filters example for detailed instructions on how to create the Class library project.

3. Create a new class under your custom project. For example, name the class TabletImageVariantDefinition.cs.

4. Add using statements for the following namespaces.

   Copy

   
   
   
    using System.Collections.Generic;
   
    using CMS.DocumentEngine;
    using CMS.ResponsiveImages;
   
   
    

5. Make the class inherit from the ImageVariantDefinition abstract class (available in the CMS.ResponsiveImages namespace).

6. Override the Identifier and Filters properties of the ImageVariantDefinition class, and implement their functionality.

   • Identifier – the image variant definition identifier. The identifier name cannot start with a number, and can contain only alphanumeric characters or underscores.

   • Filters – a collection of filters that are used to create the image variant. The order of filters in the collection determines the order in which they are applied to images.

     Copy

     
     
     
       public class TabletImageVariantDefinition : ImageVariantDefinition
       {
           // Defines the image variant definition identifier
           public override string Identifier
           {
               get
               {
                   return "Tablet";
               }
           }
     
           // Defines a set of filters applied to images
           public override IEnumerable<IImageFilter> Filters
           {
               get
               {
                   return new IImageFilter[]
                   {
                       new CropImageFilter(768)
                   };
               }
           }
       }
     
     
       

7. Register your image variant definition into the system by adding the RegisterImageVariantDefinition assembly attribute above the class declaration.

   Copy

   
   
   
    // Registers the 'TabletImageVariantDefinition' class within the system
    [assembly: RegisterImageVariantDefinition(typeof(TabletImageVariantDefinition))]
   
   
    

Limiting the scope of image variant definitions

By default, image variant definitions are global and can be applied to any image page attachments. When defining an image variant, you can restrict its scope by specifying context information, i.e. a site code name, page type, and node alias path.

To limit the scope of image variant definitions, you need to override and implement the ContextScopes property. The property can contain multiple context scopes.

For example, the following code demonstrates how to limit the application of an image variant definition only to articles on the Dancing Goat site and news posts on the Corporate Site:

// Sets context scopes to restrict application of the image variant definition
public override IEnumerable<IVariantContextScope> ContextScopes
{
    get
    {
        return new[]
        {
        new AttachmentVariantContextScope()
            .OnSite("DancingGoat")
            .Type("DancingGoat.Article")
            .Path("/Articles", PathTypeEnum.Children),

        new AttachmentVariantContextScope()
            .OnSite("CorporateSite")
            .Type("CMS.News")
            .Path("/News", PathTypeEnum.Children)
        };
    }
}

You can use the OnSite, Type, and Path methods independently and in any order.

Adding a variant display name

By default, the image variant display name that appears in the administration interface is the same as the identifier set for the image variant definition (in the Identifier property).

To assign a custom display name, you need to create a new resource string. The name of the resource string, i.e. the value in the Key field, must be in the following format: AttachmentVariant.<ImageVariantDefinitionIdentifier>

With the definition of the image variant prepared, you can use it to generate image variants for your page attachments.