Try our conversational search powered by Generative AI!

Dan Matthews
Mar 26, 2010
(3 votes)

A few tips on UI Plugins in CMS6

I have been building some quite complex admin mode plugins, and have come across a few tips that I think I should share. I may accumulate more tips, and if I do so then I’ll add them to this post :)

  • Inherit from EPiServer.UI.SystemPageBase to get access to all the UI goodies
  • Use the system master page to get all the UI skinning. The best way to do this is add it at runtime in your plugin code:

    protected override void OnPreInit(EventArgs e)
        this.MasterPageFile = ResolveUrlFromUI("MasterPages/EPiServerUI.master");
        this.SystemMessageContainer.Heading = "My Plugin Name";

  • Use the same runtime technique to set the heading for your page (see above)
  • To write out messages to the nice yellow box at the top of your page use:

    base.SystemMessageContainer.Message = "My message";
  • The master page includes a nice validation summary area all ready for you to use. So use validators and let the page do it's thing.
  • As the design-time controls in Visual Studio won’t know anything about the master page, they will expect a fully-formed ASPX page. You may find it helps  to add a temporary master page with content areas you need, then reference that instead so that the VS.Net designer is happy. You will be swapping it out at runtime anyway:

    <%@ Page Language="c#" Codebehind="MyPlugin.aspx.cs" AutoEventWireup="True" Inherits="MyNamespace.MyPlugin" MasterPageFile="~/MyFolder/Temporary.Master" %>
  • To be able to use all the nice things such as the EPiServer skinned tool buttons, you’ll need to register the EPiServer UI tag prefixes in the Web.Config. Just add the following lines into system.web->pages->controls:

    <add tagPrefix="EPiServerUI" namespace="EPiServer.UI.WebControls" assembly="EPiServer.UI" />
    <add tagPrefix="EPiServerScript" namespace="EPiServer.ClientScript.WebControls" assembly="EPiServer" />
    <add tagPrefix="EPiServerScript" namespace="EPiServer.UI.ClientScript.WebControls" assembly="EPiServer.UI" />

  • CMS6 has a funky new Page Extension for preventing forged pages. This is awesome, and the SystemPageBase class which you normally inherit from for UI plugins switches it on by default. In theory, you can override this by simply calling the base constructor for it from your constructor like so:

    public MyPlugin() : base(0, AntiForgeryValidation.OptionFlag)

    However, for some reason this isn’t switching it off. As far as I can tell it should, but I haven’t followed the logic so I imagine that the bitwise operation later on is re-enabling it.
  • The same anti-forgery device effectively switches off the ability to use Server.Transfer. You can only use Response.Redirect. Not that you’d want to use Server.Transfer anyway, but it causes an anti-forgery exception. If you’re interested in how it works… on every fresh page request (non-postback), a token is stored in a cookie and a token is also stored in the page itself. On a postback, the anti-forgery Page Extension checks that the two match. This ensures that nothing has been messed with between the original page and the postback. A Server.Transfer doesn’t regenerate that token though, so after a Server.Transfer, any postback will fire an anti-forgery Exception. You can do a Server.Transfer and pass the form values across as well to try and get around the check, but the clever boffins in development thought of that :) When it does the comparison check, it also includes a salt based on the current execution path. So… if you Server.Transferred the page, then the execution path is different, so the salt + page token combo is different, and the anti-forgery is fired.
  • Don’t use the key ‘ID’ for any QueryString value when using Response.Redirect. The outgoing URL rewriter will interpret it as an EPiServer CMS page, and try and rewrite your URL, messing it up. You’ll then wonder why you are getting a 403 or 404 in response. Use ‘SomeOtherID’ instead :)

I hope that these tips are of some use to people getting stuck into CMS6! Note that some of them might also apply to CMS5, but most won’t.


Mar 26, 2010


Sep 21, 2010 10:33 AM

Great post
/ Per Nergard

Sep 21, 2010 10:33 AM

Thank you! Came in very handy already today.

Magnus Rahl
Magnus Rahl Sep 21, 2010 10:33 AM

Two suggestions for additions: 1) How get your validation messages etc in the nice yellow message box used everywere in admin.I remember it was really simple and looked really nice, but I don't remember off the top of my head how to do it. And 2) A pattern for using an async process (like in the rebuild segments task) so that massive admin tasks don't hit the request timeout.

Sep 21, 2010 10:33 AM

Answer for Q1: Use the other properties on SystemMessageContainer to show Warning messages, link to help page, etc.

Gatis Bergšpics
Gatis Bergšpics Oct 13, 2011 03:04 PM

very useful hints

Johan Book
Johan Book Oct 27, 2011 11:24 AM

Very very nice! Thanks for sharing!

Kenia Gonzalez
Kenia Gonzalez Jan 23, 2012 03:56 PM

So very useful! Thanks for the post Dan!

Jan 26, 2012 04:58 PM

Extremely useful. Thanks!

Please login to comment.
Latest blogs
New Series: Building a .NET Core headless site on Optimizely Graph and SaaS CMS

Welcome to this new multi-post series where you can follow along as I indulge in yet another crazy experiment: Can we make our beloved Alloy site r...

Allan Thraen | Jun 14, 2024 | Syndicated blog

Inspect In Index is finally back

EPiCode.InspectInIndex was released 9 years ago . The Search and Navigation addon is now finally upgraded to support Optimizely CMS 12....

Haakon Peder Haugsten | Jun 14, 2024

Change the IP HTTP Header used for geo-lookup in Application Insights


Johan Kronberg | Jun 10, 2024 | Syndicated blog

Copying property values

In this article I’d like to show simple Edit Mode extension for copying property values to other language versions. In one of my previous blogposts...

Grzegorz Wiecheć | Jun 8, 2024 | Syndicated blog

Auto-translate with OpenAI GPT-4o in Optimizely CMS

Improvements for Episerver.Labs.LanguageManager! It's now possible to auto-translate both a page and its children at the same time! Additionally, m...

Tomas Hensrud Gulla | Jun 7, 2024 | Syndicated blog

Upgrade To Optimizely CMS 12 Issue: List item fields have become Required

There are many funny details to be aware of when upgrading from Episerver CMS 11 to Optimizely CMS 12. One of them that might feel a bit confusing ...

Allan Thraen | Jun 7, 2024 | Syndicated blog