A guide to creating a custom dashboard in Umbraco
This guide takes you through the steps to set up a Custom Dashboard in Umbraco.
The steps we will go through in part one are:
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 Lit and TypeScript.
The finished dashboard will give the editors an overview of which pages and media files they've worked on most recently.
This tutorial uses TypeScript and Lit with Umbraco, It is expected that your package is already set up to use TypeScript and Lit.
To see how to set up an extension in Umbraco using TypeScript and Lit, read the article Creating your first extension.
This tutorial will not go in-depth on how TypeScript and Lit work. To learn about TypeScript and Lit, you can find their documentation below:
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 will have a friendly welcoming dashboard displaying a list of the most recent site logs.
At each step, you will find a dropdown for welcome-dashboard.element.ts, and umbraco-package.jsonto confirm your placement for code snippets.
Follow the Vite Package Setup by creating a new project folder called "welcome-dashboard" in App_Plugins.
Create a manifest file named umbraco-package.json at the root of the welcome-dashboard folder. Here we define and configure our dashboard.
Add the following code to umbraco-package.json:
For more information about the umbraco-package.json file, read the article Package Manifest. For more information about the dashboard configurations read the Dashboards article.
The umbraco-package.json files are cached by the server. If you are running your site in development mode, the cache is short-lived (~10 seconds). If changes to umbraco-package.json files are not reflected immediately, try reloading the backoffice a few seconds later.
When running the site in production mode, the cache is long-lived. You can read more about runtime modes in the Runtime Modes article.
Now let's create the web component we need for our property editor. This web component contains all our HTML, CSS, and logic.
Create a file in the src folder with the name welcome-dashboard.element.ts
In this new file, add the following code:
In the vite.config.ts file replace the entry to our newly created .ts file:
In the welcome-dashboard folder run npm run build and then run the project. Then in the content section of the Backoffice you will see our new dashboard:
With all the steps completed, you should have a dashboard welcoming your users to the Backoffice.
In the next part, we will look into how to add localization to the dashboard using our own custom translations.
Now that we have data for our dashboard we might want to make it look prettier. To do this we can use the Umbraco UI library.
This is the fourth and final part of the guide to building a Custom Dashboard. This part continues work on the dashboard we built in part three: Adding functionality to the Dashboard. But it goes further to showcase how we can use the UI Library in our extension.
The steps we will go through in this part are:
The Umbraco UI Library is a set of web components and variables that we can use to build Umbraco User Interfaces. It is already part of the Backoffice, which means you can already start to use it.
By using the variables available from the UI Library, you ensure that your extensions are a consistent size with the rest of the backoffice.
Let's start by wrapping uui-box around our render output. This makes our dashboard the same style as the built-in dashboards of Umbraco:
The uui-box has a headline property as well. Here are two options:
Move the headline into the headline property:
Add an element instead. This element can also be styled and contain other elements.
Let's keep using umb-localize instead of localize.term():
The UI Library also has a lot of variables we can use such as sizes and colors. Let's update our padding to ensure that our element is always consistent with the rest of the backoffice:
This already looks a lot better!
Let's try another uui element. Since we have a lot of information from the users, it could be a good idea to insert it into a proper table.
The Umbraco UI (UUI) Library also includes a uui-table, so let's use it:
Since the uui-table and others are handling the table, we can redo our CSS a bit:
Your dashboard component should now look like this:
Insert the user.state into a uui-tag that uses different values of the propertieslook and color.
The values depend on the state of the user. For example, use look="primary" and color="positive" when the user is Active
Check out the uui-tag in the library here
The uui-table-row also have a selectable property.
Continue to experiment with different UUI elements from the UI library to build awesome interfaces!
Over the four previous steps, we have:
Set up the dashboard plugin
Wrote a basic Welcome Message view
Configured the Custom Welcome Dashboard to be displayed
Added translations
Added styles
Added interactive functionality with Lit and TypeScript
Displayed the current user's name in our welcome message
Displayed the most recent log viewer items
You can do anything with Umbraco UI Library
Use resources and get data for your dashboard.
This is the third part of our guide to building a custom dashboard. This part continues work on the dashboard we built in part two: Add localization to the dashboard. But it goes further to show how to add functionality and data to our dashboard.
The steps we will go through in this part are:
Umbraco has a large selection of contexts that you can use in your custom Property Editors and Dashboards. For this example, we will welcome the editor by name. To achieve this we can make use of the Umbraco Contexts.
To get information on the current user that's currently logged in, we first need to get the context and its token. We use the Current User Context to receive the user that is currently logged in.
Import the UMB_CURRENT_USER_CONTEXT and the type UmbCurrentUserModel for the logged-in user. We also need to update the import from lit decorators to get state in the welcome-dashboard.element.ts file:
Now that we have access to the Current User Context, we can consume it in the constructor to obtain the current user. We do this using the consumeContext method, which is available on our element because we extended using UmbElementMixin.
As the first thing in the export class MyWelcomeDashboardElement add the following to the element implementation :
The entire welcome-dashboard.element.ts file is available for reference at the end of the step to confirm your placement for code snippets.
Now that we have the current user, we can access a few different things. Let's get the name of the current user, so that we can welcome the user:
Your dashboard should now look something like this:
Let's dive deeper into some new resources and see what we can do with them.
Before we can get data from the server we need to start up the repository that handles said data.
Let's say we want to get the data of all of the users of our project.
To get the user data, we need to start up the user repository.
We are also going to need a type for our user details.
Import UmbUserDetailModel and UmbUserCollectionRepository:
Start up the repository and then create a new async method that we call from the constructor. We are also going to create a new state for our array that is going to contain our user details:
Notice that the user repository has a lot of methods that we can use. We are going to use requestCollection to get all the users.
The method requestCollection returns a promise, so let's await the data and save the data in our array:
Now that we have the data from the repository, we need to render the data.
We are going to use the repeat directive to loop through the array of users and render each user. We are also going to create a new method _renderUser that will render the user details.
Add the repeat directive to the import:
Add the following to the render method and create the _renderUser method:
To make it more readable, add some CSS as well:
We recommend using variables for colors and sizing. See why and how you could achieve this in the next part where we will use the Umbraco UI Library.
We now should have our welcome dashboard filled showing a list of all users:
With all of the steps completed, you should have a functional dashboard that welcomes the user and shows a list of all users. Hopefully, this tutorial has given you some ideas on what is possible to do when creating a dashboard.
You can also go further and extend the dashboard with UI elements from the Umbraco UI Library.
Set up localization for your dashboard.
This is the second part of our guide to building a Custom Dashboard. This part continues work on the dashboard we built in part one: Creating a Custom Dashboard. It further shows how to handle localization in a custom dashboard.
The steps we will go through in second part are:
In the welcome-dashboard folder create a new folder called "Localization"
Then create two new files en.js and da-dk.js:
Add the following code to en.js
Add the following code to da-dk.js
Now let's update the umbraco-package.json file from the welcome-dashboard folder to register our new localization files:
Run npm run build in the welcome-dashboard folder and then run the project.
We can use the umb-localize element to get the localizations out, which takes a key property in.
Let's start using the localizations. In the umbraco-package.json file, we will already be using the #welcomeDashboard_label key for the dashboard label. Go ahead and replace "label": "Welcome Dashboard" with "label": "#welcomeDashboard_label".
The # is used to indicate that the value is a key and not a string.
We will now use the umb-localize element to get the translations for the dashboard. Update the welcome-dashboard.element.ts:
Run npm run build in the welcome-dashboard folder and then run the project.
The dashboard's text will appear depending on the user's language.
If the user's language is Danish, the dashboard will use the text from our da-dk file.
If the user's language is English, the dashboard will use the text from our en file.
If the key is not found in the current language, the fallback language (en) will be used.
The text between the open and close tags of umb-localize is the fallback value. This is used in case the key can't be found at all.
This is how our dashboard should now look like:
Tip: If you do not have many translations, you can also choose to include the localizations directly in the meta-object. Read more about translations in the Localization article.
With the part completed, you should have a dashboard welcoming your users' language.
In the next part, we will look into how to add more functionality to the dashboard using some of the Contexts that Umbraco offers.
