Creating a Custom Dashboard

A guide to creating a custom dashboard in Umbraco
This page is a work in progress. It will be updated as the software evolves.
Overview
This guide takes you through the steps to set up a Custom Dashboard in Umbraco.
The guide is divided into four parts. The first part will go through the following:
1.​Setting up a package​
2.​Creating the dashboard web component​
What is a Dashboard?
A Dashboard is a tab on the right-hand side of a section eg. the Getting Started dashboard in the Content section:
Welcome dashboard
Why provide a Custom Dashboard for your editors?
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.
Here's an overview of the steps that will be covered:
Setting up the dashboard plugin
Writing a basic Welcome Message view
Configure the Custom Welcome Dashboard to be displayed
Adding translations
Adding styles
Adding interactive functionality with Lit and Typescript
Display the current user's name in our welcome message
Display the most recent log viewer items
You can do anything...
Prerequisites
This tutorial uses Typescript and Lit with Umbraco, so it does not cover Typescript or Lit. It is expected that your package is already set up to use Typescript and Lit. To read about setting up an extension in Umbraco using Typescript and Lit, please read the article Creating your first extension.
For resources on Typescript or Lit, you can find some here:
​Typescript Docs​
​Lit Docs​
There are a lot of parallels with Creating a Property Editor. The tutorial 'Creating a Property Editor Tutorial' is worth a read too.
The end result
At the end of this guide, we should have a friendly welcoming dashboard displaying a list of the most recent site logs.
1. Setting up a package
Assuming you have read the tutorial Creating your first extension, you should have a folder named App_Plugins in your project. Let's call our project WelcomeDashboard. Start by creating a folder in App_Plugins called WelcomeDashboard.
Create the manifest file umbraco-package.json at the root of the folder WelcomeDashboard. Here we define and configure our dashboard.
Add the following code:
umbraco-package.json
1
{
2
	"$schema": "../../umbraco-package-schema.json",
3
	"name": "My.WelcomePackage",
4
	"version": "0.1.0",
5
	"extensions": [
6
		{
7
			"type": "dashboard",
8
			"alias": "my.welcome.dashboard",
9
			"name": "My Welcome Dashboard",
10
			"js": "/App_Plugins/WelcomeDashboard/dashboard.js",
11
			"elementName": "my-welcome-dashboard",
12
			"weight": -1,
13
			"meta": {
14
				"label": "Welcome Dashboard",
15
				"pathname": "welcome-dashboard"
16
			},
17
			"conditions": [
18
				{
19
					"alias": "Umb.Condition.SectionAlias",
20
					"match": "Umb.Section.Content"
21
				}
22
			]
23
		}
24
	]
25
}
Notice that the file for our dashboard extension is in the root of our WelcomeDashboard folder and is called dashboard.jswith the element name my-welcome-dashboard.
For more information about the umbraco-package.json file, read the article Package Manifest. You should also read the Dashboards article for more information about dashboard configurations.
Please be aware that the fileumbraco-package.json is loaded into memory when Umbraco starts up. If you are changing or adding new configurations you will need to start and stop your application for it to be loaded.
2. Creating the Dashboard Web Component
Next, let's create a new ts file called welcome-dashboard.element.ts. This file is our web component and will contain all our HTML, CSS, and logic.
Let's start with setting the web component with some HTML and CSS:
welcome-dashboard.element.ts
1
import { LitElement, css, html } from "lit";
2
import { customElement } from "@umbraco-cms/backoffice/external/lit";
3
import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
4
​
5
@customElement("my-welcome-dashboard")
6
export class MyWelcomeDashboardElement extends UmbElementMixin(LitElement) {
7
​
8
  render() {
9
    return html`
10
      <h1>Welcome Dashboard</h1>
11
      <div>
12
        <p>
13
          This is the Backoffice. From here, you can modify the content,
14
          media, and settings of your website.
15
        </p>
16
        <p>© Sample Company 20XX</p>
17
      </div>
18
    `;
19
  }
20
​
21
  static styles = [
22
    css`
23
      :host {
24
        display: block;
25
        padding: 24px;
26
      }
27
    `,
28
  ];
29
}
30
​
31
declare global {
32
  interface HTMLElementTagNameMap {
33
    "my-welcome-dashboard": MyWelcomeDashboardElement;
34
  }
35
}
Build the ts file and make sure to copy the output file to dashboard.js under /App_Plugins/WelcomeDashboard/.
You can now start up the Backoffice and see our new dashboard in the content section:
First look of the dashboard
Going Further
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.
Tutorials - Previous
Creating your first extension
Adding localization to the dashboard
Last modified 1mo ago