Umbraco UI Builder is installed via the NuGet package manager by issuing the following command in your web project.

dotnet add package Umbraco.UIBuilder

If you wish to install Umbraco UI Builder into a class library without the UI elements, you can add a reference to the Umbraco.UIBuilder.Startup package instead.

dotnet add package Umbraco.UIBuilder.Startup

Alternatively, you can also find and install the NuGet package via the NuGet Package Manager graphical user interface (GUI) in Visual Studio.

Installing a License

Umbraco UI Builder is the Umbraco v14+ backoffice UI builder for custom data structures configured via a fluent API.

If you have a custom data store that you want to content manage from within Umbraco, then you can use Umbraco UI Builder. With some 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 take a matter of minutes, rather than days.

Using the Documentation

This documentation is aimed at developers who have at least a basic understanding of Umbraco, as well as C#/MVC principles.

Use the main menu to dive deeper into Umbraco UI Builder and get to know all of its features in detail. You can then jump to the specific topic you are interested in to find out more.

Getting Help

If you require assistance you can use our support channels to seek assistance.

This page covers specific upgrade documentation for when migrating to major 14 of Umbraco UI Builder.

Version Specific Upgrade Notes History

Version 14 contains a number of breaking changes from the previous, Konstrukt product.

Legacy version specific upgrade notes

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

Release History

This section contains the release notes for Umbraco UI Builder 14 including all changes for this version.

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

• Filterable properties UI updates

• Added updates to the licensing engine.

• Fixed an error in the entity update action.

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

• Release major version of Umbraco.UIBuilder 14

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

Legacy release notes

Umbraco UI Builder can be configured directly via the AddUIBuilder extension method on IUmbracoBuilder.

AddUIBuilder

To configure Umbraco UI Builder via the AddUIBuilder extension method, You can look in the Program.cs file in the root of your web project. From within this file, before the call to AddComposers() we can add our AddUIBuilder configuration.

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddUIBuilder(cfg => {
                // Apply your configuration here
    })
    .AddDeliveryApi()
    .AddComposers()
    .Build();

The AddUIBuilder extension method accepts a single parameter, a delegate function with one of the Umbraco UI Builder configuration builder arguments. With this, you can then call the relevant fluent APIs to define your solution.

Umbraco UI Builder tries its best to mimic the content pipeline as closely as possible whilst sticking to public and supported APIs. This is so that the Data Type suite can be used fully for editing properties. There are some features in the Umbraco Core that are locked away in internal methods. This means that some features may not be fully supported. Below is a list of known issues to date.

Property Editors

Tags

Whilst we have support for persisting the tag's value, we don't currently have the ability to write these tags to the cmsTags DB table. This is all handled via a tagsRepository which is internal so we currently can't save to it as core does.

This guide provides a step-by-step approach to migrating a default Konstrukt solution to Umbraco UI Builder.

Key changes

Before outlining the exact steps, there are a few key changes to be aware of.

These changes will dictate the steps to take in the process of migrating to Umbraco UI Builder.

Project, Package, and Namespace changes

Step 1: Replace dependencies

In this first step, we will be replacing all existing Konstrukt dependencies with Umbraco UI Builder dependencies.

1. Remove any installed Konstrukt packages:

dotnet remove package Konstrukt

1. Delete the Konstrukt App_Plugins folder:

rmdir App_Plugins\Konstrukt

1. Install Umbraco.UIBuilder:

dotnet add package Umbraco.UIBuilder

1. Compile your project against .NET 7.0.

Step 2: Update namespaces and entity names

Step 3: Update your configuration

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .AddUIBuilder(cfg => {
        // The rest of your configuration
    })
    .Build();

Step 4: Finalizing the migration

1. Delete any obj/bin folders in your projects to ensure a clean build.

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

3. Delete the existing Konstrukt license files in the umbraco\Licenses folder.

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

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

1. Run the project.

This section will guide you through the key steps necessary to get you started with Umbraco UI Builder.

It is assumed that you have an Umbraco 10+ website configured, and ready to install Umbraco UI Builder.

System Requirements

At this time, the minimum requirements for using Umbraco UI Builder are as follows:

• Umbraco CMS version 10.0/12.0+

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

Versioning

