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.

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.

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.

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

For a complete sample configuration, see the article.

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

Umbraco UI Builder provides property editors for managing data inside Umbraco content nodes.

The available property editors are:

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 article provides upgrade instructions for major versions of Umbraco UI Builder.

Upgrade to Version 14

Version 14 introduces breaking changes from the previous Konstrukt product. For full migration details, see the Migrate from Konstrukt to Umbraco UI Builder article.

Legacy Version Upgrade Notes

For out-of-support versions, see the Legacy documentation on GitHub.

Umbraco UI Builder allows encrypting properties to store sensitive information securely. When a property is marked as encrypted, its value is automatically encrypted before storage and decrypted upon retrieval.

Defining Encrypted Properties

Using the AddEncryptedProperty() Method

Encrypts the specified property. The property must be of type String. The value is encrypted before storage and decrypted when retrieved.

Method Syntax

AddEncryptedProperty(Lambda encryptedPropertyExpression) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddEncryptedProperty(p => p.Secret);

Field Views allow customization of the markup used by a field when displayed in a list view. Field Views are implemented as .NET Core View Components, which are passed a FieldViewsContext argument containing information about the entity/field being rendered.

Defining a Field View

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

Basic View File for the Built-In FieldView View Component

For field views, place a view file in the /Views/Shared/Components/FieldView folder with the following markup.

@model Umbraco.UIBuilder.Web.Models.FieldViewContext
<!-- Insert your markup here -->

WTo register the view, pass the name of the view file (excluding the .cshtml file extension) to the relevant API method.

Custom View Component

For more complex field views, create a custom view component class that can use dependency injection for any required dependencies. Use the following signature:

// Example
public class MyComplexFieldViewViewComponent : ViewComponent
{
    public async Task<IViewComponentResult> InvokeAsync(FieldViewContext context)
    {
        // Do your custom logic here

        return View("Default", model);
    }
}

For the view component, place a Default.cshtml file into the /Views/Shared/Components/MyComplexFieldView folder with the following markup:

@model Namespace.Of.Model.Returned.By.Custom.ViewComponent
<!-- Insert your markup here -->

The Field View Context

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

public class FieldViewContext
{
    public string ViewName { get; set; }
    public object Entity { get; set; }
    public string PropertyName { get; set; }
    public object PropertyValue { get; set; }
}

Setting the Field View of a List View Field

A field view is assigned to a list view field as part of the list view configuration. For more information, see the List Views article.

Use global filters to work with a specific subset of data within a collection. These filters apply to all queries for a given collection.

Applying a Global Filter

Configure global filters in the Collections settings.

Using the SetFilter() Method

Defines a filter using a where clause expression. The expression must return a boolean value.

Method Syntax

