Media types and templates

This section contains information about a central concept of an EPiServer CMS project, namely that of media (for example files) and media types.

This is how it works:

• A media type defines a set of properties.
• A media is an instance of the .NET class that defined the media type.
• When creating/uploading a media the editor assigns values to the properties defined by the media type.
• When a media is requested by a visitor, the default handler for media is used to send the binary data to the visitor.
• Available media types are specified in the templates, no built-in media types exist

Media type

During initialization EPiServer CMS will scan all assemblies in the bin folder for .NET classes decorated with [ContentType]-attribute, a media type must inherit from MediaData as example below.

[ContentType]
public class CustomFile : MediaData
{
    public virtual string Copyright { get; set; }
}

Specialized media types

ImageData and VideoData are two specialized base classes that allow the system to distinguish images and videos from other generic media in order to apply special handling in the user interface. For example types inheriting ImageData will display thumbnails in the user interface. Both ImageData and VideoData inherit from MediaData.

The following example shows how you can setup types for both generic media but also images and video:

 [ContentType(GUID = "EE3BD195-7CB0-4756-AB5F-E5E223CD9820")]
 public class GenericMedia : MediaData
 {
     public virtual string Description { get; set; }
 }

 [ContentType(GUID = "0A89E464-56D4-449F-AEA8-2BF774AB8730")]
 [MediaDescriptor(ExtensionString = "jpg,jpeg,jpe,ico,gif,bmp,png")]
 public class ImageFile : ImageData
 {
     public virtual string Description { get; set; }
     public virtual string Copyright { get; set; }
 }

[ContentType(GUID = "85468104-E06F-47E5-A317-FC9B83D3CBA6")]
[MediaDescriptor(ExtensionString = "flv,mp4,webm")]
public class VideoFile : VideoData
{
     public virtual string Description { get; set; }
}

Media descriptor attribute

As you may have noticed in the ImageFile content type above, there is a MediaDescriptor attribute that defines a list of file extensions. This attribute is used to associate specific file types to a given content type. This allows the system to create content of the correct content type when a user uploads media via the user interface.

When creating media content from the server side it is also possible to have this same content type resolving by using the ContentMediaResolver class.

Image descriptor attribute

The ImageDescriptor attribute is used when scaled images are automatically generated. An example of that is the property ImageData.Thumbnail property that has an attribute as below:

/// <summary>
/// Base class for content types which should be handled as images by the system.
/// </summary>
public class ImageData : MediaData
{
    /// <summary>
    /// Gets or sets the generated thumbnail for this media.
    /// </summary>
    [ImageDescriptor(Width = 48, Height = 48)]
    public override Blob Thumbnail
    {
        get { return base.Thumbnail; }
        set { base.Thumbnail = value; }
    }
}

When a property of type BLOB is routed to, if the BLOB is null a check is done if the property have the ImageDescriptor attribute. If so a scaled image is automatically generated from IBinaryStorable.BinaryData.

Media handler

By default all media are delivered via the built-in EPiServer.Web.ContentMediaHttpHandler so you do not need to add a custom handler for media. In some scenarios you may want to do custom processing before sending the media to the visitor and then as shown below you can implement your own HTTP Handler. Handlers for media uses the same templating system as other content types in CMS which means you can use any type of template for media, you are not limited to HTTP handlers.

public partial class CustomFileHandler : IHttpHandler, IRenderTemplate<CustomFile>
{
    public bool IsReusable
    {
        get { return false; }
    }

    public void ProcessRequest(HttpContext context)
    {
        //Get file content
        var routeHelper = ServiceLocator.Current.GetInstance<ContentRouteHelper>();
        var content = routeHelper.Content;

        if (content == null)
        {
            throw new HttpException(404, "Not Found.");
        }

        //Check access
        if (!content.QueryDistinctAccess(AccessLevel.Read))
        {
            var accessDenied = DefaultAccessDeniedHandler.CreateAccessDeniedDelegate();
            accessDenied(this);
            return;
        }

        //Cast to custom file
        var customFile = content as CustomFile;
        if (customFile == null || customFile.BinaryData==null)
        {
            throw new HttpException(404, "Not Found.");
        }

        //Set caching policy
        context.Response.Cache.SetCacheability(HttpCacheability.Private);
        context.Response.Cache.SetMaxAge(TimeSpan.FromDays(1));

        //Do custom processing
        //TransmitProcessedFile(customFile.BinaryData)
    }
}

Media structure

Media are structured using folders. A folder in the media structure can have other folders or media as children, but a media instance can not have any children. Access rights can be set on folders to control availability for editors.

The media structure is defined by the following:

• The global media root folder is set as GlobalAssetsRoot, defining media that will be available for content on all sites in an enterprise scenario with multiple sites.
• A site-specific media root folder is set as SiteAssetsRoot, defining media that will only be available for a specific site. In a single site scenario, the GlobalAssetsRoot and SiteAssetRoot will typically point to the same folder.
• A Folder is an instance of ContentFolder, and is used to structure content. A content folder does not have any WebForm or MVC controller associated, and hence has no visual appearance on the site.