A guide that shows you how you can create a custom dashboard in Umbraco CMS.
A Dashboard is a tab on the right-hand side of a section eg. the Getting Started dashboard in the Content section:
It is generally considered good practice to provide a custom dashboard to welcome your editors to the backoffice of your site. You can provide information about the site and/or provide a helpful gateway to common functionality the editors will use. This guide will show the basics of creating a custom 'Welcome Message' dashboard. The guide will also show how you can go a little further to provide interaction using AngularJS.
The finished dashboard will give the editors an overview of which pages and media files they've worked on most recently.
This tutorial uses AngularJS with Umbraco, so it does not cover AngularJS itself, there are tons of resources on that already here:
There are a lot of parallels with Creating a Property Editor. The tutorial Creating a Property Editor Tutorial is worth a read too.
At the end of this guide, we should have a friendly welcoming dashboard displaying a list of the editor's recent site updates.
Create a new folder inside our site's /App_Plugins folder. call it CustomWelcomeDashboard
Create an HTML file inside this folder called WelcomeDashboard.html. The HTML file will contain a fragment of an HTML document and does not need <html><head><body> entities.
Add the following HTML to the WelcomeDashboard.html:
Similar to a property editor you will now register the dashboard in a package.manifest file.
4. Add a new file inside the ~/App_Plugins/CustomWelcomeDashboard folder called package.manifest:
The above configuration is effectively saying:
Add a tab called 'WelcomeDashboard' to the 'Content' section of the Umbraco site, use the WelcomeDashboard.html as the content (view) of the dashboard and don't allow 'translators', but do allow 'admins' to see it.
The order in which the tab will appear in the Umbraco Backoffice depends on its weight. To make our Custom Welcome message the first Tab the editors see, make sure the weight is less than the default dashboards. Read more about the default weights.
You can specify multiple controls to appear on a particular tab and multiple tabs in a particular section.
After registering your dashboard, it will appear in the backoffice - however, it will have its dashboard alias [WelcomeDashboard] wrapped in square brackets. This is because it is missing a language key. The language key allows people to provide a translation of the dashboard name in multilingual environments. To remove the square brackets - add a language key:
Create a Lang folder in your custom dashboard folder
Create a package-specific language file: ~/App_Plugins/CustomWelcomeDashboard/Lang/en-US.xml
The App_Plugins version of the Lang directory is case-sensitive on Linux systems, so make sure that it starts with a capital L.
Read more about language files
This is how our dashboard looks so far:
We can apply the same workflow to elements inside the dashboard, not only the name/alias.
3. Extend the translation file xml with the following code:
We are adding another area tag with a few keys. we then need to add some HTML to the WelcomeDashboard.
Adjust the dashboard HTML with the following code:
The localize tag will be replaced with the translated keywords. We have some default text inside the tags above, which can be removed. It would usually not be visible after the translation is applied.
As for the localize tag syntax in HTML, the area alias is combined with the key alias - so if you want to translate:
The XML for that specific key will look like this:
The area and key aliases are combined and an underscore is added in between.
If you don't see the brackets disappearing - you may need to restart the website.
With the above steps completed, our dashboard is all set up to be translated across different backoffice languages.
To test it out, you can add another language XML file, like da.xml for the Danish language.
The backoffice language can be changed in the Users section if you wish to test out the translations.
Dashboards can be styled with CSS, however, there are a couple more steps to do to be able to apply a custom stylesheet.
Inside the package.manifest we add a bit of JSON to describe the dashboard's required JavaScript and stylesheet resources:
Add the following JSON to the package.manifest file:
Create a stylesheet in our CustomWelcomeDashboard folder called customwelcomedashboard.css, and add some style:
The stylesheet will be loaded and applied to our dashboard. Add images and HTML markup as required.
One caveat is that the package.manifest file is loaded into memory when Umbraco starts up. If you are adding a new stylesheet or JavaScript file you will need to start and stop your application for it to be loaded.
For version 9 and above
If the title doesn't change color, Smidge may be caching the CSS and JavaScript. To clear the cache and get it to load in the new JavaScript and CSS, you can configure the Runtime minification settings in the appsettings.json file. When you reload the page, you'll see the colorful title.
For information on creating bundles of your site's CSS or JavaScript files in your code, see the Bundling & Minification for JavaScript and CSS section.
Hopefully, now you can see the potential of what you can provide to an editor as a basic welcome dashboard.
We can add functionality to the dashboard by associating an AngularJS controller with the HTML view.
Add a new file to the CustomWelcomeDashboard folder called customwelcomedashboard.controller.js where our controller code will live.
Register the AngularJS controller to the Umbraco Angular module:
Update the outer div to wire up the controller to the view In the HTML view:
The use of vm (short for view model) is to enable communication between the view and the controller.
Update the package.manifest file to load the additional controller JavaScript file when the dashboard is displayed: