In this article, you will find the requirements to get started with Umbraco UI Builder. Umbraco UI Builder allows you to create and manage custom UI elements for your Umbraco backoffice.

Prerequisites

• Umbraco 15+ website configured and ready to install Umbraco UI Builder.

System Requirements

To use Umbraco UI Builder, your setup must meet these minimum requirements:

• Umbraco CMS version 15+

• SQL Server Database (SQLite is acceptable for testing but not recommended for live deployments)

Versioning

Umbraco UI Builder is an add-on product for Umbraco CMS, and follows the versioning strategy laid out for Umbraco CMS.

Umbraco UI Builder is a commercial product. You can use Umbraco UI Builder locally without a license. When running Umbraco UI Builder on a public domain the usage is limited to a single editable collection. To remove these restrictions, a valid license is required.

How Licensing Works

Licenses are sold per backoffice domain and applies to all subdomains. If you have alternative staging/QA environment domains, additional domains can be added to the license on request.

Example License Coverage

A license for mysite.com and requested dev domains (devdomain.com and devdomain2.com) will cover:

• localhost

• *.local

• *.mysite.com

• www.mysite.com

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What a License Covers?

There are a few differences as to what the licenses cover:

• A single license covers the installation of Umbraco UI Builder in one production backoffice domain, as well as in any requested development domains.

• The production domain includes all subdomains (e.g. *.mysite.com).

• The development domains work with or without the www subdomain.

• The license allows for an unlimited number of editable collections.

• The license also includes localhost and *.local as a valid domain.

Configuring Your License

You can look at the pricing, features, and purchase a license on the Umbraco UI Builder page. On this page, you can fill out the form with your project details and requirements.

A member of the Sales team will manage this process. In the process, you will need to provide all domains you wish to have covered by the license such as primary and staging/QA domains. You should then receive a license code to be installed in your solution.

Adding Additional Domains

If you require to add additional domains to the license, reach out to the sales team. They will manage your request and take care of the process.

Installing your license

Once you have received your license code it needs to be installed on your site.

1. Open the root directory of your project files.

2. Locate and open the appSettings.json file.

3. Add your Umbraco UI builder license key under Umbraco:Licenses:Products:Umbraco.UIBuilder:

"Umbraco": {
    "Licenses": {
        "Products": {
            "Umbraco.UIBuilder": "YOUR_LICENSE_KEY"
         }
  }
}

"Umbraco_UIBuilder": "YOUR_LICENSE_KEY"

Verifying the License

To verify that your license is successfully installed:

1. Log into Umbraco Backoffice.

2. Navigate to the Settings > License dashboard.

3. Verify the license status displayed on the dashboard.

Validating a License Without an Internet connection

Some Umbraco installations will have a highly locked down production environment, with firewall rules that prevent outgoing HTTP requests. This will interfere with the normal process of license validation.

On start-up, and periodically whilst Umbraco is running, the license component used by Umbraco UIBuilder will make an HTTP POST request to https://license-validation.umbraco.com/api/ValidateLicense.

If it's possible to do so, the firewall rules should be adjusted to allow this request.

If such a change is not feasible, there is another approach you can use.

You will need to have a server, or serverless function, that is running and can make a request to the online license validation service. That needs to run on a daily schedule, making a request and relaying it onto the restricted Umbraco environment.

To set this up, firstly ensure you have a reference to Umbraco.Licenses version 13.1 or higher. If the version of UIBuilder you are using depends on an earlier version, you can add a direct package reference for Umbraco.Licenses.

