Media types and templates

Media and media types work as follows:

• A media type defines a set of properties.
• An instance of media is of the .NET class that defined the media type.
• When you create or upload media, the editor assigns values to the properties defined by the media type.
• When an instance of media is requested by a visitor, the default handler for media sends the binary data to the visitor.
• The templates specify available media types; no built-in media types exist.

NOTE: You can create specific classes for handling media of type images, video, and anything generic other than video or image, such as text or PDF files.

Media are structured using folders. A folder in the media structure can have other folders or media as children, but a media instance cannot have any children. You can set access rights on folders to control availability for editors. The media structure is defined by the following criteria:

• Set the global media root folder as GlobalAssetsRoot, defining media that is available for content on all sites in an enterprise scenario with multiple sites.
• Set a site-specific media root folder as SiteAssetsRoot, defining media that is available only for a specific site. In a single site scenario, the GlobalAssetsRoot and SiteAssetRoot typically point to the same folder.
• Use a Folder, as an instance of ContentFolder, to structure content. A content folder does associate with a Web Form or MVC controller, so it does not appear on the site.

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

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

Setting up specialized media types

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

The following example shows how you can set up generic media types, and 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

The MediaDescriptor attribute defines a list of file extensions and associates specific file types to a given content type, which creates content of the correct content type when a user uploads media via the user interface.

When you create media content from the server side, you also can have this same content type resolve by using the ContentMediaResolver class.

Image descriptor attribute

The ImageDescriptor attribute automatically generates scaled images. The following example shows the ImageData.Thumbnail property that has an ImageDescriptor attribute:

/// <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 you route to a BLOB type property, EPiServer determines whether the BLOB is null and the property has an ImageDescriptor attribute. If both are true, then it automatically generated as scaled image from IBinaryStorable.BinaryData.

Implementing an HTTP media handler

The built-in EPiServer.Web.ContentMediaHttpHandler delivers all media by default. However, if you want custom processing before sending the media to the visitor, the following example shows how 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)
    }
}