SetFilter(Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

Example

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

Umbraco UI Builder provides different inbuilt actions that you can use right away.

ExportEntityAction

Namespace: Umbraco.UIBuilder.Infrastructure.Configuration.Actions

Exports entity data to a Comma-Separated Values (CSV) file. It converts all properties into column headings and renders each entity's property values in rows.

ImportEntityAction

Namespace: Umbraco.UIBuilder.Infrastructure.Configuration.Actions

Imports data from a Comma-Separated Values (CSV) file. This action matches column headings with entity properties and maps row values to an entity.

Fluent Conventions

Umbraco UI Builder follows a fluent configuration style, allowing method chaining for concise and readable code. Alternatively, a lambda expression can be used for a more structured approach.

Chaining Example

config.AddSection("Repositories")
      .Tree()
      .AddCollection<People>(p => p.Id, "Person", "People");

Lambda Expression Example Example

config.AddSection("Repositories", sectionConfig => {  
    sectionConfig.Tree(treeConfig => {  
        treeConfig.AddCollection<People>(p => p.Id, "Person", "People");  
    });  
});

Naming Conventions

• Methods prefixed with Add allow multiple configurations.

• Methods prefixed with Set permit only one instance within the current configuration context.

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

collectionConfig.ShowOnSummaryDashboard();

Code Reference: ShowOnSummaryDashboard() : CollectionConfigBuilder<TEntityType>

A collection in Umbraco UI Builder represents a group of entities for a specific data model. It serves as the primary configuration object for defining how the collection integrates into the UI.

You can configure its list view appearance and editing options.

Get started by reviewing the basics of collection configuration.

Cards provide an API to display summary information in a card-based format, which is useful for displaying key metrics about a collection.

Cards can be defined in two ways:

A child collection is a container for data models that are tied to a parent collection. The child collection system shares the Collections API, offering flexibility for managing and displaying related data within your backoffice UI.

By default, child collections are displayed as context apps within the parent model's editor view. If multiple child collections lead to an overcrowded context apps area, consider using the Child Collection Groups API. Using the API, you can group related child collections under a single context app, with each child collection appearing in separate tabs.

Defining a Child Collection

To define a child collection, use the AddChildCollection method on the given collection config builder instance.

Using the AddChildCollection() Method

This method adds a child collection with the specified names, description, and default icons. Both the entity ID and foreign key fields must be specified using property accessor expressions.

Method Syntax

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

Example

collectionConfig.AddChildCollection<Child>(c => c.Id, c => c.ParentId, "Child", "Children", "A collection of children", childCollectionConfig => {
    ...
});

Using the AddChildCollection() Method with Custom Icons

This method adds a child collection to the current collection with the specified names, description and custom icons. Both the entity ID and foreign key fields must be specified using property accessor expressions.

Method Syntax

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

Example

collectionConfig.AddChildCollection<Child>(c => c.Id, c => c.ParentId, "Child", "Children", "A collection of children", "icon-umb-users", "icon-umb-users", childCollectionConfig => {
    ...
});

Configuring a Child Collection

Child collections share the same API as the Collection config builder API, except child collections cannot contain further child collections. For more information, see the Basics article.

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

Defining Data Views

Data views are defined via the Collections settings.

Using the AddDataView() Method

Creates a data view with the specified name and a where clause filter expression. The expression must return a boolean value.

Method Syntax

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

Example

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

Using the AddDataView() Method with Group

Creates a data view within a specified group, using a where clause filter expression. The expression must return a boolean value.

Method Syntax

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

Example

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

Using the AddAllDataView Method

Enables the All option for data views in the collection. The method can take an empty string, which will display the CMS localized All value, plain text, or a localized string.

Method Synthax

collectionConfig.AddAllDataView(string? label)

In addition to Searching, you may need to create specific views of a collection's data. Umbraco UI Builder provides multiple filtering mechanisms to help with this.

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

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 .

Defining a Folder

To define a folder, use one of the AddFolder methods on a 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

Example

Using the AddFolder() Method with Custom Icon

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

Method Syntax

Example

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

Example

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

Example

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

Example

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

Example

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

Method Syntax

Example

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

Method Syntax

Example

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:

For a class library without UI elements, install:

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:

Installing a License

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

Umbraco stores identifiers in UDI format for most Umbraco object types.

You can read more about them in the section of the documentation.

If you want to reference an Umbraco object in your model and retrieve its Integer or Guid value, you must convert the UDI value.

Use one of UI Builder's converters - EntityIdentifierToIntTypeConverter or EntityIdentifierToGuidTypeConverter. Add it as a [TypeConverterAttribute] to your model's foreign key property.

An entity that references an Umbraco object would look like this:

You can also create a custom type converter. UI Builder will handle data persistence automatically.

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

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

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

• : 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.

Actions allow you to perform custom tasks on collections and their entities from different areas in the UI. For Example: menu actions, bulk actions, or individual table row actions.

To get started with actions, check out the basics:

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.

Using the AddChildCollectionGroup() Method

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

Method Syntax

Example

Using the AddChildCollectionGroup() Method with Custom Icon

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

Method Syntax

Example

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 .

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 Workspace View 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.

The Entity Picker property editor allows selecting one or more entities from an Umbraco UI Builder collection.

Configuring an Entity Picker

To configure an entity picker, follow these steps:

1. Go to the Settings section in the Umbraco backoffice.

2. Create a New Data Type.

3. Select UI Builder Entity Picker from the Property Editor field.

1. Enter a Name for the picker and click Save.

2. Select the Section the collection is located in.

3. Select the Collection to pick the entities from.

4. [Optional] Select a list view Data View, if configured.

5. Enter a Minimum number of items and Maximum number of items that can be selected.

6. Click Save.

After defining the entity picker Data Type, add it to the desired Document Type.

Using an Entity Picker

The entity picker functions similarly to the content picker.

To pick an entity, follow these steps:

1. Go to the Document Type where the entity picker Data Type is added.

2. Click Add to open the picker dialog, displaying a paginated list of entities.

3. [Optional] If searchable fields are configured, use the search input field to filter results.

1. Click on the entity names.

2. Click Submit. The picker displays a summary of selected entities, which can be reordered by dragging them.

3. Click Save or Save and publish to save the changes.

Retrieving the Value of an Entity Picker

The entity picker property editor includes a built-in . Retrieving the property value from Umbraco returns the selected entities, converting them to the relevant type.

Umbraco UI Builder dynamically constructs a filter dialog by choosing appropriate editor views based on basic property configurations. Properties of numeric or date types become range pickers, enums become select/checkbox lists, and other properties are text input filters.

Defining Filterable Properties

Defining filterable properties is controlled via the settings.

Using the AddFilterableProperty() Method

Adds a given property to the filterable properties collection.

Method Syntax

Example

Changing the Label of a Filterable Property

Using the SetLabel() Method

Sets the label for the filterable property.

Method Syntax

Example

Adding a Description to a Filterable Property

Using the SetDescription() Method

Sets a description for the filterable property.

Method Syntax

Example

Defining Basic Options for a Filterable Property

Using the SetOptions() Method

Defines basic options for a filterable property.

Method Syntax

Example

Defining Options with Custom Compare Clauses for a Filterable Property

Using the AddOption() Method

Defines options with custom comparison clauses for a filterable property.

Method Syntax

Example

Configuring the Mode of a Filterable Property

For filterable properties with options, you can configure whether the options should allow multiple or single selections.

Using the SetMode() Method

Configures the mode of a filterable property (multiple or single choice).

Method Syntax

Example

Data views builders allow you to create a collection’s data views dynamically at runtime. By default, Umbraco UI Builder uses hard-coded data views from the configuration. However, if you need to generate data views dynamically, a data views builder is required.

When resolving a data views builder, Umbraco UI Builder first attempts to retrieve it from the global Dependency Injection (DI) container. This allows injecting required dependencies into the builder. If no type is defined in the DI container, Umbraco UI Builder falls back to manually instantiating a new instance of the value mapper.

Defining a Data Views Builder

To define a data views builder, create a class that inherits from DataViewsBuilder<TEntityType> and implements the required 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 settings.

Using the SetDataViewsBuilder() Method

Sets the collection's data views builder, allowing you to define data views dynamically at runtime.

Method Syntax

SetDataViewsBuilder<TDataViewsBuilder>() : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.SetDataViewsBuilder<PersonDataViewsBuilder>();

Using the SetDataViewsBuilder(Type) Method

Sets the collection's data views builder, allowing you to define data views dynamically at runtime.

Method Syntax

SetDataViewsBuilder(Type dataViewsBuilderType) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.SetDataViewsBuilder(typeof(PersonDataViewsBuilder));

Using the SetDataViewsBuilder(DataViewsBuilder<TEntityType>) Method

Sets the collection's data views builder, allowing you to define data views dynamically at runtime.

Method Syntax

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

Example

collectionConfig.SetDataViewsBuilder(new PersonDataViewsBuilder());

Custom cards enable more complex metric calculations and are defined by a class that implements the Card base class.

When Umbraco UI Builder resolves a card, it tries to do so from the global DI container. This means you can inject any dependencies required for the card's value calculation. If no type is found in the DI container, Umbraco UI Builder will fall back to manually instantiating a new instance of the value mapper.

Defining a Custom Card

To define a custom card, create a class that inherits from the base class Card and configure it in the constructor as shown below:

// 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
    }
}

