The Basics
An overview of the basics of configuring a collection in Umbraco UI Builder.
A collection configuration in Umbraco UI Builder defines how collections are structured and displayed in the backoffice. This guide covers the core concepts, with additional options available in other configuration sections.
Defining a Collection
A collection is defined using the AddCollection
method on a Tree
or parent Folder
configuration instance.
Using the AddCollection()
Method
AddCollection()
MethodAdds a collection to the given container with the specified names, description, and default icons. The ID property must be defined.
Method Syntax
Example
Using the AddCollection()
Method with Icons
AddCollection()
Method with IconsAdds a collection to the given container with the specified names, description, and icons. The ID property must be defined.
Method Syntax
Example
Changing a Collection Alias
Using the SetAlias()
Method
SetAlias()
MethodSets the alias of the collection.
Optional: When creating a new collection, an alias is automatically generated from the supplied name for you. To customize the alias, the SetAlias
method can be used.
Method Syntax
Example
Changing a Collection Icon Color
Using the SetIconColor()
Method
SetIconColor()
MethodSets the collection icon color to the given color. The available options are black
, green
, yellow
, orange
, blue
, or red
.
Method Syntax
Example
Defining an Entity Name
In Umbraco, every entity is expected to have a name property. To ensure the Umbraco UI Builder knows which property to use, you must specify it.
If the entity lacks a dedicated name property, you can define how to construct a name using other properties. This is done using either the SetNameProperty
or SetNameFormat
methods on a Collection
config builder instance.
Using the SetNameProperty()
Method
SetNameProperty()
MethodSpecifies the entity property to use as the name, which must be of type string
. This property serves as the label in trees and list views, appears in the editor interface header, and is automatically included in searchable properties. It is also used as the default sorting property.
Method Syntax
Example
Using the SetNameProperty()
Method with Custom Heading
SetNameProperty()
Method with Custom HeadingSpecifies which property of your entity should be used as the name property and defines a custom heading for the list view column. The property must be of type string
.
Setting a name property ensures its value is displayed as the label for the entity in trees and list views. It will also be editable in the editor interface's header region.
Additionally, the property is automatically added to the searchable properties collection and used as the default sort property.
Method Syntax
Example
Using the SetNameFormat()
Method
SetNameFormat()
MethodDefines a format expression to dynamically generate a label for the entity in trees and list views.
This method is used when there is no single name property available on the entity. As a result, none of the default behaviors of the SetNameProperty
method, such as automatic sorting, searching, or header editing, will apply.
Method Syntax
Example
Defining a Default Sort Order
Using the SetSortProperty()
Method
SetSortProperty()
MethodSpecifies the property used to sort the collection, with the default sort direction set to ascending.
Method Syntax
Example
Using the SetSortProperty()
Method with Sort Direction
SetSortProperty()
Method with Sort DirectionDefines the property of the entity to sort by, based on the specified sort direction.
Method Syntax
Example
Defining Time Stamp Properties
Using the SetDateCreatedProperty
Method
SetDateCreatedProperty
MethodDefines the property of the entity to use as the date created field. The property must be of type DateTime
. When specified, this field will be automatically populated with the current date and time when a new entity is saved via the repository.
Method Syntax
Example
Using the SetDateModifiedProperty
Method
SetDateModifiedProperty
MethodDefines the property of the entity to use as the date modified field. The property must be of type DateTime
. When specified, this field will be updated with the current date and time whenever the entity is saved via the repository.
Method Syntax
Example
Configuring Soft Deletes
By default, entities deleted via the Umbraco UI Builder repository are permanently removed from the system. The SetDeletedProperty
method marks records as deleted without removing them. This retains them in the data repository while hiding them from the UI.
Using the SetDeletedProperty()
Method
SetDeletedProperty()
MethodDefines the property of the entity to use as the deleted flag. The property must be of type boolean
or int
. When set, delete actions will mark the entity as deleted by setting the flag instead of removing the entity.
For boolean
properties, the flag is set to True
when deleted. For int
properties, the flag is set to a UTC Unix timestamp representing the deletion date. Additionally, fetch actions will automatically exclude deleted entities.
Method Syntax
Example
Disabling Create, Update, or Delete Features
Using the DisableCreate()
Method
DisableCreate()
MethodDisables the option to create entities within the current collection. Entities can still be created programmatically, after which editing is allowed through the UI.
Method Syntax
Example
Using the DisableCreate()
Method with Conditions
DisableCreate()
Method with ConditionsDisables entity creation within the current collection if the specified runtime predicate evaluates to true. Entities can still be created programmatically, after which editing is allowed in the UI.
Method Syntax
Example
Using the DisableUpdate()
Method
DisableUpdate()
MethodDisables the option to update entities within the current collection. Entities can be created, but further editing is not permitted
Method Syntax
Example
Using the DisableUpdate()
Method with Conditions
DisableUpdate()
Method with ConditionsDisables the option to update entities within the current collection if the specified runtime predicate evaluates to true. Entities can be created, but further editing is not permitted.
Method Syntax
Example
Using the DisableDelete()
Method
DisableDelete()
MethodDisables the option to delete entities within the current collection. This is useful when data needs to be retained and visible. For more information, see the Configuring Soft Deletes section.
Method Syntax
Example
Using the DisableDelete()
Method with Conditions
DisableDelete()
Method with ConditionsDisables the option to delete entities within the current collection if the specified runtime predicate evaluates to true. This is useful when data needs to be retained and visible. For more information, see the Configuring Soft Deletes section.
Method Syntax
Example
Using the MakeReadOnly()
Method
MakeReadOnly()
MethodMarks the collection as read-only, disabling all Create, Read, Update, and Delete (CRUD) operations via the UI.
Method Syntax
Example
Using the MakeReadOnly()
Method with Conditions
MakeReadOnly()
Method with ConditionsMarks the collection as read-only if the specified runtime predicate evaluates to true. This disables all Create, Read, Update, and Delete (CRUD) operations via the UI.
Method Syntax
Example
Setting Collection Visibility
Using the SetVisibility()
Method
SetVisibility()
MethodSets the runtime visibility of the collection.
Method Syntax
Example
Changing a Collection Connection String
By default, Umbraco UI Builder uses the Umbraco connection string for its database connection. You can override this by calling the SetConnectionString
method on a Collection
config builder instance.
Using the SetConnectionString()
Method
SetConnectionString()
MethodDefines the connection string for the collection repository.
Method Syntax
Example
Last updated
Was this helpful?