Links

Adding functionality to the Dashboard

In this subpage we will cover how to use resources and get data for your dashboard.
This page is a work in progress. It will be updated as the software evolves.

Overview

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:

Step 1: Contexts

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 Auth context to receive the user that is currently logged in.
Import the Auth token and the type for the logged-in user. We also need to update the import from lit decorators to get state.
welcome-dashboard.element.ts
1
import { customElement, state } from "@umbraco-cms/backoffice/external/lit";
2
import { UMB_AUTH, UmbLoggedInUser } from '@umbraco-cms/backoffice/auth';
Now that we have the Auth token, 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.
welcome-dashboard.element.ts
...
@state()
private _currentUser?: UmbLoggedInUser;
private _auth?: typeof UMB_AUTH.TYPE;
constructor() {
super();
this.consumeContext(UMB_AUTH, (instance) => {
this._auth = instance;
this._observeCurrentUser();
});
}
private async _observeCurrentUser() {
if (!this._auth) return;
this.observe(this._auth.currentUser, (currentUser) => {
this._currentUser = currentUser;
});
}
...
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:
welcome-dashboard.element.ts
render() {
return html`
<h1>
<umb-localize key="welcomeDashboard_heading">Welcome</umb-localize>
${this._currentUser?.name ?? "Unknown"}!
</h1>
<div>
<p>
<umb-localize key="welcomeDashboard_bodytext">
This is the Backoffice. From here, you can modify the content,
media, and settings of your website.
</umb-localize>
</p>
<p>
<umb-localize key="welcomeDashboard_copyright">
© Sample Company 20XX
</umb-localize>
</p>
</div>
`;
}
Your dashboard should now look something like this:
Welcoming the user "Umbraco User"
See the entire file: welcome-dashboard.element.ts
welcome-dashboard.element.ts
1
import { UMB_AUTH, UmbLoggedInUser } from '@umbraco-cms/backoffice/auth';
2
import { LitElement, css, html, customElement, state } 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
@state()
8
private _currentUser?: UmbLoggedInUser;
9
10
private _auth?: typeof UMB_AUTH.TYPE;
11
12
constructor() {
13
super();
14
this.consumeContext(UMB_AUTH, (instance) => {
15
this._auth = instance;
16
this._observeCurrentUser();
17
});
18
}
19
20
private async _observeCurrentUser() {
21
if (!this._auth) return;
22
this.observe(this._auth.currentUser, (currentUser) => {
23
this._currentUser = currentUser;
24
});
25
}
26
27
render() {
28
return html`
29
<h1>
30
<umb-localize key="welcomeDashboard_heading">Welcome</umb-localize>
31
${this._currentUser?.name ?? "Unknown"}!
32
</h1>
33
<div>
34
<p>
35
<umb-localize key="welcomeDashboard_bodytext">
36
This is the Backoffice. From here, you can modify the content,
37
media, and settings of your website.
38
</umb-localize>
39
</p>
40
<p>
41
<umb-localize key="welcomeDashboard_copyright">
42
© Sample Company 20XX
43
</umb-localize>
44
</p>
45
</div>
46
`;
47
}
48
49
static styles = [
50
css`
51
:host {
52
display: block;
53
padding: 24px;
54
}
55
`,
56
];
57
}
58
59
export default MyWelcomeDashboardElement;
60
61
declare global {
62
interface HTMLElementTagNameMap {
63
'my-welcome-dashboard': MyWelcomeDashboardElement;
64
}
65
}

Step 2: Getting data from the server