Configuration Options

Adding a Custom Card to a Collection

Using the AddCard() Method

Adds a custom card of the specified type to the collection.

Method Syntax

AddCard() : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddCard<AvgPersonAgeCard>();

Using the AddCard(Type cardType) Method

Adds a custom card of the specified type to the collection, using the Type parameter to pass the card type dynamically.

Method Syntax

AddCard(Type cardType) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddCard(typeof(AvgPersonAgeCard));

Count cards allow you to define cards directly against the Collection configuration, providing a basic where clause to use in a count SQL statement. These work perfectly for basic data visualizations based on counts of entities in a collection.

If you need to do more than a basic count, see the Custom Cards article.

Adding a Count Card to a Collection

Count cards display basic summaries of key information that may be useful to the editor.

Using the AddCard() Method

Adds a count card with the specified name and a where clause filter expression. The filter expression must be a boolean value.

Method Syntax

AddCard(string name, Lambda whereClauseExpression, Lambda cardConfig = null) : CardConfigBuilder

Example

collectionConfig.AddCard("Older than 30", p => p.Age > 30, cardConfig => {
    ...
});

Using the AddCard() Method with Icon

Adds a count card with the specified name, an icon, and a where clause filter expression. The filter expression must be a boolean value.

Method Syntax

AddCard(string name, string icon, Lambda whereClauseExpression, Lambda cardConfig = null) : CardConfigBuilder