There are different areas of the Umbraco UI that Umbraco UI Builder can be injected into. Before you get to managing your actual content you need to choose which area makes the most sense to present that data in. Then you can review how to go about configuring that particular type of area.

Choose an area type from the list below to find out more.

Get the latest version of Umbraco UI Builder

To upgrade to the latest version of Umbraco UI Builder you can use:

• NuGet

• Visual Studio

NuGet

• NuGet installs the latest version of the package when you use the dotnet add package Umbraco.UIBuilder command unless you specify a package version: dotnet add package Umbraco.UIBuilder --version <VERSION>

• After you have added a package reference to your project by executing the dotnet add package Umbraco.UIBuilder command in the directory that contains your project file, run dotnet restore to install the package.

Visual Studio

1. Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution... in Visual Studio, to upgrade Umbraco UI Builder:

2. Select Umbraco.UIBuilder.

3. Select the latest version from the Version drop-down and click Install.

4. When the command completes, open the .csproj file to make sure the package reference is updated:

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

If you are using one or more of the below sub-packages, they also need to be upgraded as well:

Umbraco UI Builder is a commercial product. You can run an Umbraco UI Builder unrestricted locally without the need a license. Running Umbraco UI Builder on a public domain will display a warning banner in the backoffice and will limit usage to a single editable collection. To remove these restrictions, you'll need to have a valid license.

How does it work?

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

Let's say that you have a license configured for your domain, mysite.com, and you've requested two development domains, devdomain.com and devdomain2.com.

The license will cover the following domains:

• localhost

• *.local

• *.mysite.com

• www.mysite.com

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What does a license cover?

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

• A single license covers the installation of Umbraco UI Builder in 1 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

Add additional domains

Installing your license

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

1. Open the root directory for your project files.

2. Locate and open the appSettings.json file.

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

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

"Umbraco_UIBuilder": "YOUR_LICENSE_KEY"

Verify the license installation

You can verify that your license is successfully installed by logging into your project's backoffice and navigating to the settings section. Here you will see a license dashboard which should display the status of your license.

Validating a license without an outgoing 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.

A section is a distinct area of the Umbraco backoffice, such as content, media, etc. The section is accessed via a link in the main menu at the top of the Umbraco interface. Umbraco UI Builder allows you to define multiple sections in order to organise the management of your models into logical sections.

Defining a section

You can define a section by calling one of the AddSection methods on the root level UIBuilderConfigBuilder instance.

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

Adds a section to the Umbraco menu with the given name.

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

Adds a section to the Umbraco menu with the given name before the section with the given alias.

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

Adds a section to the Umbraco menu with the given name after the section with the given alias.

Changing a section alias

SetAlias(string alias) : SectionConfigBuilder

Sets the alias of the section.

Optional: When adding a new section, 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.

Configuring the section tree

Tree(Lambda treeConfig = null) : TreeConfigBuilder

Adding a dashboard to the section

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

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

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

Extending an existing section

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.

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

Starts a sub-configuration for the existing Umbraco section with the given alias.

Adding a tree to an existing section

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

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

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

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

Adding a dashboard to an existing section

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

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

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

A tree is a hierarchical structure that helps organize a section into logical sub-sections. A tree is accessed in the main side panel of the Umbraco interface. In Umbraco UI Builder, a section may only have a single tree definition. However, you can use folder nodes to help organize the tree structure as you need it.

Configuring a Umbraco UI Builder section tree

Tree(Lambda treeConfig = null) : TreeConfigBuilder

Accesses the tree config of the given section.

Adding a tree to an existing section

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

Adds a tree to the current section.

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

Adds a tree to the current section in a group with the given name.

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

Adds a tree to the current section before the tree with the given alias.

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

Adds a tree to the current section after the tree with the given alias.

Changing the tree icon color

SetIconColor(string color) : TreeConfigBuilder

Sets the trees icon color to the given color. The options that are possible are black, green, yellow, orange, blue or red.

Adding a group to a tree

AddGroup(string name, Lambda groupConfig = null) : GroupConfigBuilder

Adds a group to the current tree with the given name.

Adding a folder to a tree/group

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

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

Adding a collection to a tree/group

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

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

Extending an existing tree

WithTree(string alias, Lambda treeConfig = null) : WithTreeConfigBuilder

