How To Render Custom HTML For Episerver Properties

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?

I’m not sure if you’ve ever considered how the Episerver Nuget feed works. Obviously, Episerver needs files, like Javascript, CSS, images and assemblies to run correctly, however, if you look in a normal Episerver webroot you’ll only be able to find your solution files.

episerver_display_templates_webroot

If you have ever wondered where these mystery Episerver files live, then have a look in the ‘Modules’ folder:

episerver_display_templates_files

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’

episerver_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’.

Conclusion

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.

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

More Posts

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *