Dashboards

    Each section of the Umbraco backoffice has its own set of default dashboards.

    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 'first loads', then the default set of section dashboards are displayed in the dashboard area, arranged over multiple tabs.

    Registering your own Dashboard

    There are two approaches to registering a custom dashboard to appear in the Umbraco Backoffice:

    Registering with package.manifest

    Add a file named 'package.manifest' to the app_plugins folder, containing the following json configuration pointing to your dashboard view:

    {
        "dashboards":  [
            {
                "alias": "myCustomDashboard",
                "view":  "/App_Plugins/myCustom/dashboard.html",
                "sections":  [ "content", "settings" ],
                "weight": -10
            }
        ]
    }

    Registering with C# Type

    By creating a C# class that implements IDashboard from Umbraco.Core.Dashboards then this will automatically be discovered by Umbraco at application startup time.

    using System;
    using Umbraco.Core.Composing;
    using Umbraco.Core.Dashboards;
    
    namespace My.Website
    {
        [Weight(-10)]
        public class MyDashboard : IDashboard
        {
            public string Alias => "myCustomDashboard";
    
            public string[] Sections => new[] { "content", "settings" };
    
            public string View => "/App_Plugins/myCustom/dashboard.html";
    
            public IAccessRule[] AccessRules => Array.Empty<IAccessRule>();
        }
    }
    

    Re-ordering / weighting

    Each dashboard, regardless of how it is registered (package.manifest or C# or default core dashboard) uses a weight property to assign the order that the dashboard should be displayed. The dashboard with the lowest weighting number will be displayed first in a collection where one or more dashboards are visible for a section/application.

    For reference, here is a list of the weighting values for the default Umbraco dashboards, so you can assign a weighting to your own custom dashboard with a higher or lower value to suit your custom ordering needs.

    Content

    Name Weight Language Key C# Type
    Getting Started 10 dashboardTabs/contentIntro Umbraco.Web.Dashboards.ContentDashboard
    Redirect URL Management 20 dashboardTabs/contentRedirectManager Umbraco.Web.Dashboards.RedirectUrlDashboard

    Media

    Name Weight Language Key C# Type
    Content 10 dashboardTabs/mediaFolderBrowser Umbraco.Web.Dashboards.MediaDashboard

    Settings

    Name Weight Language Key C# Type
    Welcome 10 dashboardTabs/settingsWelcome Umbraco.Web.Dashboards.SettingsDashboard
    Examine Management 20 dashboardTabs/settingsExamine Umbraco.Web.Dashboards.ExamineDashboard
    Published Status 30 dashboardTabs/settingsPublishedStatus Umbraco.Web.Dashboards.PublishedStatusDashboard
    Models Builder 40 dashboardTabs/settingsModelsBuilder Registered in ModelsBuilder package.manifest
    Health Check 50 dashboardTabs/settingsHealthCheck Umbraco.Web.Dashboards.HealthCheckDashboard

    Members

    Name Weight Language Key C# Type
    Getting Started 10 dashboardTabs/memberIntro Umbraco.Web.Dashboards.MembersDashboard

    Forms

    Name Weight Language Key C# Type
    Install Umbraco Forms 10 dashboardTabs/formsInstall Umbraco.Web.Dashboards.FormsDashboard

    Add Language Keys

    After registering your dashboard, it will appear in the backoffice - however it will have it's dashboard alias [mycustomdashboard] wrapped in square brackets. This is because it is missing a language key. The language key allows people to provide a translation of the dashboard name in multilingual environments. To remove the square brackets - add a language key:

    If your dashboard is unique to your Umbraco installation then you can modify the following application language file: config/lang/en-US.user.xml however if the dashboard is to be released as an Umbraco package and shared with others to use in their own Umbraco installation then you will need to create a lang folder in your custom dashboard folder and create a package specific language file: App_Plugins/Mycustomdashboard/lang/en-US.xml

    Read more about language files

    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <language>
        <area alias="dashboardTabs">
            <key alias="myCustomDashboard">My Dashboard</key>
        </area>
    </language>
    

    Specifying permissions

    You can configure which applications/sections a dashboard will appear in, in the above examples (package.manifest or c#), you can see the alias of the section is used to control where the dashboard is allowed to appear. Further to this, within this section, you can control which Users can see a particular dashboard based upon the User Groups they belong to by setting the 'access' permissions based on the User Group alias, you choose to deny or grant a particular User Group's access to the dashboard.

    {
        "dashboards":  [
            {
                "alias": "myCustomDashboard2",
                "view":  "/App_Plugins/myCustom/dashboard.html",
                "sections": [ "content", "settings" ],
                "weight": -10,
                "access": [
                    { "deny": "translator" },
                    { "grant": "admin" }
                ]
            }
        ]
    }
    using Umbraco.Core.Composing;
    using Umbraco.Core.Dashboards;
    
    namespace My.Website
    {
        [Weight(-10)]
        public class MyDashboard : IDashboard
        {
            public string Alias => "myCustomDashboard";
    
            public string[] Sections => new[] { "content", "settings" };
    
            public string View => "/App_Plugins/myCustom/dashboard.html";
    
            public IAccessRule[] AccessRules
            {
                get
                {
                    var rules = new IAccessRule[]
                    {
                        new AccessRule {Type = AccessRuleType.Deny, Value = Umbraco.Core.Constants.Security.TranslatorGroupAlias},
                        new AccessRule {Type = AccessRuleType.Grant, Value = Umbraco.Core.Constants.Security.AdminGroupAlias}
                    };
                    return rules;
                }
            }
        }
    }
    

    Remove an Umbraco dashboard

    In previous versions of Umbraco if you wanted to remove or modify the order of a default dashboards you would ammend the config/dashboards.config file on disk. With V8+ the configuration file approach has been removed and you need to use code to create your own composer (a c# class that can be used to organise and customise your Umbraco application to your own needs) to remove a dashboard. For example - if you wanted to remove the 'Content Dashboard' you would create a RemoveDashboard composer like this:

    using Umbraco.Core;
    using Umbraco.Core.Composing;
    using Umbraco.Web;
    using Umbraco.Web.Dashboards;
    
    namespace My.Website
    {
        [RuntimeLevel(MinLevel = RuntimeLevel.Run)]
        public class RemoveDashboard : IUserComposer
        {
            public void Compose(Composition composition)
            {
                composition.Dashboards().Remove<ContentDashboard>();
            }
        }
    }