Example

collectionConfig.AddCard("Older than 30", "icon-umb-users", p => p.Age > 30, cardConfig => {
    ...
});

Change the Color of a Count Card

Using the SetColor() Method

Sets the color for the count card.

Method Syntax

SetColor(string color) : CardConfigBuilder

Example

cardConfig.SetColor("blue");

Add a Suffix to a Count Value

Using the SetSuffix() Method

Sets a suffix to be displayed alongside the card value.d

Method Syntax

SetSuffix(string suffix) : CardConfigBuilder

Example

cardConfig.SetSuffix("years");

Formatting the Value of a Count

Using the SetFormat() Method

Sets a custom format for the card's value.

Method Syntax

SetFormat(Lambda formatExpression) : CardConfigBuilder

Example

cardConfig.SetFormat((v) => $"{v}%");

Value mappers in Umbraco UI Builder act as intermediaries between the editor UI and the database, allowing customization of stored field values. By default, Umbraco UI Builder saves data as it would be stored in Umbraco, but value mappers enable modifications.

When resolving a value mapper, Umbraco UI Builder first checks the global DI container. If no type is defined, it manually instantiates a new instance.

Defining a Value Mapper

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

Example

public class MyValueMapper : ValueMapper
{
    public override object EditorToModel(object input)
    {
        // Tweak the input and return mapped object
        ...
    }

    public override object ModelToEditor(object input)
    {
        // Tweak the input and return mapped object
        ...
    }    
}

Setting a Field Value Mapper

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

Using the SetValueMapper() Method

Set the value mapper for the current field.

Method Syntax

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

Example

fieldConfig.SetValueMapper<MyValueMapper>();

Using the SetValueMapper(Type mapperType) Method

Set the value mapper for the current field using a type reference.

Method Syntax

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

Example

fieldConfig.SetValueMapper(typeof(MyValueMapper));

Using the SetValueMapper(Mapper mapper) Method

Set the value mapper for the current field using an instance.

Method Syntax

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

Example

fieldConfig.SetValueMapper(new MyValueMapper());

In one-to-many relationships, a parent entity is associated with multiple entities from another collection. In Umbraco UI Builder, retrieving child collections from such relationships is supported through child repositories. This enables you to access related data effectively, helping to maintain a well-organized backoffice UI.

Models Representation

For a one-to-many relationship, you typically have two models: one for the parent entity and one for the child entity.

[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; }
}

In the above example, the Student model represents the parent entity. A student can have multiple associated StudentProjects.

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

    public string Name { get; set; }

    public int StudentId { get; set; }
}

The StudentProjects model represents the child entity. The StudentId is a foreign key that links each StudentProject to the Student entity, establishing the one-to-many relationship.

Child Repositories

To retrieve data from child collections, you can use the IRepositoryFactory to create child repository instances. These repositories provide methods to fetch child entities associated with a given parent entity.

public class StudentProjectController : Controller
{
    private readonly IRepositoryFactory _repositoryFactory;

    public StudentProjectController(IRepositoryFactory repositoryFactory)
    {
        _repositoryFactory = repositoryFactory;
    }

    public IActionResult Index(int projectId)
    {
        var childRepository = _repositoryFactory.GetChildRepository<int, StudentProject, int>(projectId);

        var list = childRepository.GetAll();

        var count = childRepository.GetCount();

        var listPaged = childRepository.GetPaged();

        return View(list);
    }
}

In this example:

• The StudentProjectController is using the IRepositoryFactory to create a child repository for StudentProject.

• The GetAll()method retrieves all child entities related to the given parent.

• The GetCount() method returns the total number of child entities associated with the parent.

• The GetPaged() method allows for pagination of child entities, making it easier to manage large sets of data.

This structure allows efficient retrieval and management of child entities, providing a well-organized way to interact with related data in Umbraco's backoffice.

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, detailing all changes in this version.

16.0.0 (June 12th 2025)