UmbUserDetail and UmbUserRepository is not available yet.
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.
Let's import UmbUserDetail and UmbUserRepository:
welcome-dashboard.element.ts
import { UmbUserDetail, UmbUserRepository } from '@umbraco-cms/backoffice/users';
Next, we 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.
welcome-dashboard.element.ts
@state()
private _userData?: Array<UmbUserDetail>;
private _userRepository = new UmbUserRepository(this);
constructor() {
...
this._getDataFromRepository();
}
private async _getDataFromRepository() {
//this._userRepository
}
Notice that the user repository has a lot of methods that we can use. We are going to use requestCollectionto get all the users.
Options from the user repository
The method requestCollection returns a promise, so let's await the data and save the data in our array.
private async _getDataFromRepository() {
const { data } = await this._userRepository.requestCollection();
this._userData = data?.items;
}
See the entire file: welcome-dashboard.element.ts
welcome-dashboard.element.ts
1
import { UMB_AUTH, UmbLoggedInUser } from '@umbraco-cms/backoffice/auth';
2
import { LitElement, css, html, customElement, state } from "@umbraco-cms/backoffice/external/lit";
3
import { UmbUserDetail, UmbUserRepository } from '@umbraco-cms/backoffice/users';
4
import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
5
6
@customElement('my-welcome-dashboard')
7
export class MyWelcomeDashboardElement extends UmbElementMixin(LitElement) {
8
@state()
9
private _currentUser?: UmbLoggedInUser;
10
11
@state()
12
private _userData?: Array<UmbUserDetail>;
13
14
private _auth?: typeof UMB_AUTH.TYPE;
15
16
private _userRepository = new UmbUserRepository(this);
17
18
constructor() {
19
super();
20
this.consumeContext(UMB_AUTH, (instance) => {
21
this._auth = instance;
22
this._observeCurrentUser();
23
});
24
this._getDataFromRepository();
25
}
26
27
//Get the current user
28
private async _observeCurrentUser() {
29
if (!this._auth) return;
30
this.observe(this._auth.currentUser, (currentUser) => {
31
this._currentUser = currentUser;
32
});
33
}
34
35
//Get all users
36
private async _getDataFromRepository() {
37
const { data } = await this._userRepository.requestCollection();
38
this._userData = data?.items;
39
}
40
41
render() {
42
return html`
43
<h1>
44
<umb-localize key="welcomeDashboard_heading">Welcome</umb-localize>
45
${this._currentUser?.name ?? 'Unknown'}!
46
</h1>
47
<div>
48
<p>
49
<umb-localize key="welcomeDashboard_bodytext">
50
This is the Backoffice. From here, you can modify the content, media, and settings of your website.
51
</umb-localize>
52
</p>
53
<p>
54
<umb-localize key="welcomeDashboard_copyright"> © Sample Company 20XX </umb-localize>
55
</p>
56
</div>
57
`;
58
}
59
60
static styles = [
61
css`
62
:host {
63
display: block;
64
padding: 24px;
65
}
66
`,
67
];
68
}
69
70
export default MyWelcomeDashboardElement;
71
72
declare global {
73
interface HTMLElementTagNameMap {
74
'my-welcome-dashboard': MyWelcomeDashboardElement;
75
}
76
}
Now that we have the data from the repository, let's render the data:
welcome-dashboard.element.ts
render() {
return html`
...
...
<div id="users-wrapper">${this._userData?.map((user) => this._renderUser(user))}</div>
`;
}
private _renderUser(user: UmbUserDetail) {
return html`<div class="user">
<div>${user.name}</div>
<div>${user.email}</div>
<div>${user.state}</div>
</div>`;
}
To make it a bit easier to read, let's add a little bit of CSS as well:
welcome-dashboard.element.ts
static styles = [
css`
:host {
display: block;
padding: 24px;
}
#users-wrapper {
border: 1px solid lightgray;
}
.user {
padding: 5px 10px;
}
.user:not(:first-child) {
border-top: 1px solid lightgray;
}
`,
];
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 something that looks like this:
Dashboard with all users. Output may vary depends on your users.
See the entire file: welcome-dashboard.element.ts
welcome-dashboard.element.ts
1
import { UMB_AUTH, UmbLoggedInUser } from "@umbraco-cms/backoffice/auth";
2
import { LitElement, css, html, customElement, state } from "@umbraco-cms/backoffice/external/lit";
3
import { UmbUserDetail, UmbUserRepository } from "@umbraco-cms/backoffice/users";
4
import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
5
6
@customElement('my-welcome-dashboard')
7
export class MyWelcomeDashboardElement extends UmbElementMixin(LitElement) {
8
@state()
9
private _currentUser?: UmbLoggedInUser;
10
11
@state()
12
private _userData?: Array<UmbUserDetail>;
13
14
private _auth?: typeof UMB_AUTH.TYPE;
15
16
private _userRepository = new UmbUserRepository(this);
17
18
constructor() {
19
super();
20
this.consumeContext(UMB_AUTH, (instance) => {
21
this._auth = instance;
22
this._observeCurrentUser();
23
});
24
this._getDataFromRepository();
25
}
26
27
//Get the current user
28
private async _observeCurrentUser() {
29
if (!this._auth) return;
30
this.observe(this._auth.currentUser, (currentUser) => {
31
this._currentUser = currentUser;
32
});
33
}
34
35
//Get all users
36
private async _getDataFromRepository() {
37
const { data } = await this._userRepository.requestCollection();
38
this._userData = data?.items;
39
}
40
41
render() {
42
return html`
43
<h1>
44
<umb-localize key="welcomeDashboard_heading">Welcome</umb-localize>
45
${this._currentUser?.name ?? 'Unknown'}!
46
</h1>
47
<div>
48
<p>
49
<umb-localize key="welcomeDashboard_bodytext">
50
This is the Backoffice. From here, you can modify the content, media, and settings of your website.
51
</umb-localize>
52
</p>
53
<p>
54
<umb-localize key="welcomeDashboard_copyright"> © Sample Company 20XX </umb-localize>
55
</p>
56
</div>
57
<div id="users-wrapper">${this._userData?.map((user) => this._renderUser(user))}</div>
58
`;
59
}
60
61
private _renderUser(user: UmbUserDetail) {
62
return html`<div class="user">
63
<div>${user.name}</div>
64
<div>${user.email}</div>
65
<div>${user.state}</div>
66
</div>`;
67
}
68
69
static styles = [
70
css`
71
:host {
72
display: block;
73
padding: 24px;
74
}
75
76
#users-wrapper {
77
border: 1px solid lightgray;
78
}
79
80
.user {
81
padding: 5px 10px;
82
}
83
84
.user:not(:first-child) {
85
border-top: 1px solid lightgray;
86
}
87
`,
88
];
89
}
90
91
export default MyWelcomeDashboardElement;
92
93
declare global {
94
interface HTMLElementTagNameMap {
95
'my-welcome-dashboard': MyWelcomeDashboardElement;
96
}
97
}

Going Further

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.