From f7aa2ed7e9e4f63fb30caa1b9cda4d9a88813be0 Mon Sep 17 00:00:00 2001
From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com>
Date: Mon, 17 Jun 2024 11:28:26 +0200
Subject: [PATCH 1/9] docs: updated the dashboards article to reflect v14
---
14/umbraco-cms/extending/dashboards.md | 129 ++++++++++++++++++++-----
1 file changed, 107 insertions(+), 22 deletions(-)
diff --git a/14/umbraco-cms/extending/dashboards.md b/14/umbraco-cms/extending/dashboards.md
index 65d52c9b6f2..5c1a7098d8a 100644
--- a/14/umbraco-cms/extending/dashboards.md
+++ b/14/umbraco-cms/extending/dashboards.md
@@ -5,15 +5,36 @@ description: >-
# Dashboard
-{% hint style="warning" %}
-This article is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.
-{% endhint %}
+Each section of the Umbraco backoffice has its own set of default dashboards. Your own custom sections can show dashboards, and you can create your own custom dashboards for existing sections.
+
+The dashboard area of Umbraco is used to display an "editor" for the selected item in the tree. If no item is selected, then the default set of section dashboards are displayed in the dashboard area.
+
+Notice that [Section Views](./section-trees/sections/section-view.md) is another similar approach to append information to the root of a Section. Section views are thought mainly to be used as Secondary pages. These two approaches should ideally not be combined.
+
+## Default Dashboards in Umbraco
-Each section of the Umbraco backoffice has its own set of default dashboards.
+The default dashboards in Umbraco are the ones that are displayed when you first enter a section in the backoffice. These dashboards are used to display information and functionality that is relevant to the section you are in.
-The dashboard area of Umbraco is used to display an 'editor' for the selected item in the tree. If no item is selected, for example when the section is first loaded in the browser, then the default set of section dashboards are displayed in the dashboard area, arranged over multiple tabs.
+The default sections in Umbraco are:
-The dashboard area of Umbraco is used to display information for a Section. Notice that Section Views is another similar approach to append information to the root of a Section. Section views are thought mainly used as Secondary pages. These two approaches should ideally not be combined.
+| Alias | Name |
+| --- | --- |
+| Umb.Section.Content | Content |
+| Umb.Section.Media | Media |
+| Umb.Section.Settings | Settings |
+| Umb.Section.Members | Members |
+| Umb.Section.Users | Users |
+| Umb.Section.Translation | Dictionary |
+
+Here is a table of the default dashboards in Umbraco and the sections they are used including their aliases:
+
+| Alias | Section | Weight | Description |
+| --- | --- | --- | --- |
+| Umb.Dashboard.UmbracoNews | Umb.Section.Content | 20 | The first dashboard the user sees and contains the latest news of Umbraco including outbound links to resources |
+| Umb.Dashboard.RedirectManagement | Umb.Section.Content | 10 | Contains a list of active URL redirects |
+| Umb.Dashboard.SettingsWelcome | Umb.Section.Settings | 500 | Contains a set of boxes with links to appropriate resources |
+
+Even though these dashboards are useful, you might want to create your own custom dashboard to display specific information or functionality.
You can try and [create a custom dashboard](../../tutorials/creating-a-custom-dashboard/) as a way on getting started on this topic.
@@ -23,26 +44,90 @@ This section dives into the Dashboard Extension Manifest, shows how to register
### Example Extension Manifest
-Insert this as an entry of extensions in your `Umbraco-package.json` or register it via JavaScript.
+{% hint style="info" %}
+You can read more about manifests in the tutorial [Creating Your First Extension](../tutorials/creating-your-first-extension.md).
+{% endhint %}
-```jsx
+Insert this as an entry in the `extensions` list in a `umbraco-package.json` file.
+{% code title="~/App_Plugins/WelcomeDashboard/umbraco-package.json" lineNumbers="true" %}
+
+```json
{
- "type": "dashboard",
- "alias": "my.welcome.dashboard",
- "name": "My Welcome Dashboard",
- "element": "/App_Plugins/WelcomeDashboard/dashboard.js",
- "elementName": "my-welcome-dashboard",
- "weight": -1,
- "meta": {
- "label": "Welcome Dashboard",
- "pathname": "welcome-dashboard"
- },
- "conditions": [
+ "type": "dashboard",
+ "alias": "my.welcome.dashboard",
+ "name": "My Welcome Dashboard",
+ "element": "/App_Plugins/WelcomeDashboard/dashboard.js",
+ "weight": -1,
+ "meta": {
+ "label": "Welcome Dashboard",
+ "pathname": "welcome-dashboard"
+ }
+}
+```
+
+{% endcode %}
+
+This will register a dashboard with the alias `my.welcome.dashboard` and the name `My Welcome Dashboard`. The dashboard will be loaded from the file `/App_Plugins/WelcomeDashboard/dashboard.js`. The dashboard will be displayed with the label `Welcome Dashboard` and the URL `/welcome-dashboard` on *all sections*, e.g. `/section/content/welcome-dashboard`.
+
+### Conditions
+
+You can specify conditions for when the dashboard should be displayed. This is done by adding a `conditions` property to the manifest. Ideally we would like the dashboard to be shown only on a specific section. This can be done by specifying the condition called `Umb.Condition.SectionAlias` and providing the [alias of the section](#default-dashboards-in-umbraco) you want the dashboard to be displayed on:
+
+```json
+"conditions": [
{
- "alias": "Umb.Condition.SectionAlias",
- "match": "Umb.Section.Content"
+ "alias": "Umb.Condition.SectionAlias",
+ "match": "Umb.Section.Content"
}
- ]
+]
+```
+
+This will make the dashboard only be displayed on the Content section.
+
+{% hint style="info" %}
+You can read more about [Extension Conditions](./backoffice-setup/extension-registry/extension-conditions.md) in the documentation.
+{% endhint %}
+
+### Properties
+
+The dashboard manifest can contain the following properties:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| type | string | The type of extension, should be `dashboard` |
+| alias | string | A unique alias for the dashboard extension |
+| name | string | The name of the dashboard extension |
+| element | string | The path to the JavaScript file that exports the dashboard |
+| elementName | string | (Optional) The name of the Web Component that contains the dashboard (only if not a default export) |
+| weight | number | (Optional) The weight of the dashboard, lower numbers are displayed first |
+| meta | object | Additional metadata for the dashboard