• Upgraded to run on Umbraco version 16.

Legacy Release Notes

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

A list view displays a collection entity in a list format and includes features like pagination, custom data views, searching, and bulk actions.

Configuring a List View

The list view configuration is a sub-configuration of a Collection config builder instance and can be accessed via the ListView method.

Using the ListView() Method

Accesses the list view configuration for the specified collection.

Method Syntax

ListView(Lambda listViewConfig = null) : ListViewConfigBuilder<TEntityType>

Example

collectionConfig.ListView(listViewConfig => {
    ...
});

Adding a Field to the List View

Using the AddField() Method

Adds a specified property to the list view.

Method Syntax

AddField(Lambda propertyExpression, Lambda fieldConfig = null) : ListViewFieldConfigBuilder<TEntityType, TValueType>

Example

listViewConfig.AddField(p => p.FirstName, fieldConfig => {
    ...
});

Changing the Heading of a Field

Using the SetHeading() Method

Sets the heading for a field in the list view.

Method Syntax

SetHeading(string heading) : ListViewFieldConfigBuilder<TEntityType, TValueType>

Example

fieldConfig.SetHeading("First Name");

Formatting the Value of a Field

Using the SetFormat() Method

Sets the format expression to the field in the list view.

Method Syntax

SetFormat(Lambda formatExpression) : ListViewFieldConfigBuilder<TEntityType, TValueType>

Example

fieldConfig.SetFormat((v, p) => $"{v} years old");

Setting the View of a Field

You can customize the field's markup with field views, allowing richer visualizations of the content. For more details, see the Field Views article.

Using the SetView() Method

Sets the view component for the list view field.

Method Syntax

SetView(string viewComponentName) : ListViewFieldConfigBuilder<TEntityType, TValueType>

Example

fieldConfig.SetView("ImageFieldView");

Using the SetView<TView>() Method

Sets the view component for the list view field.

Method Syntax

SetView<TView>() : ListViewFieldConfigBuilder<TEntityType, TValueType>

Example

fieldConfig.SetView<ImageFieldView>();

Setting the Visibility of a Field

Using the SetVisibility() Method

Controls the runtime visibility of a field in the list view.

Method Syntax

SetVisibility(Predicate<ListViewFieldVisibilityContext> visibilityExpression) : ListViewFieldConfigBuilder<TEntityType, TValueType>

Example

fieldConfig.SetVisibility(ctx => ctx.UserGroups.Any(x => x.Alias == "editor"));

Changing the Page Size

Using the SetPageSize Method

Sets the number of items per page for the list view.

Method Syntax

SetPageSize(int pageSize) : ListViewConfigBuilder<TEntityType>

Example

listViewConfig.SetPageSize(20);

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.

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 or a instance.

Using the AddDashboard() Method

Adds a dashboard with the specified name.

Method Syntax

Example

Using the AddDashboardBefore() Method

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

Method Syntax

Example

Using the AddDashboardAfter() Method

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

Method Syntax

Example

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

Example

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

Example

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

Method Syntax

Example

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

Method Syntax

Example

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 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, . 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:

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:

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

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

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.

Repositories in Umbraco UI Builder manage entity data storage. By default, collections use a built-in NPoco repository. To use a different storage strategy, define a custom repository implementation.

Defining a Repository

Create a class that inherits from Repository<TEntity, TId> and implements all abstract methods.

Changing the Repository Implementation of a Collection

Using the SetRepositoryType() Method

Assign a custom repository type to a collection.

Method Syntax

Example

Using the SetRepositoryType(Type repositoryType) Method

Sets the repository type dynamically to the given type for the current collection.

Method Syntax

Example

Accessing a Repository in Code

To help with accessing a repository (default or custom) Umbraco UI Builder has an IRepositoryFactory you can inject into your code base. This includes a couple of factory methods to create the repository instances for you. Repositories should only be created via the repository factory as there are some injected dependencies that can only be resolved by Umbraco UI Builder.

Using the GetRepository<TEntity, TId>() Method

Creates a repository for the given entity type. Umbraco UI Builder will search the configuration for the first section/collection with a configuration for the given entity type. Then it will use that as a repository configuration.

Method Syntax

Example

Using the GetRepository<TEntity, TId>(string collectionAlias) Method

Creates a repository for the given entity type from the collection with the given alias.

Method Syntax

Example

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