Starts a sub-configuration for the existing Umbraco tree with the given alias.

Adding a context app to an existing tree

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

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

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

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

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

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

Defining a folder

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

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

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

Adds a folder to the current tree with the given name + icon.

Changing a folder alias

SetAlias(string alias) : FolderConfigBuilder

Sets the alias of the folder.

Optional: When creating a new folder, 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.

Changing a folder icon color

SetIconColor(string color) : FolderConfigBuilder

Sets the folder icon color to the given color. The options that are possible are black, green, yellow, orange, blue or red.

Adding a sub folder to a folder

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

Adds a sub folder to the current folder with the given name and a default folder icon.

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

Adds a sub folder to the current folder with the given name + icon.

Adding a collection to a folder

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

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

A summary dashboard is automatically displayed at the root of a defined Umbraco UI Builder section. It displays summaries of collections found within it that are told to display on the dashboard. It also provides quick links to jump to that collections list view. It can also add quickly a new entry to that collection (if the collection isn't read-only).

Showing a collection on a summary dashboard

Showing a collection in the summary dashboard is controlled via the collection configuration.

ShowOnSummaryDashboard() : CollectionConfigBuilder<TEntityType>

Sets the collection to display on the summary dashboard.

In this guide, you can find the necessary steps needed for a basic implementation using Umbraco UI Builder to manage a single custom database table.

Set up the database

Start by setting up a database table for your model (you might want to populate it with some dummy data as well while learning). We’ll use the following as an example:

Set up your model

With the database table setup, we then need to create the associated Poco model in our project.

Configure Umbraco UI Builder

With the database and model setup, we can now start to configure Umbraco UI Builder itself. The entry point for the Umbraco UI Builder configuration is via the AddUIBuilder extension method. On this method, we call on the IUmbracoBuilder instance within the Program.cs class.

For our example, we will use the following configuration:

Access your UI

With your configuration defined and your project compiled, there is one last step to perform before you can access your UI. And that is to give your backoffice user account permission to access the newly defined section. To do this you'll need to login to the backoffice, head to the user's section, and update the user group. There you will need to make sure that your user belongs to the allowed access.

With the permissions set, you can refresh your browser and you should now see your new section available in the site navigation.

Summary

As you can see, with little code you can start to create powerful interfaces for your custom data structures.

Before you get to know Umbraco UI Builder, you need to become familiar with the Umbraco UI and a few of its concepts. This is because Umbraco UI Builder reuses these same concepts for constructing its UI.

1. Section A distinct area of the Umbraco backoffice. 2. Tree A hierarchical structure to help organize a section. 3. Dashboard An intro screen for a section, usually with useful links for that section.

4. List View A list-based view of items in a tree node.

5. Editor The main content editing area is made up of tabs, fieldsets, and fields.

6. Context Apps A contextual section of a given editor UI. 7. Tabs A tabbed container of content.

8. Menu Item A context menu item + action.

9. Bulk Action An action to perform on multiple list view items at once.

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.

Context Apps in Umbraco UI Builder are analogous to Content Apps in Umbraco. They allow you to provide contextual apps that appear in the editor UI of content. From Umbraco UI Builder's perspective, defining context apps allows you to expose collections as content apps. This is where a collection has a relation to the content in question. An example could be something like blog post comments which are linked to individual blog posts. Exposing these as a content app allows them to be managed in context next to the blog post they are linked to.

Defining a context app

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

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

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

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

Adds a context app to the Umbraco menu with the given name and icon.

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

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

Adds a context app with the given name and default icon before the context app with the given alias.

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

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

Adds a context app to the Umbraco menu with the given name and icon before the context app with the given alias.

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

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

Adds a context app with the given name and default icon after the context app with the given alias.

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

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

Adds a context app to the Umbraco menu with the given name and icon after the context app with the given alias.

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

Changing a context app alias

SetAlias(string alias) : ContextAppConfigBuilder

Sets the alias of the context app.

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

// Example
contextAppConfig.SetAlias("comments");

Changing a context app icon color

SetIconColor(string color) : ContextAppConfigBuilder

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

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

Changing when a context app should display

Changing when a context app is displayed, is controlled by a delegate method which is passed 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 any value from those to return a boolean result which sets whether to display the context app or not.

By default, Umbraco UI Builder will pre-filter context apps to only display on the tree it is defined in. This will be combined with the SetVisibility config to decide when to display the context app.

SetVisibility(Func<ContextAppVisibilityContext, bool> visibilityExpression) : ContextAppConfigBuilder

Sets the context app visibility delegate.

// Example
contextAppConfig.SetVisibility(appCtx => appCtx.Source is IContent content && content.ContentType.Alias == "blogPost");

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.

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

// Example
contextAppConfig.AddCollection<Comment>(p => p.Id, p=> "Comment", "Comments", "A collection of comments", collectionConfig => {
    ...
});

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

// Example
contextAppConfig.AddCollection<Comment>(p => p.Id, "Comment", "Comments", "A collection of comments", "icon-chat", "icon-chat", collectionConfig => {
    ...
});

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

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>

// Example
collectionConfig.DisableDelete();

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

// 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");

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

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

A dashboard is a view that is displayed at the root of a section and contains welcome information. It also includes useful tools relevant to the given section. When there are multiple dashboards to display in a section these are presented in a tabbed layout to allow you to switch between the dashboards.

Defining a dashboard

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

Adds a dashboard with the given name.

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

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

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

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

Changing a dashboard alias

SetAlias(string alias) : DashboardConfigBuilder

Sets the alias of the dashboard.

Optional: When adding a new dashboard, 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.

Changing when a dashboard should display

Changing when a dashboard is displayed is controlled via an inner config. Options on the inner config are ShowForUserGroup and HideForUserGroup to control the visibility of the dashboard for given user groups. You can call these config methods multiple times to add multiple role configurations.

By default, will pre-filter dashboards to display only on the section it is defined in. This will be combined with the SetVisibility config to decide when to display the dashboard.

SetVisibility(Lambda visibilityConfig) : DashboardConfigBuilder

Sets the dashboard visibility config.

Setting the collection of a dashboard

Dashboards are only able to display a single collection. If you need to display multiple collections, then you need to configure multiple dashboards.

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

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

A list view is a list-based view of a collection entity providing features: pagination for large collections, custom data views, searching, and bulk actions.

Configuring a list view

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

Accesses the list view config of the given collection.

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

Adding a field to the list view

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

Adds the given property to the list view.

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

Changing the heading of a field

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

Sets the heading for the list view field.

// Example
fieldConfig.SetHeading("First Name");

Formatting the value of a field

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

Sets the format expression for the list view field.

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

Setting the view of a field

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

Sets the view component for the list view field.

// Example
fieldConfig.SetView("ImageFieldView");

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

Sets the view component for the list view field.

// Example
fieldConfig.SetView<ImageFieldView>();

Setting the visibility of a field

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

Sets the runtime visibility of the list view field.

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

Changing the page size

SetPageSize(int pageSize) : ListViewConfigBuilder<TEntityType>

Sets the number of items to display per page for the given list view.

// Example
listViewConfig.SetPageSize(20);

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.

// Example
collectionConfig.Editor(editorConfig => {
    ...
});

Adding a tab to an editor

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

Adds a tab to the editor.

// Example
editorConfig.AddTab("General", tabConfig => {
    ...
});

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.

// Example
tabConfig.Sidebar(sidebarConfig => {
    ...
});

Setting the visibility of a tab

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

Sets the runtime visibility of the tab.

// Example
tabConfig.SetVisibility(ctx => ctx.EditorMode == EditorMode.Create);

Adding a fieldset to a tab

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

Adds the given fieldset to the tab.

// Example
tabConfig.AddFieldset("Contact", fieldsetConfig => {
    ...
});

Setting the visibility of a fieldset

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

Sets the runtime visibility of the fieldset.

// Example
fieldsetConfig.SetVisibility(ctx => ctx.EditorMode == EditorMode.Create);

Adding a field to a fieldset

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

Adds the given property to the editor.

// Example
fieldsetConfig.AddField(p => p.FirstName, fieldConfig => {
    ...
});

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.

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

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.

// Example
fieldConfig.HideLabel();

Adding a description to a field

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

Sets the description for the editor field.

// Example
fieldConfig.SetDescription("Enter your age in years");

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.

// Example
fieldConfig.SetDataType("Richtext Editor");

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

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

// Example
fieldConfig.SetDataType(-88);

Setting the default value of a field

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

Sets the default value to a known constant.

// Example
fieldConfig.SetDefaultValue(10);

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

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

// Example
fieldConfig.SetDefaultValue(() => DateTime.Now);

Making a field required

MakeRequired() : EditorFieldConfigBuilder<TEntityType, TValueType>

Makes the given field required.

// Example
fieldConfig.MakeRequired();

Validating a field

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

Defines the regular expression to use when validating the field.

// Example
fieldConfig.SetValidationRegex("[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,4}");

Making a field read-only

MakeReadOnly() : EditorFieldConfigBuilder<TEntityType, TValueType>

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

// Example
fieldConfig.MakeReadOnly();

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.

// Example
fieldConfig.MakeReadOnly(distanceProp => $"{distanceProp:## 'km'}");

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.

// Example
fieldConfig.MakeReadOnly("myReadOnlyEditor");

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.

// Example
fieldConfig.MakeReadOnly(ctx => ctx.EditorMode == EditorMode.Create);

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.

// Example
fieldConfig.MakeReadOnly(ctx => ctx.EditorMode == EditorMode.Create, distanceProp => $"{distanceProp:## 'km'}");

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.

// Example
fieldConfig.MakeReadOnly(ctx => ctx.EditorMode == EditorMode.Create, "myReadOnlyEditor");

Setting the visibility of a field

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

Sets the runtime visibility of the field.

// Example
fieldConfig.SetVisibility(ctx => ctx.EditorMode == EditorMode.Create);

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:

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.

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.

Defining repository methods

IEnumerable GetRelationsByParentIdImpl(int parentId, string relationAlias)

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

StudentCourse SaveRelationImpl(StudentCourse entity)

Adds a new related collection to the current parent entity.

Beyond listing collection entities, if you need to be able to locate specific entities within a collection then Umbraco UI Builder provides a search API.

Get started by reviewing how to define searchable properties.

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.

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

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 on a model. They will be searchable via Umbraco UI Builder's list view and entity picker search controls.

You can also use any String based property of nested objects of a model, as long as the parent object is not null.

Defining searchable properties

AddSearchableProperty(Lambda searchablePropertyExpression) : CollectionConfigBuilder<TEntityType>

Adds the given property to the searchable properties collection.

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

Search Expression Pattern

Up to version 14.0.1, the search was performed using the StartsWith method call. From 14.0.1 and up, search operations can be performed using the Contains method call.

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

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.

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

SetDataViewsBuilder<TDataViewsBuilder>() : CollectionConfigBuilder<TEntityType>

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

SetDataViewsBuilder(Type dataViewsBuilderType) : CollectionConfigBuilder<TEntityType>

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

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

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

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

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.

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

SetFilter(Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

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

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

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.

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

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

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);

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.

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

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);

