---
title: Adding widget dashboards to the interface
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
If the default widget dashboards in the administration interface do not meet your requirements, you can create your own dashboard applications or pages.
> **Note:** **Important**: Widget dashboards are a completely separate feature from the system's main [application dashboard](https://docs.kentico.com/k81/using-the-kentico-interface.md). Every widget dashboard is either a standalone application, or a page within another application.
The following _example_ demonstrates how to add a custom dashboard application to the **Social & Community** category. You can apply the same principles when creating widget dashboards in other locations.
## Creating the dashboard page template
First, create a [page template](https://docs.kentico.com/k81/developing-websites/managing-page-templates.md) for the dashboard:
1. Open the **Page templates** application.
2. Select the **Dashboard pages** category in the tree.
3. Click **New template** and enter the following values:
- **Template display name**: Community dashboard
- **Template code name**: CommDashboard
4. Click **Save**.
5. Select _Dashboard page_ as the **Template type**.
6. Click **Save**.
Adjust the [layout](https://docs.kentico.com/k81/developing-websites/developing-websites-using-the-portal-engine/editing-page-layouts.md) of the page template:
1. Switch to the **Layout** tab.
2. Copy the following sample code into the layout to define web part/widget zones for the template:
```html
```
3. Click **Save**.
4. Switch to the **Design** tab.
5. Expand the menu () of the **DashboardTop** zone and click **Configure**.
6. Switch the **Widget zone type** property from _None_ to _Dashboard_.
7. Click **Save & Close**.
8. Repeat the steps 5 – 7 for the **DashboardLeft** and **DashboardRight** zones.
Add [web parts](https://docs.kentico.com/k81/custom-development/developing-web-parts.md) and [widgets](https://docs.kentico.com/k81/developing-websites/preparing-widgets-for-users.md) to the zones:
1. [Add](https://docs.kentico.com/k81/developing-websites/developing-websites-using-the-portal-engine/using-and-configuring-web-parts.md) the **Widget actions** web part into the **ZoneTop** zone.
2. Configure the following properties of the _Widget actions_ web part:
- **Widget zone type**: Dashboard
- **Widget zone ID**: Leave empty _(Designates the zone where new widgets should be created when users click the_ Add widget \*button. By default, the web part uses the first available zone (\*DashboardTop _in this case), but you can specify the ID of any other dashboard zone.)_
3. Leave the remaining properties in their default state and click **OK**.
4. Add the **Static text** web part to the same zone and set the following properties:
- **Text**: This is a custom dashboard page
- **Display as**: Header level 2
5. Click **OK**.
6. Expand the menu () of the **DashboardTop** zone and click **Add new widget**.
7. For example, choose the **Community -> My messages** widget.
8. Confirm the dialogs without making changes and leave the other two dashboard zones empty.
- This sets the default content of the dashboard that individual users can later configure and expand.
## Adding the dashboard UI element
To create a new widget dashboard application, you need to add a UI element to the system:
1. Open the **Modules** application.
2. Edit () the **Custom** module. Note that the **Module code name** is _cms.customsystemmodule_ on the **General** tab.
3. Switch to the **User interface** tab.
4. Select the **CMS -> Administration -> Social & Community** element in the tree.
5. Click **New element** ().
6. Enter the following values:
- **Display name**: Community overview
- **Code name**: CommDashboardElement
- **Module**: Custom
- **Caption**: Community overview
- **Element icon type**: Class
- **Element icon CSS class**: icon-app-content-dashboard
- **Type**: URL
- **Target URL**: _\~/CMSGlobalFiles/CommDashboard.aspx?dashboardName=Comm\&templateName=CommDashboard&{hash}_ Sets the URL of the page with the content of the UI element. You will create the source file used in the URL above later in the example. When creating links to dashboard pages, you need to understand and correctly specify the query string parameters:
- **dashboardName** - sets a name for the dashboard to ensure uniqueness in cases where multiple dashboards use the same page template. The content of a dashboard is unique for every user. If two or more dashboards share a page template and the _dashboardName_ parameters in the URLs used to access the page have the same value, changes made to one of the dashboards also affect the other dashboards (for the given user and site).
- **templateName** - specifies the code name of the page template that the dashboard is based on. The type of the assigned template must be _Dashboard page_. This example uses the template created in the previous steps.
- **hash** - the system automatically generates a hash code for the element
7. Click **Save**.
> **Info:** When adding applications to the interface of an actual live website, you can set a [macro condition](https://docs.kentico.com/k81/macro-expressions/writing-macro-conditions.md) in the **Content permissions** field to define security requirements for access to the application.
The system creates the new UI element.
## Creating the dashboard page source file
Now you need to develop the **.aspx** file of the dashboard page in your web project:
1. Open your website in Visual Studio.
2. Create a **New folder** under the root called _CMSGlobalFiles_ (if it doesn't already exist).
3. Right‑click the folder and select **Add -> Web form**.
4. Name the web form _CommDashboard_.
- This is the file specified in the **Target URL** of the previously created UI element. The location ensures that the system exports the file with any site that includes global folders in the export package.
5. Modify the page code to match the following:
```html
<%@ Page Language="C#" AutoEventWireup="true" CodeFile="CommDashboard.aspx.cs" Theme="Default" EnableEventValidation="false" Inherits="CMSGlobalFiles_CommDashboard" %>
<%@ Register Src="~/CMSModules/Widgets/Controls/Dashboard.ascx" TagName="Dashboard" TagPrefix="cms" %>
<%=DocType%>
>
Dashboard
```
> **Info:** The **Dashboard** user control handles the entire functionality of the dashboard. It processes the query string parameters from the URL used to access the page and displays the corresponding dashboard according to the specified dashboard name, page template and context‑related data such as the current site and user.
6. Switch to the web form's code behind and add the following references to the beginning of the code:
```csharp
using CMS.Core;
using CMS.UIControls;
using CMS.SiteProvider;
```
7. Set the **CMSGlobalFiles\_CommDashboard** class to inherit from **DashboardPage**.
8. Modify the class to contain the following code:
```csharp
[UIElement(ModuleName.CUSTOMSYSTEM, "CommDashboardElement")]
public partial class CMSGlobalFiles_CommDashboard : DashboardPage
{
protected override void OnPreInit(EventArgs e)
{
base.OnPreInit(e);
// Must be equal to the code name of the module containing the corresponding UI element
ucDashboard.ResourceName = "cms.customsystemmodule";
// Must be equal to the code name of the corresponding UI element
ucDashboard.ElementName = "CommDashboardElement";
ucDashboard.PortalPageInstance = this as PortalPage;
ucDashboard.TagsLiteral = this.ltlTags;
// Ensures that the dashboard has unique content for each site
ucDashboard.DashboardSiteName = SiteContext.CurrentSiteName;
ucDashboard.SetupDashboard();
}
protected void Page_Load(object sender, EventArgs e)
{
// Security access checks for the current user
}
}
```
> **Info:** The handler of the _PreInit_ event sets the properties of the **Dashboard** user control calls and its **SetupDashboard()** method. Note that the values of the **ResourceName** and **ElementName** properties must be set according to the module and code name of the UI element created in previous steps of this example.
9. **Save** both files. If your installation is a web application, **Build** the CMSApp project.
## Result
Users can now access the **Community overview** application either through the application list or the application dashboard (if you add the application to the roles of users).
The page displays a fully functional dashboard based on the created page template.
