Custom MVC routing in Umbraco

This post will describe how you can declare your own custom MVC routes in order to execute your own custom controllers in Umbraco but still be able to render Umbraco views with the same model that Umbraco uses natively.

NOTE: This post is not about trying to execute a particular Umbraco page under a custom URL, that functionality can be accomplished by creating a custom IContentFinder (in v6.1), or by applying the umbracoUrlAlias

There’s a long (but very useful) thread on Our describing various needs for custom MVC routing inside of Umbraco, definitely worth a read. Here I’ll try to describe a pretty easy way to accomplish this. I’m using Umbraco v6.0.7 (but I’m pretty sure this will work in v4.10+ as well).

Create the route

This example will use an IApplicationEventHandler (in 6.1 you should use the base class ApplicationEventHandler instead). Here I’m defining a custom route for handling products on my website. The example URLs that I want handled will be:

/Products/Product/ProductA
/Products/Category/CategoryA

public class MyStartupHandler : IApplicationEventHandler
{
    public void OnApplicationStarted(
        UmbracoApplicationBase umbracoApplication, 
        ApplicationContext applicationContext)
    {
        //Create a custom route
        RouteTable.Routes.MapRoute(
            "test",
            "Products/{action}/{id}",
            new
                {
                    controller = "MyProduct", 
                    action = "Product", 
                    id = UrlParameter.Optional
                });           
    }
    public void OnApplicationInitialized(
        UmbracoApplicationBase umbracoApplication, 
        ApplicationContext applicationContext)
    {
    }
    public void OnApplicationStarting(
        UmbracoApplicationBase umbracoApplication, 
        ApplicationContext applicationContext)
    {
    }
}

Create the controller

With the above route in place, I need to create a controller called “MyProductController”. The base class it will inherit from will be “Umbraco.Mvc.PluginController”. This abstract class exposes many of the underlying Umbraco objects that I might need to work with such as an UmbracoHelper, UmbracoContext, ApplicationContext, etc… Also note that the PluginController doesn’t get auto-routed like a SurfaceController which is good because we only want to route our controller once. In 6.1 you can inherit from a different controller called Umbraco.Mvc.UmbracoController, which is what the PluginController will be inheriting from in the next version.

Constructor

First thing is to define the constructors since the PluginController doesn’t have an empty constructor but we want ours to (unless you have IoC setup).

public class MyProductController : PluginController
{
    public MyProductController()
        : this(UmbracoContext.Current)
    {            
    }

    public MyProductController(UmbracoContext umbracoContext) 
        : base(umbracoContext)
    {
    }
}

Actions

Next we need to create the controller Actions. These actions will need to lookup either a Product or a Category based on the ‘id’ string they get passed. For example, given the following URL: /Products/Category/CategoryA the id would be CategoryA and it would execute on the Category action.

In my Umbraco installation, I have 2 document types with aliases: “Product” and “ProductCategory”

To perform the lookup in the controller Actions we’ll use the UmbracoHelper.TypedSearch overload which uses Examine.

public ActionResult Category(string id)
{
    var criteria = ExamineManager.Instance.DefaultSearchProvider
        .CreateSearchCriteria("content");
    var filter = criteria.NodeTypeAlias("ProductCategory").And().NodeName(id);
    var result = Umbraco.TypedSearch(filter.Compile()).ToArray();
    if (!result.Any())
    {
        throw new HttpException(404, "No category");
    }
    return View("ProductCategory", CreateRenderModel(result.First()));
}

public ActionResult Product(string id)
{
    var criteria = ExamineManager.Instance.DefaultSearchProvider
        .CreateSearchCriteria("content");
    var filter = criteria.NodeTypeAlias("Product").And().NodeName(id);
    var result = Umbraco.TypedSearch(filter.Compile()).ToArray();
    if (!result.Any())
    {
        throw new HttpException(404, "No product");
    }
    return View("Product", CreateRenderModel(result.First()));
}

The Category action lookup uses Examine to lookup any document with:

A document type alias of “ProductCategory”
A name equal to the id parameter passed in

The Product action lookup uses Examine to lookup any document with:

A document type alias of “Product”
A name equal to the id parameter passed in