By default actions are not visible in the UI and you must expressly define when and where an action should display. This can be achieved in two ways, either on the action definition itself or at the point of registration on the collections config.

Controlling the default action visibility

To define the default visibility of an action at the action level you can do this by overriding 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;
    }
    ...
}

Overriding an actions visibility

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

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

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

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

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

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

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

Adds the given action to the collection with the given visibility.

// 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 be given a ActionVisibilityContext object from which you can decide whether to show the action or not. The visibility context contains two key pieces of information on which you can base this decision.

ActionType

The action type property is an enum property that define which area of the UI it is that wishes to access this action. Enabling an action to display for a given action type will determine where an action is displayed.

ContainerMenu

The ContainerMenu action type determines that the action will be displayed in both the tree of the collection and its list view actions menu.

EntityMenu

The EntityMenu action type determines that the action will be displayed in the actions menu of a collection editor UI.

Bulk

The Bulk action type determines that the action will be displayed in the collection list view bulk actions menu.

Row

The Row action type determines that the action will be displayed in the collection list view action row menu.

Save

The Save action type determines that the action will be displayed as a sub button in an entity editors save button. All Save action types trigger a save before the action is executed and so to convey this, all Save action type button labels are prefixed Save & [Action Name]

UserGroups

The user groups collection contains a list of Umbraco IReadOnlyUserGroup objects for the current logged-in backoffice user. This allows you to control the visibility of actions for given user group members.

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:

