In this tutorial, you will learn how to create a custom dashboard within Umbraco V9. When planning a CMS project, I think it's really important to make the solution as user-friendly for content editors as possible. One way of doing this is by including extra screens and extra capabilities that allow them to do additional things.

Luckily, when it comes to Umbraco development, it is very easy to create a dashboard and in this tutorial, you will learn exactly how to do that. If this sounds good to you, read on 🔥🔥🔥

Creating A Dashboard

To create a dashboard you will need to create a new class and implement from the IDashboard interface. With dashboards, you do not need to register with components and composers. All you need to do is build your project and it will appear like magic🪄. IDashboard comes with five properties you will need to implement:

  • Sections: This property defines wherein the backend you want the dashboard to appear. The easy way to learn about the options available to you is to use a useful helper class that ships with Umbraco. This helper is the Constants class found in Umbraco.Cms.Core. Constants exposes a property called Applications. From here you will get the options available to you. I will use the Content section in this example. You are also free to include more than one area!

  • AccessRules: You can get access to the different access rights from within Constants.Security (also found in Umbraco.Cms.Core). In this example I want the dashboard to be viewable to all content editors, so I use Constants.Security.EditorGroupAlias

  • Alias: Like all things Umbraco, your dashboard will need a unique alias

  • View: The request Url that Umbraco will use to access the screen

Building Controller, Model, View

We have now built a dashboard that will call a URL. You will need to build a screen that renders something. To do this we can use C# to create a controller and a view. The important thing is to ensure your controller has the correct permissions. You don't want any old Tom, Dick or Harry accessing your secure dashboard. The official way to lock a controller down in Umbraco is to use the UmbracoAuthorizedController. I had trouble getting this working. When I tried to return a View type from this controller I encountered this error:

Instead, I created my own controller and defined the permissions manually. This is easy enough. If you look at the source code (here), you will see the UmbracoAuthorizedController is just a normal controller with two attributes. We can clone its functionality like this:

Within this controller, you can use normal MVC and add your custom code.

View: When you render your view, you will want it to look like a Umbraco backend page. This is why you should create a new master layout and add the Umbraco CSS and JS calls that an out-of-the-box backend Umbraco page makes. The HTML to do this is shown below:

I added my layout in a file called AdminLayout.cshtml, which I reference from my view like this:

Routing Rules

The important thing when setting all this up is our good friend routing. Routing is usually different in a vanilla .NET project compared to a CMS project. To get the routing to work in a secure Umbraco request, there are two important things you need to ensure when setting this up:

  • The Url to access the screen needs to start with umbraco/backoffice/plugins/

  • You need to create a rule within the routing table otherwise you will get a 404 error

You can add rules directly within start.cs although I do not recommend this. To ensure a clean codebase, I recommend you add your rules within an extension class and then reference the extension within start.cs. The code to create this extension is shown below:

Within Start.cs you access the extension ike this:

I won't cover how to create a rule within .NET. Just remember it needs to start with umbraco/backoffice/plugins/!

Creating Resource Files

When you try and view your dashboard within the backend, your dashboard name will look very funky. The alias name will be rendered wrapped in [] instead of some nice, friendly text. The reason this happens is that you need to create a mapping within a resource file. You need to map your dashboard alias to a resource value. You can do this by creating a resource file.

Within App_Plugins, create a new folder. This folder can be called anything you like. I called mine SpellCheckTutorials. In here create a folder called lang. Under here you will need to create a new xml file. Within lang create a new file in this format, en-US.xml. Change the language code to meet your website. The default language is en-US so you can use that if you go the default route. In this file, you need to add this config:

In the file, you need to map your dashboard alias to a value that you want to appear within the backend. In this example, the text Unpublished Tutorials will be rendered whenever a call to an alias called UnpublishedTutorials is made. Job done 💥

You are now a Umbraco dashboard master! You are now fully capable of building really cool things within the Umbraco backend. Building a dashboard is pretty simple and easy. Go forth and build cool shit. Happy Coding 🤘