In this tutorial, you will learn how to create a block preview controller within Episerver CMS. A preview controller will give content editors the ability to see how a block will look like when it renders on the website 🔥🔥🔥
Previewing a page within Episerver CMS will work as expected, however, when you try to preview a block within a ContentArea, out-of-the-box you will encounter a 'Preview is not available for this item' error, as shown below:
When a block is added within a content area, Episerver MVC looks for a matching block controller to render the block. An important thing to understand is that the routing rules are very different for pages and blocks. A page can have its own routing rule. A block is contained within a page and it does not have its own special URL in order to access it directly. This is why we have two base controllers in our project for blocks and pages. There are fundamental differences.
Our problem arises when we try to preview a block within the editor from a content area. In preview mode, the block effectively becomes a page. It needs its own unique URL for the preview to work. The request pipeline tries to find a matching page-level controller and fails.
Instead of having to create two controllers for every block (normal view and preview view), we can create a single preview block controller that handles all preview requests for any block. This controller will be called... PreviewController 💥.
The Preview Controller
To create a preview controller, we need to create a class that inherits from IRenderTemplate. I also personally like to create a base preview block class in case we need to add in extra preview specific functionality later on. THe code to do this is shown below:
The preview controller code would now look like this:
Notice the [TemplateDescriptor] attribute. The TemplateDescriptor allows us to add extra metadata to the request. Below breaks down these properties:
TemplateType: This is used with the
TemplateTypeCategoriesenum. This property allows you to define the type of render template the controller should perform a match on.Tags: This defines an Episerver tag to match on. Use
RenderingTags.PreviewandRenderingTags.Edit.RenderingTagslives inEPiServer.Framework.Webassembly. For a preview controller, we only care about matching when we're inEditorPreviewmode, however, be aware there are other options!
*Preview View Model: Next, we need to define the view model that controller will use:
The View: In order to render a block, we can add this HTML into the associated cshtml file:
If you run the code above you should now see a block render in your preview.
If you run the code above you should now see a block render correctly when previewing it in the editor 💥.
Previewing With Display Options: It is also possible to change this controller to work with display options. If you want to learn how to do that read this article.
You now know how to make the preview feature work when viewing blocks within the Episerver editor. All the above code can be downloaded in a fully working website from my GitHub account here. Happy Coding 🤘
