# Creating a Custom Dashboard

## Overview

This guide outlines the steps to set up a custom dashboard in Umbraco. Part one covers:

1. [Setting up a Package](#setting-up-a-package)
2. [Creating the Dashboard Web Component](#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](https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-64641334b3e4bb9c788b5f23eb6c41a36eb23291%2Fwelcome-dashboard.png?alt=media)

#### 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.

This tutorial uses TypeScript and Lit with Umbraco, It is expected that your package is already [set up to use TypeScript and Lit](https://docs.umbraco.com/umbraco-cms/customizing/development-flow/vite-package-setup).

To see how to set up an extension in Umbraco using TypeScript and Lit, read the article [Creating your first extension](https://docs.umbraco.com/umbraco-cms/tutorials/creating-your-first-extension).

### Resources

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:

* [TypeScript documentation](https://www.typescriptlang.org/docs/)
* [Lit documentation](https://lit.dev/docs/)

There are a lot of parallels with Creating a Property Editor. The tutorial '[Creating a Property Editor Tutorial](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor)' is worth a read too.

### The end result

At the end of this guide, the tutorial results in a friendly welcoming dashboard displaying a list of the most recent site logs.

{% hint style="info" %}
At each step, you will find a dropdown for `welcome-dashboard.element.ts`, `and umbraco-package.json`to confirm your placement for code snippets.
{% endhint %}

## Setting up a package

1. Follow the [Vite Package Setup](https://docs.umbraco.com/umbraco-cms/customizing/development-flow/vite-package-setup) by creating a new project folder called "`welcome-dashboard`" in `App_Plugins`.
2. Create a manifest file to define and configure your dashboard using either JSON or TypeScript.

{% tabs %}
{% tab title="JSON Manifest" %}
Create a manifest file named `umbraco-package.json` within the `public` folder, located at the root of the `welcome-dashboard` folder, and add the following code:

{% code title="umbraco-package.json" lineNumbers="true" %}

```json
{
  "$schema": "../../umbraco-package-schema.json",
  "name": "My.WelcomePackage",
  "version": "0.1.0",
  "extensions": [
    {
      "type": "dashboard",
      "alias": "my.welcome.dashboard",
      "name": "My Welcome Dashboard",
      "element": "/App_Plugins/welcome-dashboard/welcome-dashboard.js",
      "elementName": "my-welcome-dashboard",
      "weight": 30,
      "meta": {
        "label": "Welcome Dashboard",
        "pathname": "welcome-dashboard"
      },
      "conditions": [
        {
          "alias": "Umb.Condition.SectionAlias",
          "match": "Umb.Section.Content"
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript Manifest" %}
Extension authors define the dashboard manifest, then register it dynamically during runtime using a [Backoffice Entry Point](https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types/backoffice-entry-point) extension.

Create a manifest file named `manifests.ts` and add the following code:

{% code title="manifests.ts" %}

```typescript
import type { ManifestDashboard } from '@umbraco-cms/backoffice/dashboard';

export const manifests: Array<ManifestDashboard> = [
    {
      type: "dashboard",
      alias: "my.welcome.dashboard",
      name: "My Welcome Dashboard",
      element: "/App_Plugins/welcome-dashboard/welcome-dashboard.js",
      elementName: "my-welcome-dashboard",
      weight: 30,
      meta: {
        label: "Welcome Dashboard",
        pathname: "welcome-dashboard"
      },
      conditions: [
        {
          alias: "Umb.Condition.SectionAlias",
          match: "Umb.Section.Content"
        }
      ]
    }
];
```

{% endcode %}
{% endtab %}
{% endtabs %}

For more information about the `umbraco-package.json` file, read the article [Extension Manifest](https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest). For more information about the dashboard configurations read the [Dashboards](https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types/dashboard) article.

{% hint style="info" %}
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](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes).
{% endhint %}

## Creating the Dashboard Web Component

Create the web component for the property editor. This web component contains all HTML, CSS, and logic.

1. Create a file in the `src` folder with the name `welcome-dashboard.element.ts`
2. In this new file, add the following code:

{% code title="welcome-dashboard.element.ts" overflow="wrap" lineNumbers="true" %}

```typescript
import { css, html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-welcome-dashboard')
export class MyWelcomeDashboardElement extends UmbLitElement {

  override render() {
    return html`
      <h1>Welcome Dashboard</h1>
      <div>
        <p>
          This is the Backoffice. From here, you can modify the content,
          media, and settings of your website.
        </p>
        <p>© Sample Company 20XX</p>
      </div>
    `;
  }

  static override readonly styles = [
    css`
      :host {
        display: block;
        padding: 24px;
      }
    `,
  ];
}

export default MyWelcomeDashboardElement;

declare global {
  interface HTMLElementTagNameMap {
    'my-welcome-dashboard': MyWelcomeDashboardElement;
  }
}
```

{% endcode %}

3. In the `vite.config.ts` file update the `entry` to point to the newly created `.ts` file, and also ensure that the `outDir` and `base` attributes are pointing to the `welcome-dashboard` folder:

```typescript
import { defineConfig } from "vite";

export default defineConfig({
    build: {
        lib: {
            entry: "src/welcome-dashboard.element.ts", // your web component source file
            formats: ["es"],
        },
        outDir: "../App_Plugins/welcome-dashboard", // all compiled files will be placed here
        emptyOutDir: true,
        sourcemap: true,
        rollupOptions: {
            external: [/^@umbraco/], // ignore the Umbraco Backoffice package in the build
        },
    },
    base: "/App_Plugins/welcome-dashboard/", // the base path of the app in the browser (used for assets)
});
```

4. 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 the new dashboard:

<figure><img src="https://2050077833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb0WSXUuM7Qx5BfREagAI%2Fuploads%2Fgit-blob-8e14d6fe0e643fcb6406babd2bf0463d345d6a2b%2Fspaces_G1Byxw7XfiZAj8zDMCTD_uploads_PtBQkEyVcGmoVx3ysAOJ_welcome.webp?alt=media" alt=""><figcaption><p>First look of the dashboard</p></figcaption></figure>

## Going Further

With all the steps completed, you should have a dashboard welcoming your users to the Backoffice.

In the next part, the tutorial covers how to add localization to the dashboard using custom translations.