Adding a count card to a collection

Cards allow you to display basic summaries of key information that may be useful to the editor.

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

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

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

Adds a card with the given name + icon and where clause filter expression. Expression must be a boolean expression.

Change the color of a count card

SetColor(string color) : CardConfigBuilder

Sets the color of the card.

Add a suffix to a count value

SetSuffix(string suffix) : CardConfigBuilder

Sets the suffix of the card value.

Formatting the value of a count

SetFormat(Lambda formatExpression) : CardConfigBuilder

Sets the format expression for the card.

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.

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

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.

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

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

Set the value mapper for the current field.

// Example
fieldConfig.SetValueMapper<MyValueMapper>();

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

Set the value mapper for the current field.

// Example
fieldConfig.SetValueMapper(typeof(MyValueMapper));

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

Set the value mapper for the current field.

// Example
fieldConfig.SetValueMapper(new MyValueMapper());

Virtual subtrees are a powerful feature that allows you to inject an Umbraco UI Builder tree structure into another Umbraco tree at a desired location. Thus acting as child nodes to the node chosen as the injection point. With virtual subtrees it allows you to extend built in or even 3rd party package trees with additional features. An example could be developing a "loyalty point" program for your e-commerce site and injecting the related database tables into a Vendr store tree. This allows the management of the program in its most logical location.

