Display options

Introduction

When working with content in a content area, it is often the case that editors would like to specifically choose how the content should be laid out; which means choose which rendering template should be used to display each item. Display options provide the means for developers to specify which render templates should be available for selection in the user interface.

Configuring the display options

Making rendering templates available for selection in the user interface can be done simply be adding a 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>();
displayOptions.Add(
    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

Adding display options to the site will automatically enable an addition option in the context menu for content within a content area. By default the Automatic option is selected. This means that the content is using the rendering template specified by the content area. Selecting a display option other than automatic will cause that particular content in that content area to be rendered using the rendering template associated with the display option.

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 given content. In this scenario a message is rendered, instead of the content, which informs the user that the content can not be displayed with this chosen display option.