The result from TypedSearch is IEnumerable<IPublishedContent> and since we know we only want one result we pass in the first item of the collection in “result.First()”

If you didn’t want to use Examine to do the lookup, you could use a Linq query based on the result of Umbraco.TypedContentAtRoot(), but I wouldn’t recommend that since it will be much slower.

In v6.1 the UmbracoHelper exposes a couple of other methods that you could use to perform your lookup if you didn’t want to use Examine and wanted to use XPath instead:

TypedContentSingleAtXPath(string xpath, params XPathVariable[] vars)
TypedContentAtXPath(string xpath, params XPathVariable[] vars)
TypedContentAtXPath(XPathExpression xpath, params XPathVariable[] vars)

CreateRenderModel method

You will have noticed that I’m using a method called CreateRenderModel to create the model that is passed to the View. This method accepts an IPublishedContent object as an argument and creates a RenderModel object which is what a normal Umbraco view expects. This method isn’t complex but it does have a couple things worth noting:

private RenderModel CreateRenderModel(IPublishedContent content)
{
    var model = new RenderModel(content, CultureInfo.CurrentUICulture);

    //add an umbraco data token so the umbraco view engine executes
    RouteData.DataTokens["umbraco"] = model;

    return model;
}

The first thing is that you need to construct the RenderModel with an explicit culture otherwise you’ll get an exception. The next line adds the created RenderModel to the RouteData.DataTokens… this is because we want to render an Umbraco view which will be stored in either of the following places (based on Umbraco standard practices):

~/Views/Product.cshtml
~/Views/ProductCategory.cshtml

These locations are not MVC standard practices. Normally MVC will look in a controller specific folder for views. For this custom controller the locations would be:

~/Views/MyProduct/Product.cshtml
~/Views/MyProduct/ProductCategory.cshtml

But we want to use the views that Umbraco has created for us so we need to ensure that the built in Umbraco ViewEngine gets executed. For performance reasons the Umbraco RenderViewEngine will not execute for a view unless a RenderModel instance exists in the RouteData.DataTokens with a key of “umbraco”, so we just add it there before we return the view.

Views

The views are your regular Umbraco views but there’s a few things that might not work:

Macros. Sorry, since we’ve bypassed the Umbraco routing pipeline which macros rely upon, any call to Umbraco.RenderMacro will fail. But you should be able to achieve what you want with Partial Views or Child Actions.
Umbraco.Field. Actually this will work but you’ll need to upgrade to 6.0.7 or 6.1.2 based on this fixed issue: http://issues.umbraco.org/issue/U4-2324

One cool thing is that you can use the regular MVC UrlHelper to resolve the URLs of your actions, since this custom controller is actually just a regular old MVC controller after all.

These view example are nothing extraordinary, just demonstrating that they are the same as Umbraco templates with the same model (but using our custom URLs)

ProductCategory

@inherits Umbraco.Web.Mvc.UmbracoTemplatePage
@{
    Layout = null;
}
<html>
    <body>
        <h1>Product category</h1>
        <hr />
        <h2>@Model.Content.Name</h2>
        <ul>
            @foreach (var product in Model.Content.Children
                .Where(x => x.DocumentTypeAlias == "Product"))
            {
                <li><a href="@Url.Action("Product", "MyProduct", new { id = product.Name })">
                        @product.Name
                    </a>
                </li>
            }
        </ul>
    </body>
</html>

Which looks like this:

Product

@inherits Umbraco.Web.Mvc.UmbracoTemplatePage
@{
    Layout = null;
}
<html>
    <body>

        <h1>Product</h1>
        <hr />
        <h2>@Model.Content.Name</h2>
        <div>
            @(Model.Content.GetPropertyValue("Description"))
        </div>
    </body>
</html>

Which looks like this:

Whats next?

With the setup above you should be able to achieve most of what you would want with custom routing, controllers, URLs and lookups. However, as I mentioned before things like executing Macros and potentially other internal Umbraco bits that rely on objects like the PublishedContentRequest will not work.

Of course if there is a will, there is a way and I have some cool ideas that could make all of those things work seamlessly too with custom MVC routes. Stay tuned!

Shazwazza

My blog which is pretty much just all about coding