Update all Konstrukt references to their Umbraco UI Builder alternatives. Ensure you update any Views/Partials that also reference these. See the section for reference.

Step 3: Update Configuration

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

For multi-step configurations using Action or Card classes, update the config builders and base classes to their UI Builder alternatives as described in .

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.

Umbraco UI Builder triggers different notification events during operation, allowing customization of default behavior.

Registering Event Handlers

Umbraco UI Builder follows the for event registration.

Define a notification event handler for the target event:

Register the event handler in Program.cs:

Repository Events

Using the EntitySavingNotification()

Triggers when Save is called before persisting the entity. The notification contains an Entity property with Before and After values, providing access to the previous and updated entities. Modify the After entity to persist changes. If the Cancel property of the notification is set to true then the save operation will be canceled and no changes will be saved.

Example

Using the EntitySavedNotification()

Triggers when the repository Save method is called and after the entity has been persisted. The notification contains an Entity property with Before and After inner properties. These properties provide access to a copy of the previously persisted entity (or null if a new entity) and the updated entity that´s saved.

Example

Using the EntityDeletingNotification()

Triggers when the repository Delete method is called and before the entity is deleted. The notification contains an Entity property providing access to a copy of the entity about to be deleted. If the Cancel property of notification is set to true then the delete operation will be cancelled and entity won't be deleted.

Example

Using the EntityDeletedNotification()

Triggers when the repository Delete method is called and after the entity has been deleted. The notification contains an Entity property providing access to a copy of the entity that´s deleted.

Example

Using the SqlQueryBuildingNotification()

Triggers when the repository is preparing a SQL query. The notification contains the collection alias + type, the NPoco Sql<ISqlContext> object, and the where clause/order by clauses. These will be used to generate the SQL query.

Example

Using the SqlQueryBuiltNotification()

Triggers when the repository has repaired a SQL query. The notification contains the collection alias + type, the NPoco Sql<ISqlContext> object and the where clause/order by clauses that was used to generate the SQL query.

Example

Repository Events Validation

From version 15.1.0, complex server-side validation can be added to a collection using the CancelOperation method of the notification.

Example

Umbraco UI Builder requires aliases for different elements, such as sections, context apps, and dashboards. While aliases for elements defined in the UI Builder config are straightforward, finding aliases for existing Umbraco instances can be challenging. Below is a list of known aliases for reference.

Dashboard Aliases

Content

Media

Settings

Members

Workspace Views Aliases

Content

Media

Members

ContentTypes

Section Aliases

Tree Aliases

Actions allow you to add custom functionality to Umbraco UI Builder without creating custom UI elements. By providing an action to run, Umbraco UI Builder can trigger actions from different UI locations.

Defining an Action

To define an action, create a class that inherits from the base class Action<> and configure it as shown 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...
    }
}

Configuration Options

The generic argument specifies the return type for the action. For more details, see the Controlling the Action Result section below.

Controlling the Action Result

By default, actions return an ActionResult, but you can return other types by changing the Action<> generic argument.

• ActionResult - Standard result with a boolean Success value.

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

Capturing Settings for an Action

Sometimes, you need to collect user input before performing an action. You can achieve this by using the Action<> base class with an additional TSetting generic argument.