Then configure a random string as an authorization key in configuration. This is used as protection to ensure only valid requests are handled. You can also disable the normal regular license checks - as there is no point in these running if they will be blocked:

  "Umbraco": {
    "Licenses": {
      "Umbraco.UIBuilder": "<your license key>"
    },
    "LicensesOptions": {
      "EnableScheduledValidation": false,
      "ValidatedLicenseRelayAuthKey": "<your authorization key>"
    }

Your Internet enabled server should make a request of the following form to the online license validation service:

POST https://license-validation.umbraco.com/api/ValidateLicense
{
    "ProductId": "Umbraco.UIBuilder",
    "LicenseKey": "<your license key>",
    "Domain": "<your licensed domain>"
}

The response should be relayed exactly via an HTTP request to your restricted Umbraco environment:

POST http://<your umbraco environment>/umbraco/licenses/validatedLicense/relay?productId=<product id>&licenseKey=<license key>

A header with a key of X-AUTH-KEY and value of the authorization key you have configured should be provided.

This will trigger the same processes that occur when the normal scheduled validation completes ensuring your product is considered licensed.

Umbraco UI Builder strives to closely mimic the content pipeline while adhering to public and supported APIs. This ensures full compatibility with the Data Type suite for property editing. However, some features in the Umbraco Core rely on internal methods, making full support for certain functionalities challenging. Below is a list of known issues.

Property Editors

Tags

While Umbraco UI Builder supports persisting tag values, it currently does not write these tags to the cmsTags database table. This functionality is managed by the internal tagsRepository, which is not publicly accessible, preventing direct saving in the same manner as Umbraco Core.

Block Editors

Block Editors (Block List/Block Grid) are not currently supported due to casting errors between the JSON string representation and collection property.

An implementation to address this is investigated and will be scheduled for a future major release.

In this article, you will learn how to install Umbraco UI Builder into your Umbraco CMS implementation.

Install via Command Line

Run the following command in your web project:

dotnet add package Umbraco.UIBuilder

For a class library without UI elements, install:

dotnet add package Umbraco.UIBuilder.Startup

Install via Visual Studio

To install via Visual Studio, follow these steps:

1. Open Visual Studio and load your project.

2. Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution...

3. Select the Browse tab and search for Umbraco.UIBuilder.

1. Select a version from the Version drop-down based on the Umbraco CMS version you are using.

2. Click Install.

3. [Optional] Search for and install Umbraco.UIBuilder.Startup if installing without UI elements.

4. Ensure that the package reference is added to the .csproj file once the installation is complete:

<ItemGroup>
<PackageReference Include="Umbraco.UIBuilder" Version="15.0.2" />
</ItemGroup>

Installing a License

For details on how to install a license, see the Licensing article.

Umbraco UI Builder is a tool for creating custom Backoffice User Interfaces (UIs) in Umbraco using a fluent API.

If you have a custom data store that you want to manage within Umbraco, you can use Umbraco UI Builder. With few lines of code, you can configure a custom administration UI, and reuse many core components with a consistent look and feel.

With Umbraco UI Builder, custom backoffice integrations can now be set up in minutes rather than days.

Using The Documentation

This documentation is intended for developers with a basic understanding of Umbraco and C#/MVC principles.

If you are new to Umbraco UI Builder, it is recommended to start with the Getting Started section. This section covers system requirements and installation instructions.

Once you have Umbraco UI Builder installed, explore the Guides section. This section provides a quick-start example on configuring Umbraco UI Builder.

Use the main menu to explore features in detail and navigate directly to topics of interest.

For additional resources and best practices, visit the Miscellaneous section.

Getting Help

If you need assistance, refer to our support channels for help and troubleshooting.

This article provides upgrade instructions for major versions of Umbraco UI Builder.

Upgrade to Version 14

Legacy Version Upgrade Notes

You can configure Umbraco UI Builder either via a Composer or in the Program.cs.

Option 1: Configuring via a Composer

A Composer is a common approach for registering and configuring services in Umbraco during application startup.

To configure Umbraco UI Builder via a Composer:

1. Create a file called UIBuilderComposer.cs in your project.

2. Implement the IComposer interface and add the configuration inside the Compose method:

Option 2: Configuring via Program.cs

You can also configure Umbraco UI Builder directly in Program.cs using the AddUIBuilder extension method.

To configure Umbraco UI Builder:

1. Open the Program.cs file in your project.

2. Locate the CreateUmbracoBuilder() method.

3. Add AddUIBuilder before AddComposers().

Example Configuration

The AddUIBuilder method accepts a delegate function, allowing you to configure your solution using fluent APIs.

This guide walks you through migrating a default Konstrukt solution to Umbraco UI Builder.

Key Changes

Before starting, review these key changes that impact the migration process.

Project, Package, and Namespace changes

Code and UI Changes

Step 1: Replace Dependencies

Replace all existing Konstrukt dependencies with Umbraco UI Builder dependencies.

1. Remove existing Konstrukt packages:

1. Delete the Konstrukt App_Plugins folder:

1. Install Umbraco.UIBuilder:

1. Compile your project against .NET 7.0.

Step 2: Update Namespaces and Entity Names

Step 3: Update Configuration

If your configuration is in a single statement, replace AddKonstrukt with AddUIBuilder.

Step 4: Finalize the Migration

1. Delete obj/bin folders for a clean build.

2. Recompile all projects and ensure all dependencies are restored correctly.

3. Remove existing Konstrukt license files from umbraco\Licenses folder.

4. Add your Umbraco.UIBuilder license key to the appSettings.json file:

1. Run the project.

This guide walks you through a basic implementation of Umbraco UI Builder to manage a custom database table.

Setting Up the Database

Umbraco UI Builder uses PetaPoco as its default persistence layer.

In this section, you will create a Person table to store data.

To create a Person table, run the following script in SQL Server Management Studio (SSMS).

This script creates a table for storing people’s details. You may want to populate it with some dummy data for testing.

Setting Up the Model

With the database table created, define the Person model in your project.

To create a Model:

1. Create a new folder called Models in your project.

2. Add a new class file called Person.cs.

3. Add the following code:

Configure Umbraco UI Builder

With the database and model set up, it is time to configure Umbraco UI Builder to work with the Person model. This will allow you to manage Person entities from the Umbraco backoffice.

Configuring via Program.cs

1. Open the Program.cs file in your project.

2. Locate the CreateUmbracoBuilder() method.

3. Add AddUIBuilder before AddComposers().

Example Configuration

Here’s an example configuration defining a section, a list view, and an editor for managing Person entities:

Accessing the Umbraco Backoffice

After defining the configuration, compile and run your project. To access the newly defined section, you need to give permission to the backoffice user account:

1. Login to the Umbraco backoffice.

2. Go to the Users section.

3. Navigate to the user group you wish to assign the newly defined section.

1. Submit the changes.

2. Refresh the browser to view the new section.

If you click on a person's name, you will see the following screen:

Summary

This setup allows you to extend and customize your Umbraco site by managing data and entities directly in the backoffice. The simplicity of the implementation allows to create dynamic, user-friendly interfaces for your own data models.

Umbraco UI Builder can be integrated into different areas of the Umbraco Backoffice. Before you start managing content, it is essential to decide which area best suits the presentation of your data. Each area offers unique features for displaying and interacting with content.

Once you have identified the most appropriate area, you can proceed with configuring it to suit your needs.

Key Areas for Integration

• Sections: The Sections area allows you to organize your content in a structured layout, enabling users to navigate different parts of the backoffice.

• Dashboards: The Dashboards area is ideal for creating custom views that provide quick access to key information and statistics.

• Context Apps: Context Apps provide contextual tools and information based on the specific content a user is working with.

Selecting the correct area is essential to ensure your UI is both functional and user-friendly. Consider the nature of your content and the tasks users need to perform when deciding which area to use.

This article explains how to manually upgrade Umbraco UI Builder to the latest version. Before upgrading Umbraco UI Builder, see the Version Specific Upgrade Notes for potential breaking changes and common pitfalls.

Get the latest version of Umbraco UI Builder

To get the latest version of Umbraco UI Builder, you can upgrade using either of the two options:

• NuGet

• Visual Studio

NuGet

• To install the latest version via NuGet:

dotnet add package Umbraco.UIBuilder

• To specify a package version:

dotnet add package Umbraco.UIBuilder --version <VERSION>

• After adding the package reference, restore dependencies:

dotnet restore

Visual Studio

1. Open Visual Studio.

2. Navigate to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution....

3. Select Umbraco.UIBuilder.

4. Choose the latest version from the drop-down and click Install.

5. After installation, verify the update in your .csproj file:

<ItemGroup>
  <PackageReference Include="Umbraco.UIBuilder" Version="xx.x.x" />
</ItemGroup>

Upgrade Sub-Packages

If you are using any of the following sub-packages, upgrade them as well:

This section summarizes the changes and fixes introduced in each version of Umbraco UI Builder. Each release includes a link to the UI Builder issue tracker, where you can find a list of resolved issues. Individual issues are also linked for more details.

If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.

Release History

Below are the release notes for Umbraco UI Builder 15, detailing all changes in this version.

15.1.0 (March 4th 2025)

• Updated licensing engine.

• Fixed issue with import entity action for Umbraco Cloud websites #92.

• Added feature to allow server-side complex validation using repository events.

• Enable sorting a list view based on the Name column.

• Fixed issue with SetHeading collection property.

• Fixed issue with setting a list view page size programmatically using SetPageSize.

15.0.3 (February 5th 2025)

• Fixed an issue with filter input values persistence for filterable properties.

• Filterable properties UI updates

15.0.2 (January 22nd 2025)

• Added updates to the licensing engine.

• Fixed an error in the entity update action.

15.0.1 (December 16th 2024)

• Added previously validated license resolver, to validate a license if a validation process was already executed successfully in the past 7 days.

• Fixed an issue caused by where clauses for filter expression and deleted property.

• Allow entity properties to be searched based on pattern: StartsWith | Contains #116.

• Switch entity create/edit header to label view for read-only collections #111.

15.0.0 (November 14th 2024)

• Product migrated to support the new Web Component-based Umbraco.

You can read more about the new Backoffice in the Umbraco CMS documentation.

Legacy Release Notes

You can find the release notes for Konstrukt in the Change log file on GitHub.

Folders help organize trees in Umbraco UI Builder, allowing you to structure content with nested folders and collections. A folder can exist within a tree or as a sub-folder within another folder. Folders can contain either sub-folders or Collections.

Defining a Folder

To define a folder, use one of the AddFolder methods on a Tree or parent Folder config builder instance.

Using the AddFolder() Method

Adds a folder to the current tree with the specified name and a default folder icon.

Method Syntax

AddFolder(string name, Lambda folderConfig = null) : FolderConfigBuilder

Example

treeConfig.AddFolder("Settings", folderConfig => {
    ...
});

Using the AddFolder() Method with Custom Icon

Adds a folder to the current tree with a specified name and icon.

Method Syntax

AddFolder(string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder

Example

treeConfig.AddFolder("Settings", "icon-settings", folderConfig => {
    ...
});

Changing a Folder Alias

When creating a new folder, an alias is automatically generated. However, if you need a specific alias, you can use the SetAlias method to override it.

Using the SetAlias() Method

Sets a custom alias for a folder.

Method Syntax

SetAlias(string alias) : FolderConfigBuilder

Example

folderConfig.SetAlias("settings");

Changing a Folder Icon Color

Using the SetIconColor() Method

Sets the folder icon color to the given color. The available colors are: black, green, yellow, orange, blue, or red.

Method Syntax

SetIconColor(string color) : FolderConfigBuilder

Example

folderConfig.SetIconColor("blue");

Adding a Sub-Folder To a Folder

Using the AddFolder() Method for Sub-Folders

Adds a sub-folder inside the current folder with a specified name and a default folder icon.

Method Syntax

AddFolder (string name, Lambda folderConfig = null) : FolderConfigBuilder

Example

folderConfig.AddFolder("Categories", subFolderConfig => {
    ...
});

Using the AddFolder() Method for Sub-Folders with Custom Icon

Adds a sub folder to the current folder with a specified name and custom icon.

Method Syntax

AddFolder (string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder

Example

folderConfig.AddFolder("Categories", "icon-tags", subFolderConfig => {
    ...
});

Adding a Collection to a Folder

Using the AddCollection<>() Method

Adds a collection to the current folder with the given names, descriptions, and default icons. The ID property must be defined. For more details, see the Collections article.

Method Syntax

AddCollection<TEntityType>(
    Lambda idFieldExpression, 
    string nameSingular, 
    string namePlural, 
    string description, 
    Lambda collectionConfig = null
) : CollectionConfigBuilder<TEntityType>

Example

folderConfig.AddCollection<Person>(
    p => p.Id, 
    "Person", 
    "People", 
    "A collection of people", 
    collectionConfig => {
        ...
    }
);

Using the AddCollection<>() Method with Custom Icons

Adds a collection to the current folder with the given names, description and icons. The ID property must be defined. For more details, see the Collections article.

Method Syntax

AddCollection<TEntityType>(
    Lambda idFieldExpression, 
    string nameSingular, 
    string namePlural, 
    string description, 
    string iconSingular, 
    string iconPlural, 
    Lambda collectionConfig = null
) : CollectionConfigBuilder<TEntityType>

Example

folderConfig.AddCollection<Person>(
    p => p.Id, 
    "Person", 
    "People", 
    "A collection of people", 
    "icon-umb-users", 
    "icon-umb-users", 
    collectionConfig => {
        ...
    }
);

Before diving into Umbraco UI Builder, it’s important to understand some of the fundamental concepts of the Umbraco UI. This knowledge will help you navigate and leverage the UI Builder more effectively, as it uses the same UI components to construct interfaces.

Section

A section in Umbraco is a distinct area within the backoffice where related content and functionality are grouped. For example, the Content section is where content management happens, while the Media section handles media files.

Tree

The tree represents the hierarchical structure of items within a section. It organizes content, settings, and data, for quick navigation and locating items. For example, the content tree shows the pages of a website in a nested format.

Dashboard

Each section in the Umbraco backoffice typically starts with a dashboard. This is an introductory screen for the section. It often includes useful links or shortcuts, providing an overview or quick access to the most commonly used features.

Collection

The collection displays a list of items in a tree or grid view. It provides an overview of content or data in a table format, with sortable columns and the option to filter or search through the items. This view is used when you need to work with multiple items at once.

Editor

The editor is where the main content editing occurs. It is structured using tabs, fieldsets, and fields. Tabs organize different sections of content, and fieldsets group related fields together. Each field represents a specific piece of data, such as a text box or an image upload.

Workspace Views

Workspace Views are additional functionality that can be added to an editor. They provide extra features based on the content of the item being edited. For instance, a media content app might allow you to resize or crop an image directly from the editor.

Tabs

Tabs are used to organize content within the editor, allowing users to switch between different sections of a content item. For example, one tab might contain the general settings, while another contains media or advanced options.

Menu Item

A menu item represents an action within the context of a tree node or a list item. It is a clickable item that triggers specific tasks, such as deleting or editing an item.

Bulk Action

Bulk actions allow you to perform an operation on multiple items in the list view at once. For example, you might use a bulk action to delete multiple content items or update their status in a single step.

A collection is the cornerstone Umbraco UI Builder config and it represents a collection of entities for a given data model. From this config object, you can configure everything about how this collection integrates into the UI. You can also configure how it should display in a list view as well as how it should be edited.

Get started by reviewing the basics of collection configuration.

Dashboards in Umbraco UI Builder provide an intuitive way to present important information and tools at the root of a section within the Umbraco backoffice. They serve as a starting point for users, offering quick access to relevant data, insights, or actions. Dashboards can be customized, reordered, and configured to display for specific user groups, making them a flexible tool for enhancing the backoffice experience. When multiple dashboards are available in a section, they appear in a tabbed layout for easy navigation.

Defining a Dashboard

You can define a dashboard by calling one of the AddDashboard methods on a SectionConfigBuilder or a WithSectionConfigBuilder instance.

Using the AddDashboard() Method

Adds a dashboard with the specified name.

Method Syntax

AddDashboard(string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

sectionConfig.AddDashboard("Team", dashboardConfig => {
    ...
});

Using the AddDashboardBefore() Method

Adds a dashboard with the specified name before the dashboard with the given alias.

Method Syntax

AddDashboardBefore(string beforeAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

sectionConfig.AddDashboardBefore("contentIntro", "Team", dashboardConfig => {
    ...
});

Using the AddDashboardAfter() Method

Adds a dashboard with the specified name after the dashboard with the given alias.

Method Syntax

AddDashboardAfter(string afterAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

sectionConfig.AddDashboardAfter("contentIntro", "Team", dashboardConfig => {
    ...
});

Setting a Custom Dashboard Alias

Using the SetAlias() Method

Sets the alias of the dashboard. By default, an alias is automatically generated based on the supplied name. If a specific alias is required, the SetAlias method can be used to override the default.

Method Syntax

SetAlias(string alias) : DashboardConfigBuilder

Example

dashboardConfig.SetAlias("team");

Controlling Dashboard Visibility

Dashboard visibility can be controlled using ShowForUserGroup and HideForUserGroup, which specify which user groups can see the dashboard. These settings can be applied multiple times for different user roles.

By default, dashboards are pre-filtered to display only in their defined section. This filtering is combined with the SetVisibility method to control when a dashboard appears.

Using the SetVisibility() Method

Defines visibility rules for the dashboard.

Method Syntax

SetVisibility(Lambda visibilityConfig) : DashboardConfigBuilder

Example

dashboardConfig.SetVisibility(visibilityConfig => visibilityConfig
    .ShowForUserGroup("admin")
    .HideForUserGroup("translator")
);

Assigning a Collection to a Dashboard

A dashboard can display only one collection. To display multiple collections, multiple dashboards must be configured.

Using the SetCollection<>() Method

Assigns a collection to the dashboard with the specified names, descriptions, and default icons. The ID property must be defined. For more details, see the Collections article.

Method Syntax

SetCollection<TEntityType>(
    Lambda idFieldExpression, 
    string nameSingular, 
    string namePlural, 
    string description, 
    Lambda collectionConfig = null
) : ContextAppConfigBuilder

Example

dashboardConfig.SetCollection<Comment>(
    p => p.Id, 
    "Team Member", 
    "Team Members", 
    "A collection of team members", 
    collectionConfig => {
        ...
    }
);

Using the SetCollection<>() Method with Custom Icons

Assigns a collection to the dashboard with the specified names, descriptions, and custom icons. The ID property must be defined. For more details, see the Collections article.

Method Syntax

SetCollection<TEntityType>(
    Lambda idFieldExpression, 
    Lambda fkFieldExpression, 
    string nameSingular, 
    string namePlural, 
    string description, 
    string iconSingular, 
    string iconPlural, 
    Lambda collectionConfig = null
) : ContextAppConfigBuilder

Example

dashboardConfig.SetCollection<Comment>(
    p => p.Id, 
    p => p.ForeignKey, 
    "Team Member", 
    "Team Members", 
    "A collection of team members", 
    "icon-umm-user", 
    "icon-umb-user", 
    collectionConfig => {
        ...
    }
);

A section in Umbraco represents a distinct area within the backoffice, such as content, media, and so on. Sections are accessible via links in the main menu at the top of the Umbraco interface. Using Umbraco UI Builder, multiple sections can be defined to organize the management of models logically.

Defining a Section

Sections are defined using the AddSection method on the root-level UIBuilderConfigBuilder instance.

Using the AddSection() Method

This method adds a new section to the Umbraco menu with the specified name, allowing custom areas for organizing content in the backoffice.

Method Syntax

AddSection(string name, Lambda sectionConfig = null) : SectionConfigBuilder

Example

config.AddSection("Repositories", sectionConfig => {
    ...
});

Using the AddSectionBefore() Method

This method adds a section before another section with the specified alias, allowing for customized ordering of sections in the backoffice.

Method Syntax

AddSectionBefore(string beforeAlias, string name, Lambda sectionConfig = null) : SectionConfigBuilder

Example

config.AddSectionBefore("settings", "Repositories", sectionConfig => {
    ...
});

Using the AddSectionAfter() Method

This method adds a section after another section with the specified alias, allowing for a custom order of sections in the backoffice.

Method Syntax

AddSectionAfter(string afterAlias, string name, Lambda sectionConfig = null) : SectionConfigBuilder

Example

config.AddSectionAfter("media", "Repositories", sectionConfig => {
    ...
});

Customizing the Section Alias

Setting a Custom Alias with SetAlias() Method

This method sets a custom alias for the section.

Optional: By default, an alias is automatically generated from the section's name. To customize the alias, the SetAlias() method can be used.

Method Syntax

SetAlias(string alias) : SectionConfigBuilder

Example

sectionConfig.SetAlias("repositories");

Configuring the Section Tree

Using the Tree() Method for Configuration

This method configures the tree structure for the section, which is used to organize content types. For more information, see the Trees article.

Method Syntax

Tree(Lambda treeConfig = null) : TreeConfigBuilder

Example

sectionConfig.Tree(treeConfig => {
    ...
});

Adding Dashboards to the Section

Adding a Dashboard with the AddDashboard() Method

This method adds a dashboard to the section with the specified alias, providing tools and features for content management. For more information, see the Dashboards article.

Method Syntax

AddDashboard(string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

sectionConfig.AddDashboard("Team", dashboardConfig => {
    ...
});

Using AddDashboardBefore() to Place a Dashboard

This method adds a dashboard before another dashboard with the specified alias, allowing custom placement in the section. For more information, see the Dashboards article.

Method Syntax

AddDashboardBefore(string beforeAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

sectionConfig.AddDashboardBefore("contentIntro", "Team", dashboardConfig => {
    ...
});

Using AddDashboardAfter() to Place a Dashboard

This method adds a dashboard after another dashboard with the specified alias, giving control over dashboard order. For more information, see the Dashboards article.

Method Syntax

AddDashboardAfter(string afterAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

sectionConfig.AddDashboardAfter("contentIntro", "Team", dashboardConfig => {
    ...
});

Extending Existing Sections

You can extend existing sections by adding Umbraco UI Builder trees and dashboards, context apps, and virtual subtrees. This can be done by calling the WithSection method on the root-level UIBuilderConfigBuilder instance.

Extending an Existing Section with WithSection()

This method extends an existing section with additional configuration, enabling more customization for existing areas.

Method Syntax

WithSection(string alias, Lambda sectionConfig = null) : WithSectionConfigBuilder

Example

config.WithSection("member", withSectionConfig => {
    ...
});

Adding Trees to an Existing Section

Using the AddTree() Method

This method adds a tree to the section, helping to visualize and organize content types. For more information, see the Trees article.

Method Syntax

AddTree(string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder

Example

withSectionConfig.AddTree("My Tree", "icon-folder", treeConfig => {
    ...
});

Grouping Trees with AddTree() Method

This method adds a tree within a specified group, improving content organization by grouping related trees together. For more information, see the Trees article.

Method Syntax

AddTree(string groupName, string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder

Example

withSectionConfig.AddTree("My Group", "My Tree", "icon-folder", treeConfig => {
    ...
});

Adding a Tree Before or After an Existing Tree

Using AddTreeBefore() to Position a Tree

This method adds a tree before another tree within the section, allowing you to customize the tree order. For more information, see the Trees article.

Method Syntax

AddTreeBefore(string treeAlias, string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder

Example

withSectionConfig.AddTreeBefore("member", "My Tree", "icon-folder", treeConfig => {
    ...
});

Using AddTreeAfter() to Position a Tree

This method adds a tree after another tree within the section, enabling specific ordering of trees. For more information, see the Trees article.

Method Syntax

AddTreeAfter(string treeAlias, string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder

Example

withSectionConfig.AddTreeAfter("member", "My Tree", "icon-folder", treeConfig => {
    ...
});

Adding a Dashboard to an Existing Section

Using the AddDashboard() Method

This method adds a new dashboard to the section with the specified name. For more information, see the Dashboards article.

Method Syntax

AddDashboard (string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

withSectionConfig.AddDashboard("Team", dashboardConfig => {
    ...
});

Using the AddDashboardBefore() Method

This method adds a dashboard before the dashboard with the specified alias. For more information, see the Dashboards article.

Method Syntax

AddDashboardBefore (string beforeAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

withSectionConfig.AddDashboardBefore("contentIntro", "Team", dashboardConfig => {
    ...
});

Using the AddDashboardAfter() Method

This method adds a dashboard after the dashboard with the specified alias. For more information, see the Dashboards article.

Method Syntax

AddDashboardAfter (string afterAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Example

withSectionConfig.AddDashboardAfter("contentIntro", "Team", dashboardConfig => {
    ...
});

Context Apps in Umbraco UI Builder function similarly to Content Apps. They provide contextual applications within the content editor UI. By defining context apps, you can expose collections that are directly related to the content in question. For example, blog post comments can be linked to their respective blog posts and managed in context through a content app.

Defining a Context App

Using the AddContextApp() Method

Adds a context app with the specified name and default icon.

Method Syntax

Example

Using the AddContextApp() Method with Custom Icon

Adds a context app with the specified name and custom icon.

Method Syntax

Example

Using the AddContextAppBefore() Method

Adds a context app with the specified name and default icon before another context app specified by its alias.

Method Syntax

Example

Using the AddContextAppBefore() Method with a Custom Icon

Adds a context app with the specified name and custom icon before another context app specified by its alias.

Method Syntax

Example

Using the AddContextAppAfter() Method

Adds a context app with the specified name and default icon after another context app specified by its alias.

Method Syntax

Example

Using the AddContextAppAfter() Method with a Custom Icon

Adds a context app with the specified name and custom icon after another context app specified by its alias.

Method Syntax

Example

Changing a Context App Alias

Using the SetAlias() Method

Sets the alias of the context app. By default, an alias is automatically generated from the context app's name. You can use the SetAlias method to specify a custom alias.

Method Syntax

Example

Changing a Context App Icon Color

Using the SetIconColor() Method

Sets the context app icon color to the given color. The available colors are: black, green, yellow, orange, blue or red.

Method Syntax

Example

Changing Context App Visibility

Context app visibility is controlled by a delegate that takes a ContextAppVisibilityContext instance. This method contains a Source property which holds a reference to the source object that the content app is being displayed on (i.e., an IContent instance). It also holds a reference to a UserGroups collection of the currently logged-in user's user groups. You can use these values to determine when the context app should be displayed.

By default, context apps are pre-filtered to only appear on the tree they are defined in. This default behavior is combined with the SetVisibility configuration to control visibility.

Using the SetIconColor() Method

Defines the visibility of the context app based on a delegate expression.

Method Syntax

Example

Adding a Collection to a Context App

Context apps can consist of one or more collections. If a context app contains multiple collections, the collection list views will be displayed in tabs within the context app.

Using the AddCollection<>() Method

Method Syntax

Example

Using the AddCollection<>() Method with Custom Icon

AddCollection<TEntityType>(Lambda idFieldExpression, Lambda fkFieldExpression, string nameSingular, string namePlural, string description, string iconSingular, string iconPlural, Lambda collectionConfig = null) : ContextAppConfigBuilder

Method Syntax

Example

Field Views allow you to customize the markup used by a field when displayed in a list view. Field Views are implemented as .NET Core View Components that are passed a single FieldViewsContext argument with information about the entity/field being rendered.

Defining a field view

You can define a field view in one of two ways.

1. A basic view file for the built in FieldView view component

The simplest way to define a field view for non-complex fields is to place a view file in the /Views/Shared/Components/FieldView folder with the following markup.

When registering a basic file view you can pass the name of the view file (excluding the .cshtml file extension) to the relevant API method.

2. A complete custom view component

To define a more complex field view you can create your own view component class (which can use dependency injection for any required dependencies). This can be done by using the following signature:

For the view element of your component, based on the example above, you would place a file Default.cshtml into the /Views/Shared/Components/MyComplexFieldView folder with the following markup:

The field view context

Field view components are passed a FieldViewContext object with the following information:

Setting the field view of a list view field

Retrieving child collections in one-to-many relationships with UI Builder, can be achieved with the support of child repositories. One-to-many relations are where one parent entity of a collection is associated with multiple entities from another.

Models Representation

The models would look like this:

Child Repositories

You can create child repository instances via the IRepositoryFactory and use them to retrieve information from the child collection.

A tree is a hierarchical structure that organizes sections into sub-sections. It appears in the main side panel of the Umbraco interface. In Umbraco UI Builder, each section can only have one tree definition, but you can use folder nodes to organize the tree.

Configuring a Umbraco UI Builder Section Tree

Using the Tree() Method

This method defines the structure and behavior of a tree within a section.

Method Syntax

Example

Adding a Tree to an Existing Section

Using the AddTree() method

This method adds a tree to the current section, specifying its name and icon.

Method Syntax

Example

Grouping Trees with AddTree() Method

This method adds a tree to the current section under a specified group.

Method Syntax

Example

Using AddTreeBefore() to Position a Tree

This method adds a tree to the current section before the tree with the specified alias.

Method Syntax

Example

Using AddTreeAfter() to Position a Tree

This method adds a tree to the current section after the tree with the specified alias.

Method Syntax

Example

Changing the Tree Icon Color

Using the SetIconColor() Method

This method changes the color of the tree’s icon. The available options are black, green, yellow, orange, blue, or red.

Method Syntax

Example

Adding a Group to a Tree

Using the AddGroup() Method

This method adds a group to the current tree with the specified name.

Method Syntax

Example

Adding a Folder to a Tree or Group

Using the AddFolder() Method

Method Syntax

Example

Using the AddFolder() Method with Custom Icon

Method Syntax

Example

Adding a Collection to a Tree or Group

Using the AddCollection<>() Method

Method Syntax

Example

Using the AddCollection<>() Method with Icons

Method Syntax

Example

Extending an Existing Tree

Using the WithTree() Method

This method starts a sub-configuration for an existing tree with the specified alias.

Method Syntax

Example

Adding a Context App to an Existing Tree

Using the AddContextApp() Method

Method Syntax

Example

Using the AddContextApp() Method with Custom Icon

Method Syntax

Example

Adding a Context App Before or After Another Context App

Using the AddContextApp() Method Before Another Context App

Method Syntax

Example

Using the AddContextApp() Method with Custom Icon Before Another Context App

Method Syntax

Example

Using the AddContextApp() Method After Another Context App

Method Syntax

Example

Using the AddContextApp() Method with Custom Icon After Another Context App

Method Syntax

Example

A child collection group is a container for other child collections. Its purpose is mainly to provide a logical grouping of multiple child collections to help with organization and an improved user experience.

Defining a child collection group

You can define a child collection group by calling one of the AddChildCollectionGroup methods on a given collection config builder instance.

AddChildCollectionGroup(string name, Lambda childCollectionGroupConfig = null) : ChildCollectionGroupConfigBuilder

Adds a child collection group to the current collection with the given name and default icon.

AddChildCollectionGroup(string name, string icon, Lambda childCollectionGroupConfig = null) : ChildCollectionGroupConfigBuilder

Adds a child collection group to the current collection with the given name and icon.

Defining a child collection

You define a child collection by calling one of the AddChildCollection methods on a given collection config builder instance.

AddChildCollection<TChildEntityType>(Lambda idFieldExpression, Lambda fkFieldExpression, string nameSingular, string namePlural, string description, Lambda childCollectionConfig = null) : ChildCollectionConfigBuilder<TEntityType>

Adds a child collection to the current collection with the given names and description and default icons. A property accessor expression is required for both the entity ID field and FK (Foreign Key) field of the entity.

AddChildCollection<TChildEntityType>(Lambda idFieldExpression, Lambda fkFieldExpression, string nameSingular, string namePlural, string description, string iconSingular, string iconPlural, Lambda childCollectionConfig = null) : ChildCollectionConfigBuilder<TEntityType>

Adds a child collection to the current collection with the given names, description and icons. A property accessor expression is required for both the entity ID field and FK (Foreign Key) field of the entity.

Configuring a child collection

Umbraco UI Builder includes a search API for filtering and locating specific entities within a collection. This enhances usability, especially in collections with large datasets.

Get started by reviewing how to define searchable properties.

An editor is the user interface used to edit an entity and is made up of tabs and property editors.

Configuring an editor

Editor(Lambda editorConfig = null) : EditorConfig<TEntityType>

Accesses the editor config of the given collection.

Adding a tab to an editor

AddTab(string name, Lambda tabConfig = null) : EditorTabConfigBuilder<TEntityType>

Adds a tab to the editor.

Configuring a sidebar to a tab

A slidebar is a smaller area that is displayed to the right of the main editor. The sidebar can also contain fieldsets and fields in the same way tabs can. However, it is a much more limited display area so you'll need to choose your field types carefully. The sidebar is a great location to display entity metadata.

Sidebar(Lambda sidebarConfig = null) : EditorTabSidebarConfigBuilder<TEntityType>

Configures the sidebar for the tab.

Setting the visibility of a tab

SetVisibility(Predicate<EditorTabVisibilityContext> visibilityExpression) : EditorTabConfigBuilder<TEntityType>

Sets the runtime visibility of the tab.

Adding a fieldset to a tab

AddFieldset(string name, Lambda fieldsetConfig = null) : EditorFieldsetConfigBuilder<TEntityType>

Adds the given fieldset to the tab.

Setting the visibility of a fieldset

SetVisibility(Predicate<EditorFieldsetVisibilityContext> visibilityExpression) : EditorFieldsetConfigBuilder<TEntityType>

Sets the runtime visibility of the fieldset.

Adding a field to a fieldset

AddField(Lambda propertyExpression, Lambda propertyConfig = null) : EditorFieldConfigBuilder<TEntityType, TValueType>

Adds the given property to the editor.

Changing the label of a field

By default, Umbraco UI Builder will build the label from the property name, including splitting camel case names into sentence cases. However, you can set an explicit label if preferred.

SetLabel(string label) : EditorFieldConfigBuilder<TEntityType, TValueType>

Sets the label for the editor field.

Hiding the label of a field

Sometimes you may have a field editor that would work better in full width. You can achieve this by explicitly hiding the field label.

HideLabel() : EditorFieldConfigBuilder<TEntityType, TValueType>

Hides the label for the editor field.

Adding a description to a field

SetDescription(string description) : EditorFieldConfigBuilder<TEntityType, TValueType>

Sets the description for the editor field.

Changing the Data Type of a field

By default, Umbraco UI Builder will automatically choose a relevant Data Type for basic field types. However, if you wish to use an alternative Data Type then you can override this.

SetDataType(string dataTypeName) : EditorFieldConfigBuilder<TEntityType, TValueType>

Set the Data Type of the current field to the Umbraco Data Type with the given name.

SetDataType(int dataTypeId) : EditorFieldConfigBuilder<TEntityType, TValueType>

Set the Data Type of the current field to the Umbraco Data Type with the given id.

Setting the default value of a field

SetDefaultValue(TValueType defaultValue) : EditorFieldConfigBuilder<TEntityType, TValueType>

Sets the default value to a known constant.

SetDefaultValue(Func defaultValueFunc) : EditorFieldConfigBuilder<TEntityType, TValueType>

Sets the default value via a function that gets evaluated at time of entity creation.

Making a field required

MakeRequired() : EditorFieldConfigBuilder<TEntityType, TValueType>

Makes the given field required.

Validating a field

SetValidationRegex(string regex) : EditorFieldConfigBuilder<TEntityType, TValueType>

Defines the regular expression to use when validating the field.

Making a field read-only

MakeReadOnly() : EditorFieldConfigBuilder<TEntityType, TValueType>

Makes the current field read-only disabling editing in the UI.

MakeReadOnly(Func<TValueType, string> format) : EditorFieldConfigBuilder<TEntityType, TValueType>

Makes the current field read-only disabling editing in the UI. Provides a custom formatting expression to use when rendering the value as a string.

MakeReadOnly(object dataTypeNameOrId) : EditorFieldConfigBuilder<TEntityType, TValueType>

Makes the current field read-only disabling editing in the UI. Provides the name or id of a datatype to use when in read-only mode.

MakeReadOnly(Predicate<EditorFieldReadOnlyContext> readOnlyExp) : EditorFieldConfigBuilder<TEntityType, TValueType>

Makes the current field read-only disabling editing in the UI if the given runtime predicate is true.

MakeReadOnly(Predicate<EditorFieldReadOnlyContext> readOnlyExp, Func<TValueType, string> format) : EditorFieldConfigBuilder<TEntityType, TValueType>

Makes the current field read-only disabling editing in the UI if the given runtime predicate is true. Provides a custom formatting expression to use when rendering the value as a string.

MakeReadOnly(Predicate<EditorFieldReadOnlyContext> readOnlyExp, object dataTypeNameOrId) : EditorFieldConfigBuilder<TEntityType, TValueType>

Makes the current field read-only disabling editing in the UI if the given runtime predicate is true. Provides the name or id of a datatype to use when in read-only mode.

Setting the visibility of a field

SetVisibility(Predicate<EditorFieldVisibilityContext> visibilityExpression) : EditorFieldConfigBuilder<TEntityType, TValueType>

Sets the runtime visibility of the field.

If you want to work with a subset of data within a given collection then this is where the global filters come in handy. These allow you to define a filter to apply to all queries for a given collection.

Applying a global filter

Applying a global filter is controlled via the collections configuration.

SetFilter(Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

Sets the filter where clause expression. Expression must be a boolean expression.

// Example
collectionConfig.SetFilter(p => p.Current);

Data views builders allow you to create a collection data views list dynamically at run time. By default, Umbraco UI Builder will use the hard-coded data views defined in your Umbraco UI Builder config. However, if you need to build your data views list dynamically, then this is when you'd use a data views builder.

When Umbraco UI Builder resolves a data views builder it will attempt to do so from the global DI container. This means you can inject any dependencies that you require for your builder. If there is no type defined in the DI container, Umbraco UI Builder will fall-back to manually instantiating a new instance of value mapper.

Defining a data views builder

To define a data views builder you can create a class that inherits from the base class DataViewsBuilder<TEntityType> and implements the abstract methods.

// Example
public class PersonDataViewsBuilder : DataViewsBuilder<Person>
{
    public override IEnumerable<DataViewSummary> GetDataViews()
    {
        // Generate and return a list of data views
    }

    public override Expression<Func<Person, bool>> GetDataViewWhereClause(string dataViewAlias)
    {
        // Return a where clause expression for the supplied data view alias
    }
}

The required methods are:

• GetDataViews: Returns the list of data views to choose from.

• GetDataViewWhereClause: Returns the boolean where clause expression for the given data views alias.

Setting the data views builder of a collection

Setting a data views builder is controlled via the collections configuration.

SetDataViewsBuilder<TDataViewsBuilder>() : CollectionConfigBuilder<TEntityType>

Sets the collections data views builder which allows you to define the data views dynamically at run time.

// Example
collectionConfig.SetDataViewsBuilder<PersonDataViewsBuilder>();

SetDataViewsBuilder(Type dataViewsBuilderType) : CollectionConfigBuilder<TEntityType>

Sets the collections data views builder which allows you to define the data views dynamically at run time.

// Example
collectionConfig.SetDataViewsBuilder(typeof(PersonDataViewsBuilder));

SetDataViewsBuilder(DataViewsBuilder<TEntityType> dataViewsBuilder) : CollectionConfigBuilder<TEntityType>

Sets the collections data views builder which allows you to define the data views dynamically at run time.

// Example
collectionConfig.SetDataViewsBuilder(new PersonDataViewsBuilder());

There is a lot that can be configured from the collection config, but what follows are the core basics. You can find more configuration options about specific topics from the other configuration sections in the main menu.

Defining a collection

You can define a collection by calling one of the AddCollection methods on a given Tree or parent Folder config builder instance.

AddCollection<TEntityType>(Lambda idFieldExpression, string nameSingular, string namePlural, string description, Lambda collectionConfig = null) : CollectionConfigBuilder<TEntityType>

Adds a collection to the given container with the given names and description and default icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property.

// Example
folderConfig.AddCollection<Person>(p => p.Id, "Person", "People", "A collection of people", collectionConfig => {
    ...
});

AddCollection<TEntityType>(Lambda idFieldExpression, string nameSingular, string namePlural, string description, string iconSingular, string iconPlural, Lambda collectionConfig = null) : CollectionConfigBuilder<TEntityType>

Adds a collection to the given container with the given names, description and icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property.

// Example
folderConfig.AddCollection<Person>(p => p.Id, "Person", "People", "A collection of people", "icon-umb-users", "icon-umb-users", collectionConfig => {
    ...
});

Changing a collection alias

SetAlias(string alias) : CollectionConfigBuilder<TEntityType>

Sets the alias of the collection.

Optional: When creating a new collection, an alias is automatically generated from the supplied name for you. However, if you need a specific alias you can use the SetAlias method to override this.

// Example
collectionConfig.SetAlias("person");

Changing a collection icon color

SetIconColor(string color) : CollectionConfigBuilder<TEntityType>

Sets the collection icon color to the given color. Possible options are black, green, yellow, orange, blue or red.

// Example
collectionConfig.SetIconColor("blue");

Defining an entity name

Within Umbraco, it is expected that an entity has a name property. So we need to let Umbraco UI Builder know which property to use for the name. If the entity doesn't have a name property, then it needs to know how to construct a name from an entity's other properties. We do this by using either the SetNameProperty or SetNameFormat methods on a Collection config builder instance.

SetNameProperty(Lambda namePropertyExpression) : CollectionConfigBuilder<TEntityType>

Sets which property of your entity to use as the name property. Property must be of type string. By defining a property as the name property, its value will be used as the label for the entity in trees and list views. It will also be editable in the header region of the editor interface. The property will also automatically be added to the searchable properties collection and be used for the default sort property.

// Example
collectionConfig.SetNameProperty(p => p.Name);

SetNameProperty(Lambda namePropertyExpression, string heading) : CollectionConfigBuilder<TEntityType>

Sets which property of your entity to use as the name property and what custom heading should the list view column heading be. Property must be of type string. By defining a property as the name property, its value will be used as the label for the entity in trees and list views. It will also be editable in the header region of the editor interface. The property will also automatically be added to the searchable properties collection and be used for the default sort property.

// Example
collectionConfig.SetNameProperty(p => p.Name, "Person Name");

SetNameFormat(Lambda nameFormatExpression) : CollectionConfigBuilder<TEntityType>

Sets a format expression to use to dynamically create a label for the entity in things like trees and list views. By providing a name format it is assumed there is no single name property available on the entity. And as such none of the default behaviors described for the SetNameProperty method will apply.

// Example
collectionConfig.SetNameFormat(p => $"{p.FirstName} {p.LastName}");

Defining a default sort order

SetSortProperty(Lambda sortPropertyExpression) : CollectionConfigBuilder<TEntityType>

Sets which property of our entity to sort against, defaulting to ascending sort direction.

// Example
collectionConfig.SetSortProperty(p => p.FirstName);

SetSortProperty(Lambda sortPropertyExpression, SortDirection sortDirection) : CollectionConfigBuilder<TEntityType>

Sets which property of our entity to sort against in the provided sort direction.

// Example
collectionConfig.SetSortProperty(p => p.FirstName, SortDirection.Descending);

Defining time stamp properties

SetDateCreatedProperty(Lambda dateCreatedProperty) : CollectionConfigBuilder<TEntityType>

Sets which property of our entity to use as the date created property. Property must be of type DateTime. When set and a new entity is saved via the repository, then the given field will be populated with the current date and time.

// Example
collectionConfig.SetDateCreatedProperty(p => p.DateCreated);

SetDateModifiedProperty(Lambda dateCreatedProperty) : CollectionConfigBuilder<TEntityType>

Sets which property of our entity to use as the date modified property. Property must be of type DateTime. When set and an entity is saved via the repository, then the given field will be populated with the current date and time.

// Example
collectionConfig.SetDateModifiedProperty(p => p.DateModified);

Configuring soft deletes

By default, in Umbraco UI Builder any entity that is deleted via the Umbraco UI Builder repository is definitively removed from the system. The SetDeletedProperty method can be used if needed to keep the records in the data repository despite having them marked as deleted. This is so they do not show the the UI.

SetDeletedProperty(Lambda deletedPropertyExpression) : CollectionConfigBuilder<TEntityType>

Sets which property of our entity to use as the deleted property flag. Property must be of type boolean or int. When a deleted property is set, any delete actions will set the deleted flag instead of deleting the entity. For boolean based properties, deleted entities will have a value of True when deleted. For int based properties, deleted entities will have a UTC Unix timestamp value of the date the entity was deleted. In addition, any fetch actions will also pre-filter out any deleted entities.

// Example
collectionConfig.SetDeletedProperty(p => p.Deleted);

Disabling create, update or delete features

DisableCreate() : CollectionConfigBuilder<TEntityType>

Disables the option to create entities on the current collection. An entity could be created via code and only then editing is allowed in the UI for example.

// Example
collectionConfig.DisableCreate();

DisableCreate(Predicate<CollectionPermissionContext> disableExpression) : CollectionConfigBuilder<TEntityType>

Disables the option to create entities on the current collection if the given runtime predicate is true. An entity could be created via code and only then editing is allowed in the UI.

// Example
collectionConfig.DisableCreate(ctx => ctx.UserGroups.Any(x => x.Alias == "editor"));

DisableUpdate() : CollectionConfigBuilder<TEntityType>

Disables the option to update entities on the current collection. An entity can be created, but further editing is not allowed.

// Example
collectionConfig.DisableUpdate();

DisableUpdate(Predicate<CollectionPermissionContext> disableExpression) : CollectionConfigBuilder<TEntityType>

Disables the option to update entities on the current collection if the given runtime predicate is true. An entity can be created, but further editing is not allowed.

// Example
collectionConfig.DisableUpdate(ctx => ctx.UserGroups.Any(x => x.Alias == "editor"));

DisableDelete() : CollectionConfigBuilder<TEntityType>

Disables the option to delete entities on the current collection. Useful if the data needs to be retained and visible. See also configuring soft deletes.

// Example
collectionConfig.DisableDelete();

DisableDelete(Predicate<CollectionPermissionContext> disableExpression) : CollectionConfigBuilder<TEntityType>

Disables the option to delete entities on the current collection if the given runtime predicate is true. Useful if the data needs to be retained and visible. See also configuring soft deletes.

// Example
collectionConfig.DisableDelete(ctx => ctx.UserGroups.Any(x => x.Alias == "editor"));

MakeReadOnly() : CollectionConfigBuilder<TEntityType>

Sets the collection as read-only and disables any Create, Read, Update, and Delete (CRUD) operations from being performed on the collection via the UI.

// Example
collectionConfig.MakeReadOnly();

MakeReadOnly(Predicate<CollectionPermissionContext> disableExpression) : CollectionConfigBuilder<TEntityType>

Sets the collection as read-only if the given runtime predicate is true. It also disables any Create, Read, Update, and Delete (CRUD) operations from being performed on the collection via the UI.

// Example
collectionConfig.MakeReadOnly(ctx => ctx.UserGroups.Any(x => x.Alias == "editor"));

Set the visibility of the collection

SetVisibility(Predicate<CollectionVisibilityContext> visibilityExpression) : CollectionConfigBuilder<TEntityType>

Sets the runtime visibility of the collection.

// Example
collectionConfig.SetVisibility(ctx => ctx.UserRoles.Any(x => x.Alias == "editor"));

Changing a collection connection string

By default, Umbraco UI Builder will use the Umbraco connection string for its database connection. However, you can change this by calling the SetConnectionString method on a Collection config builder instance.

SetConnectionString(string connectionStringName) : CollectionConfigBuilder<TEntityType>

Sets the connection string name for the given collection repository.

// Example
collectionConfig.SetConnectionString("myConnectionStringName");

Actions are a powerful way of adding custom functionality to Umbraco UI Builder without needing to create custom UI elements. By providing an action to run, Umbraco UI Builder can automatically trigger actions from a number of UI locations.

Defining an action

To define an action create a class that inherits from the base class Action<> and configure it like below:

// Example
public class MyAction : Action<ActionResult>
{
    public override string Icon => "icon-settings";
    public override string Alias => "myaction";
    public override string Name => "My Action";
    public override bool ConfirmAction => true;

    public override ActionResult Execute(string collectionAlias, object[] entityIds)
    {
        // Perform operation here...
    }
}

The required configuration options are:

• Name: The name of the action.

• Alias: A unique alias for the action.

• Icon: An icon to display next to the name in the action button.

• Execute: The method to run against a given list of entities.

Additional optional configuration options are:

• ConfirmAction: Set whether a confirm dialog should display before performing this action.

The generic argument is a return type for the action. See Controlling the action result below.

Controlling the action result

Actions by default will return a ActionResult but you can return other types of result by swapping the Action<> generic argument.

• ActionResult - Standard result with a boolean Success value.

• FileActionResult - Returns a file stream / bytes and triggers a download dialog.

Capturing settings for an action

Sometimes you may need to collect further user input before you can perform an action. To achieve this you can use the Action<> base class that accepts an additional TSetting generic argument.

// Example
public class MyAction : Action<MyBulkdActionSettings, ActionResult>
{
    public override string Icon => "icon-settings";
    public override string Alias => "myaction";
    public override string Name => "My Action";
    public override bool ConfirmAction => true;

    public override void Configure(SettingsConfigBuilder<MyActionSettings> settingsConfig)
    {
        settingsConfig.AddFielset("General", fieldsetConfig => fieldsetConfig
            .AddField(s => s.RecipientName).SetLabel("Recipient Name")
            .AddField(s => s.RecipientEmail).SetLabel("Recipient Email"))
    }

    public override ActionResult Execute(string collectionAlias, object[] entityIds, MyActionSettings settings)
    {
        // Perform operation here...
    }
}

public class MyActionSettings
{
    public string RecipientName { get; set; }
    public string RecipientEmail { get; set; }
}

By implementing this base class you are required to implement an additional Configure method which accepts a SettingsConfigBuilder<> parameter. You should use this parameter calling the builders fluent API to define the settings dialog UI and how it maps to the settings type. With the settings config builder you are able to create fieldsets and fields with the same fluent API as defined in the Collection Editors section.

In addition to this Configure method, the Execute method will now accept an additional settings parameter of the settings type. This will be pre-populated by Umbraco UI Builder with the value entered by the user, allowing you to alter your actions behavior accordingly.

Adding an action to a collection

Actions are added via the Collections configuration.

AddAction<TMenuActionType>() : CollectionConfigBuilder<TEntityType>

Adds an action of the given type to the collection.

// Example
collectionConfig.AddAction<ExportMenuAction>();

AddAction(Type actionType) : CollectionConfigBuilder<TEntityType>

Adds an action of the given type to the collection.

// Example
collectionConfig.AddAction(actionType);

AddAction(IAction action) : CollectionConfigBuilder<TEntityType>

Adds the given action to the collection.

// Example
collectionConfig.AddAction(action);

Custom cards allow you to perform more complex metric calculations and are defined via a class implementing the Card base class.

When Umbraco UI Builder resolves a card it will attempt to do so from the global DI container. This means you can inject any dependencies that you require for your card to calculate its value. If there is no type defined in the DI container, Umbraco UI Builder will fall-back to manually instantiating a new instance of value mapper.

Defining a custom card

To define a card you create a class that inherits from the base class Card and configure it within the constructor like so.

// Example
public class AvgPersonAgeCard : Card
{
    public override string Alias => "avgPersonAge";
    public override string Name => "Average Age";
    public override string Icon => "icon-calendar";
    public override string Color => "green";
    public override string Suffix => "yrs";
        
    public override object GetValue(object parentId = null)
    {
        // Perform value calculation logic
    }
}

The required configuration options are:

• Name: The name of the card.

• Alias: A unique alias for the card.

• GetValue(object parentId = null): A method to get the cards value.

Additional optional configuration options are:

• Icon: An icon to display in the card.

• Color: The color of the card.

• Suffix: A suffix to display after the card value.

Adding a custom card to a collection

AddCard() : CollectionConfigBuilder<TEntityType>

Adds a card of the given type to the collection.

// Example
collectionConfig.AddCard<AvgPersonAgeCard>();

AddCard(Type cardType) : CollectionConfigBuilder<TEntityType>

Adds a card of the given type to the collection.

// Example
collectionConfig.AddCard(typeof(AvgPersonAgeCard));

Umbraco UI Builder comes with some inbuilt actions that are available for you to use straight away.

ExportEntityAction

Namespace Umbraco.UIBuilder.Infrastructure.Configuration.Actions

Provides a Comma-Separated Values (CSV) export functionality converting all properties to column headings and rendering each entity property values on each row.

ImportEntityAction

Namespace Umbraco.UIBuilder.Infrastructure.Configuration.Actions

Provides a Comma-Separated Values (CSV) import functionality matching column headings with entity properties and mapping row values to an entity.

Data views allow you to define multiple, pre-filtered views of the same data source. This can be useful when entities exist in different states and you want a way to toggle between them.

Defining data views

Data views are defined via the collections configuration.

AddDataView(string name, Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

Adds a data view with the given name and where clause filter expression. Expression must be a boolean expression.

// Example
collectionConfig.AddDataView("Active", p => p.IsActive);

AddDataView(string group, string name, Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

Adds a data view with the given group, name and where clause filter expression. Expression must be a boolean expression.

// Example
collectionConfig.AddDataView("Status", "Active", p => p.IsActive);

Searchable properties allow you to define any String based properties in a model. It can be searched via Umbraco UI Builder's list view and entity picker search controls.

Both direct String properties and String properties within nested objects can be made searchable, provided the parent object is not null.

Defining Searchable Properties

Using AddSearchableProperty() Method

Use AddSearchableProperty to specify which properties should be included in search functionality.

Method Syntax

AddSearchableProperty(Lambda searchablePropertyExpression) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddSearchableProperty(p => p.FirstName);
collectionConfig.AddSearchableProperty(p => p.Address.Street);

Search Expression Pattern

The search behavior differs based on the version:

• Up to version 15.0.1: Search uses the StartsWith method, meaning results include entries that begin with the search term.

• Version 15.0.1 and later: Search can be configured to use Contains, allowing results that include the search term anywhere within the property value.

Example

collectionConfig.AddSearchableProperty(p => p.FirstName); // will search for keywords that start with.
collectionConfig.AddSearchableProperty(p => p.FirstName, )SearchExpressionPattern.Contains); // will search for keywords that are contained.

Related collections add support for editing many-to-many relationships with UI Builder. These are found when multiple entities from one collection are associated with multiple entities from another. They are modeled in a database via two tables related to a junction table.

A classic example is with Students and Courses. Each course has many students, and each student takes many courses.

Collections Representation

A representation of your collections would look like this:

And the entities would be represented using the following Models:

[TableName("Students")]
[PrimaryKey("Id")]
public class Student
{
    [PrimaryKeyColumn]
    public int Id { get; set; }

    public string FirstName { get; set; }

    public string LastName { get; set; }

    public string Email { get; set; }
}

[TableName("Courses")]
[PrimaryKey("Id")]
public class Course
{
    [PrimaryKeyColumn]
    public int Id { get; set; }

    public string Title { get; set; }

    public string Description { get; set; }
}

[TableName("StudentsCourses")]
[PrimaryKey(new[] { "StudentId", "CourseId" })]
public class StudentCourse
{
    [PrimaryKeyColumn]
    public int StudentId { get; set; }

    [PrimaryKeyColumn]
    public int CourseId { get; set; }
}

Defining a related collection

You can get started with related collection through a two step process:

1. Add collection definition

2. Add related collection entity picker and definition

Collection definition

Define a related collection by calling the AddRelatedCollection method on a given collection config builder instance.

AddRelatedCollection<TEntityType, TRelatedEntityType, TJunctionEntityType>(Expression<Func<TRelatedEntityType, object>> idPropertyExpression, string nameSingular, string namePlural, Action<RelationConfigBuilder<TBuilder, TEntity, TRelatedEntityType, TJunctionEntityType>> relationConfig)

Adds a related collection to the current collection with the given names, descriptions, and default icons. A property accessor expression is required for the entity ID field of the entity. The relation configuration will define the junction entity by specifying the references to parent and child entities.

collectionConfig.AddRelatedCollection<Student, Course, StudentCourse>(x => x.Id, "Student Course", "Students Courses", relationConfig =>
{
    relationConfig
        .SetAlias("studentsCourses")
        .SetJunction<StudentCourse>(x => x.StudentId, y => y.CourseId);
});

Configuring a related collection entity picker

Define the child collection entity picker by calling the AddRelatedCollectionPickerField method on the parent collection fieldset config.

AddRelatedCollectionPickerField<TValueType>(string alias, string dataTypeName, string label)

Adds an entity picker with the specified Data Type name to the editor of the parent collection.

collectionConfig.Editor(editorConfig =>
{
    editorConfig.AddTab("General", tabConfig =>
        tabConfig.AddFieldset("General", fieldsetConfig =>
        {
            fieldsetConfig.AddField(x => x.FirstName).MakeRequired();
            fieldsetConfig.AddField(x => x.LastName).MakeRequired();
            fieldsetConfig.AddField(x => x.Email).MakeRequired();

            fieldsetConfig.AddRelatedCollectionPickerField<Course>("studentsCourses", "Courses Related Picker", "Courses");
        }));
});

Defining repository methods

IEnumerable GetRelationsByParentIdImpl(int parentId, string relationAlias)

Retrieves the related collections based on the ID of the parent entity.

{
    var db = _scopeProvider.CreateScope().Database;
    var sql = db.SqlContext.Sql()
            .Select(new[] { "StudentId", "CourseId" } )
            .From("StudentsCourses")
            .Where($"studentId = @0", parentId);

    var result = db.Fetch<StudentCourse>(sql);

    return result;
}

StudentCourse SaveRelationImpl(StudentCourse entity)

Adds a new related collection to the current parent entity.

{
    var db = _scopeProvider.CreateScope().Database;

    var type = entity.GetType();
    var studentId = type.GetProperty("StudentId").GetValue(entity);
    var courseId = type.GetProperty("CourseId").GetValue(entity);

    // delete relation if exists
    db.Execute("DELETE FROM StudentsCourses WHERE StudentId = @0 AND CourseId = @1",
        studentId,
        courseId);

    db.Execute("INSERT INTO StudentsCourses (StudentId, CourseId) VALUES (@0, @1)",
        studentId,
        courseId);

    return entity;
}

Umbraco UI Builder can dynamically build a filter dialog choosing appropriate editor views for you based on a basic property configuration. Properties of a number or date types will become range pickers and enums. Properties with options defined will become select/checkbox lists and all other properties will become text input filters.

Defining filterable properties

Defining filterable properties is controlled via the collections configuration.

AddFilterableProperty(Lambda filterablePropertyExpression, Lambda filterConfig = null) : CollectionConfigBuilder<TEntityType>

Adds the given property to the filterable properties collection.

// Example
collectionConfig.AddFilterableProperty(p => p.FirstName, filterConfig => filterConfig 
    // ...
);

Changing the label of a filterable property

SetLabel(string label) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.SetLabel("First Name");

Adding a description to a filterable property

SetDescription(string description) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.SetDescription("The first name of the person");

Defining basic options for a filterable property

SetOptions(IDictionary<TValueType, string> options) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.SetOptions(new Dictionary<string, string> {
    { "Option1", "Option One" },
    { "Option2", "Option Two" }
});

Defining options with custom compare clauses for a filterable property

AddOption(object key, string label, Lambda compareExpression) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.AddOption("Option1", "Option One", (val) => val != "Option Two");

Configuring the mode of a filterable property

For filterable properties with options you can configure whether the options should be multiple or single choice.

SetMode(FilterMode mode) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.SetMode(FilterMode.MultipleChoice);

Beyond searching there might be times when you need to be able to create specific views of a collection's data. To help with this Umbraco UI Builder has different filtering mechanisms available.

Choose a filtering method from the list below to find out more.

Actions provide an API to perform custom tasks against a collection and its entities from multiple locations in the UI. Examples: menu actions, bulk actions, or individual table row actions.

Get started with actions by learning about the basics.

As well as the API for managing your custom data source, Umbraco UI Builder also comes with some property editors. Those property editors help you work with your data inside Umbraco content nodes.

The property editors available are:

Cards provide an API to display basic summary information in a card-based format and are useful for displaying key metrics about a collection.

Cards can be defined in one of two ways:

A value mapper is an Umbraco UI Builder helper class that sits between the editor UI and the database. It also lets you tweak the stored value of a field. By default Umbraco UI Builder will save a datatype value as it would be stored in Umbraco. Value mappers let you change this.

When Umbraco UI Builder resolves a value mapper it will attempt to do so from the global DI container. This means you can inject any dependencies that you require for your mapper. If there is no type defined in the DI container, Umbraco UI Builder will fall-back to manually instantiating a new instance of value mapper.

Defining a value mapper

To define a mapper create a class that inherits from the base class ValueMapper and implements the methods EditorToModel and ModelToEditor.

Setting a field value mapper

Value mappers are defined as part of a collection editor field configuration.

SetValueMapper<TMapperType>() : EditorFieldConfigBuilder<TEntityType, TValueType>

Set the value mapper for the current field.

SetValueMapper(Type mapperType) : EditorFieldConfigBuilder<TEntityType, TValueType>

Set the value mapper for the current field.

SetValueMapper(Mapper mapper) : EditorFieldConfigBuilder<TEntityType, TValueType>

Set the value mapper for the current field.

If needed to collect sensitive information in a collection but don't want to persist in a plain text format to the data storage mechanism. Umbraco UI Builder can help with this by allowing you to define properties as encrypted. After which any time the value is persisted or retrieved from persistence, Umbraco UI Builder will automatically encrypt and decrypt the value.

Defining encrypted properties

AddEncryptedProperty(Lambda encryptedPropertyExpression) : CollectionConfigBuilder<TEntityType>

Adds the given property to the encrypted properties collection. Property must be of type String. When set, the property will be encrypted/decrypted on write/read respectively.

A summary dashboard appears automatically at the root of an Umbraco UI Builder section. It provides an overview of key collections within that section, enabling quick access to list views. Additionally, it allows for adding new entries to the collection, provided the collection is not set to read-only.

By summarizing important data and simplifying navigation, the summary dashboard improves content management efficiency.

Displaying a Collection on the Summary Dashboard

To display a collection on the summary dashboard, use the ShowOnSummaryDashboard() method in the collection configuration.

Configuration Example

Code Reference: ShowOnSummaryDashboard() : CollectionConfigBuilder<TEntityType>