Display channels

Display channels let you control the rendering of content, such as controlling which templates (WebForm, UserControl, View or partial view) you should use to render, depending on the request (for example, which browser it is). You also can have a single template but in that template check which channels are active and then control output (such as which stylesheet to use), depending on active channel. This means you can target the output for example specific devices.

• WebForms: DisplayChannel
• MVC: IDisplayMode
• DisplayChannelService
• Previewing content
• Adding a new device to view resolution

WebForms: DisplayChannel

To create a DisplayChannel to use with WebForms, create a class that inherits EPiServer.Web.DisplayChannel. You do not need to explicitly register the channel. During initialization, the system scans and registers all found channel instances. The IsActive methods adds logic that controls whether your channel can be considered active for a request. When the system tries to resolve which template (WebForms or UserControl) to use to render an item, it checks which DisplayChannels are active and then prefers templates that have a tag included in EPiServer.Framework.DataAnnotations.TemplateDescriptorAttribute.Tags that matches EPiServer.Web.DisplayChannel.ChannelName for the active channel.

The following example shows a simple DisplayChannel that is active for mobile devices:

public class MobileDisplayChannel : DisplayChannel
{
    public override bool IsActive(HttpContextBase context)
    {
        return context.Request.Browser.IsMobileDevice;
    }

    public override string ChannelName
    {
        get { return RenderingTags.Mobile; }
    }
}

If you have two different templates registered for same type and one template has a tag that matches the ChannelName then that template is used when the channel is active.

The following example shows two different templates for same type:

[ContentType]
public class MyBlock : BlockData {}

[TemplateDescriptor(Default=true)]
public partial class MyBlockControl : BlockControlBase<MyBlock>
{ }

[TemplateDescriptor(Tags = new string[] { RenderingTags.Mobile })]
public partial class MyBlockMobileControl : BlockControlBase<MyBlock>
{ }

MVC: IDisplayMode

To register a System.Web.WebPages.IDisplayMode to use with MVC, you register your instance with EPiServer.Web.DisplayChannelService. The reason for registering the IDisplayMode towards Episerver (and not directly against ASP.NET) is so editors can preview the channel even if the request itself does not match the channel condition. That is, so an editor can view the site as it appears for a mobile device even if the editor is working on a regular browser. Otherwise the same conventions as for System.Web.Mvc apply; if a “mobile” channel is active then the convention is to prefer a view named like Index.mobile.cshtml before one named Index.cshtml.

The following example shows how to register a simple IDisplayMode that is active for mobile devices:

public void Initialize(EPiServer.Framework.Initialization.InitializationEngine context)
{
    context.Locate.DisplayChannelService()
        .RegisterDisplayMode(new DefaultDisplayMode(RenderingTags.Mobile)
    {
        ContextCondition = (r) => r.Request.Browser.IsMobileDevice
    });
}

DisplayChannelService

If you need to know which channels are active for a request, get the active channels from EPiServer.Web.DisplayChannelService. You can retrieve the service from EPiServer.ServiceLocation.ServiceLocator.Current or from EPiServer.ServiceLocation.ServiceLocationHelper, which is exposed in several locations, such as in PageBase, UserControlBase, InitializationEngine if you have a using statement for EPiServer.Web namespace. This can be useful when you want to select stylesheet depending on active channel.

The following example shows how to set a CSS class depending on whether a mobile channel is active:

public partial class ABlockControl : BlockControlBase<MyBlock>
{
    protected override void OnLoad(EventArgs e)
    {
        base.OnLoad(e);
        CssClass = Locate.DisplayChannelService().GetActiveChannels(new HttpContextWrapper(HttpContext.Current))
            .Any(c => String.Equals(c.ChannelName, RenderingTags.Mobile, StringComparison.OrdinalIgnoreCase)) ?
            "MobileMainArea" : "MainArea";
    }

    protected String CssClass { get; set; }
}

Previewing content

An editor can preview the site with different channels active. When the editor selects to preview the site for a specific channel, requests to IsActive on the DisplayChannel and IDisplayMode instances are short-cutted, and the one that is selected for preview “fakely” returns true for the request.

Adding a new device to view resolution

You can change the size of the preview view port to give the editor a quick way of visualizing a page as it would turn out when shown on a smaller screen. A few devices are set up in the Alloy Templates project, and you can add your own.

This following section describes adding a preview option for the Google Nexus 7 tablet to the preview resolutions drop-down list.

The hardware specifications show that the native display resolution on the Nexus 7 is 1280 by 800 pixels, but you cannot use these values straight away because most high resolution mobile devices apply scaling and actually report different screen dimensions than the physical ones. For example, the iPhone 4 reports the same screen dimensions as the iPhone 3, even though its display has four times as many pixels. Therefore you need to know which resolution the device actually reports to get as close as possible to reality. You can use this screen size test page at Quirksmode.org with the device in question and check the reported window width and height. For the Nexus 7 in portrait mode you get a reported canvas size of 600 by 790 pixels, and in landscape mode 960 by 440 pixels. The difference in width/height between the different modes is caused by soft buttons and browser chrome (location bar and tabs).

When you have this information, you can add a new option to the resolution section of the view drop-down list by implementing the EPiServer.Web.IDisplayResolution interface.

public class Nexus7PortraitResolution : IDisplayResolution
{
    public string Id
    {
        get { return GetType().Name; }
    }

    public string Name
    {
        get { return "Google Nexus 7 Portrait"; }
    }

    public int Height
    {
        get { return 790; }
    }

    public int Width
    {
        get { return 600; }
    }
}

Build and reload, and the new display resolution option is available.

Adding a background device image

If you inspect the HTML structure around the preview iframe you will notice an auto-generated CSS class named epi-viewPort-600x790, where the numbers correspond to the dimensions specified in the definition. Define this CSS class to customize the look of the view port – assuming you are in the Alloy sample project – you add a new CSS file ClientResources/Style/displayresolutions.css with the following contents:

.epi-viewPort-600x790
{
    background: url('../images/nexus7.png') no-repeat center center;
}

The image nexus7.png referenced in the CSS class above is a background image picturing the Nexus 7, and is shown behind the scaled down view port.

To get this CSS file loaded when the user interface loads, piggy-back on the CMS module’s resource bundle. Knowing that the CMS module depends on a epi.cms.widgets.base resource bundle, add your CSS file to this resource bundle from the module.config of your project.

<clientResources>
    <add name="epi.cms.widgets.base" path="Styles/displayresolutions.css"
         resourceType="Style" isMinified="false" />
</clientResources>

The displayresolutions.css file is loaded whenever the CMS module is started; in other words, when going to the editorial interface.

Note: There is no file watch on module.config, so changes are not picked up automatically by the application. Therefore you have to touch web.config or restart the application by other means to see the changes on the site.

Select Nexus 7 in the resolution drop-down and get the preview as shown below, with the browser preview to the left and the actual rendering to the right for comparison.

While this approach does not give the exact same result as on the actual device, it can give the editor a very close idea of how a page will look on a different screen.