// Example
public class MyAction : Action<MyActionSettings, 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.AddFieldset("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 must also implement the Configure method which accepts a SettingsConfigBuilder<> parameter. Use this builder to define the settings dialog UI and how it maps to the settings type. You can create fieldsets and fields with the same fluent API as in the Collection Editors section.

Additionally, the Execute method now accepts an extra settings parameter, which Umbraco UI Builder will pre-populate with the user-entered values. You can adjust the action's behavior based on this data.

Adding an Action to a Collection

Actions are added via the Collections settings.

Using the AddAction<TMenuActionType>() Method

Adds an action of the specified type to the collection.

Method Syntax

AddAction<TMenuActionType>() : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddAction<ExportMenuAction>();

Using the AddAction(Type actionType) Method

Adds an action of the specified type to the collection.

Method Syntax

AddAction(Type actionType) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddAction(actionType);

Using the AddAction(IAction action) Method

Adds the given action to the collection.

Method Syntax

AddAction(IAction action) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddAction(action);

By default, actions are hidden in the UI. You must define when and where an action should appear. This can be done either at the action definition level or when registering it in the collection config.

Controlling Default Action Visibility

To define the default visibility of an action, override the IsVisible method of the Action<> base class.

// Example
public class MyAction : Action<ActionResult>
{
    ...
    public override bool IsVisible(ActionVisibilityContext ctx)
    {
        return ctx.ActionType == ActionType.Bulk 
            || ctx.ActionType == ActionType.Row;
    }
    ...
}

The IsVisible method receives an ActionVisibilityContext. You can use this context to decide whether the action should be displayed. Return true to show it, or false to hide it. For more information, see the Action visibility context section below.

Overriding Action Visibility

You can override an action's visibility in the Collections settings.

Using the AddAction<TMenuActionType>() Method

Adds an action of the given type to the collection with the specified visibility.

Method Syntax

AddAction<TMenuActionType>(Lambda actionConfig = null) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddAction<ExportMenuAction>(actionConfig => actionConfig
    .SetVisibility(x => x.ActionType == ActionType.Bulk 
        || x.ActionType == ActionType.Row)
);

Using the AddAction(Type actionType, Lambda actionConfig = null) Method

Adds an action of the given type to the collection by specifying the action type dynamically using Type instead of a generic type.

Method Syntax

AddAction(Type actionType, Lambda actionConfig = null) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddAction(typeof(ExportMenuAction), actionConfig => actionConfig
    .SetVisibility(x => x.ActionType == ActionType.Bulk 
        || x.ActionType == ActionType.Row)
);

Using the AddAction(IAction action, Lambda actionConfig = null) Method

Adds the already defined action instance to the collection with the specified visibility.

Method Syntax

AddAction(IAction action, Lambda actionConfig = null) : CollectionConfigBuilder<TEntityType>

Example

collectionConfig.AddAction(action, actionConfig => actionConfig
    .SetVisibility(x => x.ActionType == ActionType.Bulk 
        || x.ActionType == ActionType.Row)
);

Action Visibility Context

When controlling the visibility of an action, you will receive an ActionVisibilityContext object. This context allows you to decide whether to show the action. The context contains two key pieces of information for this decision.

ActionType

The ActionType property is an enum property that defines which area of the UI wants to access the action. This property helps determine where the action is displayed.

ContainerMenu

The ContainerMenu action type displays the action in both the collection tree and its list view actions menu.

EntityMenu

The EntityMenu action type shows the action in the collection editor UI's actions menu.

Bulk

The Bulk action type displays the action in the collection list view bulk actions menu.

Row

The Row action type shows the action in the collection list view action row menu.

Save

The Save action type displays the action as a sub-button in the entity editor’s save button. All Save actions trigger a save before executing. Their labels are prefixed with Save & [Action Name].

UserGroups

The UserGroups collection contains a list of IReadOnlyUserGroup objects for the current logged-in backoffice user. This allows you to control action visibility for members of specific user groups.

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

Example

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

Example

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

Example

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

Example

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

Method Syntax

Example

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

Method Syntax

Example

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

Method Syntax

Example

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

Method Syntax

Example

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

Example

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

Method Syntax

Example

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

Method Syntax

Example

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

Method Syntax

Example

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

Method Syntax

Example

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

Method Syntax

Example

Using the AddDashboardBefore() Method

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

Method Syntax

Example

Using the AddDashboardAfter() Method

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

Method Syntax

Example

Virtual subtrees inject an Umbraco UI Builder tree structure into another Umbraco tree at a specified location, acting as child nodes of the injection point. They extend built-in or third-party package trees with additional features. For example a "loyalty points" program for an e-commerce site can inject related database tables into a Commerce store tree, making management more intuitive.

Defining Virtual SubTrees

Use the AddVirtualSubTree methods of a instance to define a virtual subtree.

Using the AddVirtualSubTree() Method

Adds a virtual subtree to the current tree with visibility controlled by the specified expression.

Method Syntax

Example

Using the AddVirtualSubTreeBefore() Method

Adds a virtual subtree to the current tree before the tree node matches the match expression, with its visibility controlled by the specified expression.

Method Syntax

Example

Using the AddVirtualSubTreeAfter() Method

Adds a virtual subtree to the current tree after the tree node matches the match expression, with its visibility controlled by the specified expression.

Method Syntax

Example

Control the Virtual SubTrees Inject Location

Control the injection location by passing a visibility expression to the AddVirtualSubTree methods on the root UIBuilderConfigBuilder instance. Without a visibility expression, the subtree appears under every node in the target tree. This expression can be used to identify the exact location where the tree should go.

The visibility expression receives a VirtualSubTreeFilterContext argument with relevant contextual information. The information includes the current node being rendered, alongside a list of the current user's user groups for permission-based visibility control. It also includes access to an IServiceProvider for dependency resolution.

Example: Filter Injection by Document Type

Control the Position of the injected Virtual SubTrees

The position of a virtual subtree within the child nodes of the injection node is controlled by using one of the AddVirtualSubTreeBefore or AddVirtualSubTreeAfter methods. These methods need to be on the root level UIBuilderConfigBuilder instance. The match expression identifies the node for insertion. This expression passes a single TreeNode argument to determine the position. It also requires a boolean return value to indicate the relevant location has been found.

Below you can find an example of positioning a subtree after a node with the alias "settings":

Configuring a Virtual SubTree

Virtual subtrees use the Tree config builder API including support for folders and collections. There is an exception when adding collections to a subtree where you will have an additional foreign key expression parameter to define. The foreign key expression links the entities of the collection to the parent node of the subtree. For more information, see the article.

Inject Virtual Subtrees into Third-Party Trees

Out of the box, Umbraco UI Builder supports injecting subtrees into the core content, media, members, and member group trees. It also includes third-party support for settings and commerce trees. To inject into additional trees, implement an ITreeHelper to extract necessary data. The tree helper consists of a tree alias for which the tree helper is. It includes methods to correctly identify the full parent path, a unique ID for a given node ID, and to resolve the actual entity ID. The entity ID should be used for the foreign key collection values.

Once you have defined a tree helper, register the DI container in your startup class.

Once registered, any virtual subtree assigned to the helper’s tree alias will use it to locate required data.

Related collections support the editing of many-to-many relationships in UI Builder. These are used when multiple entities from one collection are linked to multiple entities from another collection, commonly represented through a junction table.

Example Use Case

A classic example is the relationship between Students and Courses, where each student takes many courses, and each course has many students.

Collections Representation

This is how the collections would be represented:

The models representing the entities would be as follows:

[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

To define a related collection, follow these two steps:

1. Add the collection definition

2. Add the related collection entity picker and definition

Collection definition

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

Using the AddRelatedCollection() Method

This method adds a related collection to the current collection, specifying names, descriptions, and default icons. The ID property must be defined, and the relation configuration defines the junction entity with references to parent and child entities.

Method Syntax

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

Example

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's fieldset config.

Using the AddRelatedCollectionPickerField() Method

This method adds an entity picker with the specified Data Type name to the parent collection editor.

Method Syntax

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

Example

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

Using the GetRelationsByParentIdImpl<>() Method

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

Method Syntax

IEnumerable<StudentCourse> GetRelationsByParentIdImpl<StudentCourse>(int parentId, string relationAlias)

Example

{
    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;
}

Using the SaveRelationImpl<>() Method

Adds a new related collection to the current parent entity.

Method Syntax

StudentCourse SaveRelationImpl<StudentCourse>(StudentCourse entity)

Example

{
    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;
}

Context Apps in Umbraco UI Builder function similarly to Workspace Views (previously called as 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 Workspace View.

Defining a Context App

You can define a context app by calling one of the AddContextApp methods on a WithTreeConfigBuilder instance.

Using the AddContextApp() Method

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

Method Syntax

AddContextApp(string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Example

withTreeConfig.AddContextApp("Comments", contextAppConfig => {
    ...
});

Using the AddContextApp() Method with Custom Icon

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

Method Syntax

AddContextApp(string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Example

withTreeConfig.AddContextApp("Comments", "icon-chat", contextAppConfig => {
    ...
});

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

AddContextAppBefore(string beforeAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Example

withTreeConfig.AddContextAppBefore("umbContent", "Comments", contextAppConfig => {
    ...
});

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

AddContextAppBefore(string beforeAlias, string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Example

withTreeConfig.AddContextAppBefore("umbContent", "Comments", "icon-chat", contextAppConfig => {
    ...
});

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

AddContextAppAfter(string afterAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Example

withTreeConfig.AddContextAppAfter("umbContent", "Comments", contextAppConfig => {
    ...
});

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

AddContextAppAfter(string afterAlias, string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Example

withTreeConfig.AddContextAppAfter("umbContent", "Comments", "icon-chat", contextAppConfig => {
    ...
});

Changing a Context App Alias