Route Hijacking in Umbraco: A Step by Step Tutorial

What is Umbraco Route Hijacking?

By default, all front-end requests to an Umbraco site are handled automatically by Umbraco, and a default Umbraco project doesn't contain any controller files. However, if you as a developer need to access a controller to perform tasks that Umbraco doesn't handle by default, route hijacking becomes useful. Route hijacking allows you to take control of the routing for specific document types, enabling you to execute custom logic and render views as needed.

Create a Controller Class Matching the Document Type Alias

To intercept a page in Umbraco, create a controller class named after the document type alias. For example, if your document type is called "Home," with an alias of "Home," your controller class should be named HomeController.

The controller should inherit from RenderController, which allows you to work with the page's content and rendering.


public class HomeController : RenderController
{
    // Controller code here
}

This step ensures that your controller can access and manage the content of the corresponding Umbraco page

Access the Content Node (Model)

To access the content node or model, you can cast the CurrentPage property to your strongly typed model. This gives you full access to the content and properties of the page, allowing you to customize how the data is presented. For more details on how to use strongly typed models with Umbraco, refer to my article on Models Builder

For example, if your document type is "Home," you can cast CurrentPage like this:


var model = (Home)CurrentPage;

This allows you to work with the properties defined in your "Home" document type directly.

Returning the View

Route hijacking is often used to change the view that is returned or to pass a different model back to the template. This allows you to present data in a customized way.

In the example below, I use data from the content node/model (like CurrentPage) to populate a view model. I can then combine this with other data and return it to the view:


var model = (Search)CurrentPage; // Cast the current page to the strongly typed model

// Get the search query from the URL
string search = HttpContext.Request.Query["query"];

// Perform the search using the search service
var results = searchService.SearchContentNames(query);

// Prepare the view model with the data
SearchViewModel viewModel = new(CurrentPage!, publishedValueFallback)
{
    SearchResults = searchService.SearchContentNames(query),
    HasSearched = !string.IsNullOrEmpty(query),
    ShortDescription = model.ShortDescription,
    Title = model.Title,
    Image = model.Image,
    TypedWords = model.TypedWords
};

// Return the view with the populated view model
return CurrentTemplate(viewModel);

This approach allows you to leverage Umbraco's content while also injecting custom data into the view for more flexibility and control over how the page is rendered

Wrap Up:

Route hijacking lets you customize how pages are rendered in Umbraco. By inheriting from RenderController, accessing the content, and modifying the view model, you can easily adjust page content and layout to meet your needs

For a deeper dive into Umbraco's routing and custom controllers, check out the official Umbraco documentation on Custom Controllers and Routing.