In today’s post, I’m going to talk a little about how Episerver works and how we can take advantage of that fact to render custom HTML for Episerver properties like content areas, images or XhtmlString.
Where Are My Episerver Files?
If you have ever wondered where these mystery Episerver files live, then have a look in the ‘Modules’ folder:
In the ‘Modules’ -> ‘_protected’ folder things get a little bit more interesting. If you haven’t had a look through these files I suggest you have a browse and afterwards you should start to see how Episerver integrates with your website, without actually installing any files directly in your solution. Compared to some other CMS solutions this makes deployment so nice and easy. When you have to worry about separation of concerns between CMS core files and your own dev files deployment becomes a lot more complex and this is one of the really nice things about how Episerver works.
To go back to the original point of this post in this situation we care about the zip file ‘EPiServer.Cms.Shell.UI.zip’ in the CMS directly. If you copy the Zip file to somewhere on your PC and unzip it, you will see a bunch of CMS files. If you look in ‘Util’ -> ‘Views’ -> ‘Shared’, you should see a folder called ‘Display Templates’
In the ‘Display Templates’ folder you should see a list of views. The names of these views match the UIHint names for the corresponding Episerver property. Now you have an understanding about how Episerver renders out HTML for it’s properties, we can discuss how we can override it.
Out of the box, Episerver will use these views to render a property. If, however, in your webroots ‘View’ folder, create a matching folder structure ‘Shared’ -> ‘DisplayTemplates’ then copy one of the property HTML files over, when Episerver runs your website it will use the file in your webroot instead of the one within EPiServer.Cms.Shell.UI.zip.
Creating Custom Image HTML
To run through a quick example, if we look in the ‘Image.ascx’ files, you will see this HTML
<%@ Control Language="C#" Inherits="System.Web.Mvc.ViewUserControl<EPiServer.Core.ContentReference>" %> <%@ Import Namespace="EPiServer.Web.Mvc.Html" %> <img src="<%: Url.ContentUrl(Model) %>" alt="" />
Now, say every time we wanted to render an image you want to add a watermark to it, you could completely delete the img tag and instead use a custom HTML helper method that stamps the watermark on it. If you have read my article How To Implement a Donut Hole Cache In Episerver, you can learn how to create a custom HTML helper for a content area (same principles apply).
For a silly example, if you changed Image.ascx to this
<%@ Control Language="C#" Inherits="System.Web.Mvc.ViewUserControl<EPiServer.Core.ContentReference>" %> <%@ Import Namespace="EPiServer.Web.Mvc.Html" %> IMAGE GOES HERE
Instead of rendering images on your website, you will see the text called ‘IMAGE GOES HERE’.
Today’s post is quite simple to implement but from my experience, a lot of developers don’t know that this option is open to them. Understanding how the editor and Episerver manage its files and dependencies is an important aspect in getting the most out of the CMS. I would advise everyone to have a look in the modules folder if they have a spare 5 minutes.
Episerver properties display templates live in the modules folder. These views are used when Episerver renders out each property. You can override this HTML by mirroring the folder structure in EPiServer.Cms.Shell.UI.zip and change the views you want to customise.