This content is archived. See latest version here.

Last updated: Mar 31 2014

When working with content in a content area, editors often want to choose how the content should be laid out. This means choosing a rendering template to display the item. Display options let developers specify which rendering templates may be selected in the user interface.

Configuring display options

To make rendering templates available in the user interface, add an EPiServer.Web.DisplayOption to the display options service, which can be accessed as a singleton via the service locator.

var displayOptions = ServiceLocator.Current.GetInstance<DisplayOptions>();
    id: "promo", 
    tag: "promo",
    // The name and description properties can also be reference keys to a language resource to allow internationalization.
    name: "Promotion", 
    description: "Promotional content is displayed full width and with background highlighing.", 
    iconClass: "icon-promo"

See the EPiServer.Web.DisplayOptions class for more information and method overloads.

Appearance in the user interface

If you add display options to the site, a Display as option appears in the content's context menu within a content area. By default, Automatic is selected. This means that the content uses the rendering template specified by the content area. If the user selects a different display option, that template renders the content.

The display option available for selection in the user interface.

Since all display options are available in the context menu, it is possible to select an option whose tag does not match a rendering template for the content. In this case, a message informs the user that the content cannot be displayed with this option.


Are there any plans to implement this in a way that enables us to do this on a per block type basis?

So, for example, most blocks only have one viewing mode (and thus no viewable Display options menu), but some might have "Wide" and "Narrow", while others have "Full view" and "Basic view" as available modes.

That would be kindof nice, since the only way to achieve this now is to use Dropdown-properties on the content types itself, which ties "Display option" to the content, instead of to the rendering content area.

I agrree with Arve Systad, it seems backwards giving all options then displaying an error when one that's not applicable is selected. Ideally I think you want these configured the same way and an attribute added for a block that allows an enumerable string of names the block support. Then when the block is clicked on only the support display modes are shown

Once I've set a display option for one of my content blocks, how I determine which option was set from my view?

When you log in and view the content, then click its context menu, the Display as menu option shows the current value.

Sorry, I'm referrning more to the content rendering on the page, not the CMS interface.

I am using MVC to render my page, so I have a partial view for use when displaying content from the block in question.  I'm assuming I need to put a check in the partial view to determine which display option the author has chosen and then render different HTML based on that choice.

In the end I discovered that (from the MVC controller) you can access the value the content author selects from the Display as menu option by looking at the RouteData.Values dictionary.  The dictionary contains a "tag" field which corresponds to the value of the "tag" parameter you specify during the displayOptions.Add() method (as documented above).


var renderSettings = this.ControllerContext.RouteData.Values["renderSettings"] as Dictionary<string, object>;

if (renderSettings != null)
    renderSettings.TryGetValue("tag", out tag); // "tag" contains the value of the "tag" parameter of the Display Option
    if (tag != null)
        //logic for changing which view to use based on the value of "tag" goes here


Another thing that would be nice, is if we could vary the available options on different content areas. Especially in multi site environments, this would come in handy. (One site needs "Normal" and "Wide", where a second site might need "Small" too).

Hopefully, this should be possible by adding an editor descriptor to the property on the content type. Maybe set some way to decide what ContentAreaRenderer is used too? So I don't have to mix logic for all different sites into one.