Defining virtual SubTrees

AddVirtualSubTree(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder

Adds a virtual subtree to the current tree with its visibility controlled via the visibility expression.

// Example
withTreeConfig.AddVirtualSubTree(ctx => ctx.Source.Id == 1056, contextAppConfig => {
    ...
});

AddVirtualSubTreeBefore(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda matchExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder

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

// Example
withTreeConfig.AddVirtualSubTreeBefore(ctx => ctx.Source.Id == 1056, treeNode => treeNode.Name == "Settings", contextAppConfig => {
    ...
});

AddVirtualSubTreeAfter(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda matchExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder

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

// Example
withTreeConfig.AddVirtualSubTreeAfter(ctx => ctx.Source.Id == 1056, treeNode => treeNode.Name == "Settings", contextAppConfig => {
    ...
});

Controlling where to inject the Virtual SubTrees

Controlling where a virtual subtree is injected is done via the visibility expression passed to one of the AddVirtualSubTree methods on the root UIBuilderConfigBuilder instance. Without a visibility expression, Umbraco UI Builder would inject the virtual subtree under every node in the given tree. This expression can be used to identify the exact location where our tree should go.

To help with this, the visibility expression is passed a single VirtualSubTreeFilterContext argument with relevant contextual information. This information is about 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 in case you need to resolve a service to determine the correct node to inject below.

public class VirtualSubTreeFilterContext
{
    public NodeContext Source { get; }
    public IEnumerable<IReadOnlyUserGroup> UserGroups { get; }
    public IServiceProvider ServiceProvider { get; }
}

public class NodeContext
{
    public string Id { get; }
    public string TreeAlias { get; }
    public string SectionAlias { get; }
    public FormCollection QueryString { get; }
}

Below you can find an example of a more complex filter expression where injection is based on the Document Type of a content node:

withTreeConfig.AddVirtualSubTree(ctx =>
    {
        using var umbracoContextRef = ctx.ServiceProvider.GetRequiredService<IUmbracoContextFactory>().EnsureUmbracoContext();

        if (!int.TryParse(ctx.Source.Id, out int id))
            return false;

        return (umbracoContextRef.UmbracoContext.Content.GetById(id)?.ContentType.Alias ?? "") == "textPage";
    },
    virtualNodeConfig => virtualNodeConfig
        ...
);

Controlling 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 and pass a match expression used to identify the tree node to insert before/after. This expression is passed a single TreeNode argument to determine the position. It also requires a boolean return value to indicate the relevant location has been found.

public class TreeNode
{
    public object Id { get; }
    public object ParentId { get; }
    public string Alias { get; }
    public string Name { get; }
    public string NodeType { get; }
    public string Path { get; }
    public string RoutePath { get; }
    public IDictionary<string, object> AdditionalData { get; }
    ...
}

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

treeNode => treeNode.alias == "settings"

Configuring a Virtual SubTrees

Injecting Virtual SubTrees into 3rd party trees

public interface ITreeHelper
{
    string TreeAlias { get; }
    string GetUniqueId(string nodeId, FormCollection queryString);
    object GetEntityId(string uniqueId);
    string GetPath(string uniqueId);
}

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

builder.Services.AddSingleton<ITreeHelper, MyCustomTreeHelper>();

Once registered any virtual subtrees registered against the given helpers tree alias will then use your tree helper to locate the required information.

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.

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.

AddCard(Type cardType) : CollectionConfigBuilder<TEntityType>

Adds a card of the given type to the collection.

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:

The Entity Picker property editor is an Umbraco property editor that lets you select one or more entities from an Umbraco UI Builder collection.

Configuring an entity picker

To configure an entity picker you need to create a Data Type in the Umbraco backoffice. From the property editor dropdown choose 'Umbraco UI Builder Entity Picker'.

From there choose 'Section' and 'Collection' you wish to pick entities from. You can also choose an optional list view 'Data View' if there are any configured.

You can also set a minimum and maximum number of items to be able to pick if required.

With an entity picker Data Type defined, finish off the configuration by adding it to the desired Document Type definition.

Using an entity picker

Using the entity picker should be pretty familiar as it aims to mimic the content picker as closely as possible.

To pick an entity click the 'Add' link to launch the picker dialog. The dialog should present a paginated list of entities to pick from. If any searchable fields were configured for the entity type, you can perform a search by typing a search term in the search input field.

To pick your items click on the entity names and then click 'Select' in the bottom right-hand corner.

The picker should display a summary of the selected entities which can be sorted by dragging the selected entities into the desired order.

To save the value either save or save and publish the current document.

Getting the value of an entity picker

// Example
foreach(var p in Model.People){
    ...
}

Repositories are used by Umbraco UI Builder to access the entity data stores. By default, collections will use a generic built-in NPoco repository. However, you can define your own repository implementation should you wish to store your entities via an alternative strategy.

Defining a repository

To define a repository create a class that inherits from the base class Repository<TEntity, TId> and implements all of its abstract methods.

// Example
public class PersonRepository : Repository<Person, int> {

    public PersonRepository(RepositoryContext context)
        : base(context)
    { }

    protected override int GetIdImpl(Person entity) {
        return entity.Id;
    }

    protected override Person GetImpl(int id) {
        ...
    }

    protected override Person SaveImpl(Person entity) {
        ...
    }

    protected override void DeleteImpl(int id) {
        ...
    }

    protected override IEnumerable<Person> GetAllImpl(Expression<Func<Person, bool>> whereClause, Expression<Func<Person, object>> orderBy, SortDirection orderByDirection) {
        ...
    }

    protected override PagedResult<Person> GetPagedImpl(int pageNumber, int pageSize, Expression<Func<Person, bool>> whereClause, Expression<Func<Person, object>> orderBy, SortDirection orderByDirection) {
        ...
    }

    protected override long GetCountImpl(Expression<Func<Person, bool>> whereClause) {
        ...
    }

    protected override IEnumerable<TJunctionEntity> GetRelationsByParentIdImpl<TJunctionEntity>(int parentId, string relationAlias)
    {
        ...
    }

    protected override TJunctionEntity SaveRelationImpl<TJunctionEntity>(TJunctionEntity entity)
    {
        ...
    }
}

Note: For all Impl methods there are public alternatives without the Impl suffix. However, there are separate implementation methods in order to ensure all repositories fire the relevant Umbraco UI Builder events. This is whether triggered via the Umbraco UI Builder's UI or not.

Changing the repository implementation of a collection

SetRepositoryType<TRepositoryType>() : CollectionConfigBuilder<TEntityType>

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

// Example
collectionConfig.SetRepositoryType<PersonRepositoryType>();

SetRepositoryType(Type repositoryType) : CollectionConfigBuilder<TEntityType>

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

// Example
collectionConfig.SetRepositoryType(typeof(PersonRepositoryType));

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.

IRepositoryFactory.GetRepository<TEntity, TId>() : Repository<TEntity, TId>

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.

// Example
public class MyController : Controller
{
    private readonly Repository<Person, int> _repo;

    public MyController(IRepositoryFactory repoFactory) 
    {
        _repo = repoFactory.GetRepository<Person, int>();
    }
}