From c151e4239d9300701b29a419b38cc1723fe95c19 Mon Sep 17 00:00:00 2001 From: Esha Noronha Date: Fri, 28 Feb 2025 11:14:38 +0100 Subject: [PATCH 1/2] Updated articles --- 15/umbraco-ui-builder/areas/context-apps.md | 206 ++++++++++--- 15/umbraco-ui-builder/areas/dashboards.md | 153 +++++++--- 15/umbraco-ui-builder/areas/folders.md | 164 +++++++--- 15/umbraco-ui-builder/areas/trees.md | 315 +++++++++++++++----- 4 files changed, 634 insertions(+), 204 deletions(-) diff --git a/15/umbraco-ui-builder/areas/context-apps.md b/15/umbraco-ui-builder/areas/context-apps.md index ad04cf5d62d..224bcdf1dd6 100644 --- a/15/umbraco-ui-builder/areas/context-apps.md +++ b/15/umbraco-ui-builder/areas/context-apps.md @@ -1,144 +1,252 @@ --- -description: Configuring context apps in Umbraco UI Builder, the backoffice UI builder for Umbraco. +description: Configuring context apps in Umbraco UI Builder. --- # Context Apps -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. +Context Apps in Umbraco UI Builder function similarly to Content Apps. They provide contextual applications within the content editor UI. By defining context apps, you can expose collections that are directly related to the content in question. For example, blog post comments can be linked to their respective blog posts and managed in context through a content app. ![Context App](../images/context_app.png) -## Defining a context app +## Defining a Context App You can define a context app by calling one of the `AddContextApp` methods on a [`WithTreeConfigBuilder`](trees.md#extending-an-existing-tree) instance. -### **AddContextApp(string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### Using the `AddContextApp()` Method -Adds a context app with the given name and default icon. +Adds a context app with the specified name and default icon. + +#### Method Syntax + +```cs +AddContextApp(string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example withTreeConfig.AddContextApp("Comments", contextAppConfig => { ... }); ``` -### **AddContextApp(string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### Using the `AddContextApp()` Method with Custom Icon + +Adds a context app with the specified name and custom icon. + +#### Method Syntax -Adds a context app to the Umbraco menu with the given name and icon. +```cs +AddContextApp(string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example withTreeConfig.AddContextApp("Comments", "icon-chat", contextAppConfig => { ... }); ``` -### **AddContextAppBefore(string beforeAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### 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 + +```cs +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 ```csharp -// Example withTreeConfig.AddContextAppBefore("umbContent", "Comments", contextAppConfig => { ... }); ``` -### **AddContextAppBefore(string beforeAlias, string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### Using the `AddContextAppBefore()` Method with a Custom Icon -Adds a context app to the Umbraco menu with the given name and icon **before** the context app with the given alias. +Adds a context app with the specified name and custom icon before another context app specified by its alias. + +#### Method Syntax + +```cs +AddContextAppBefore(string beforeAlias, string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example withTreeConfig.AddContextAppBefore("umbContent", "Comments", "icon-chat", contextAppConfig => { ... }); ``` -### **AddContextAppAfter(string afterAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### 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 -Adds a context app with the given name and default icon **after** the context app with the given alias. +```cs +AddContextAppAfter(string afterAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example + withTreeConfig.AddContextAppAfter("umbContent", "Comments", contextAppConfig => { ... }); ``` -### **AddContextAppAfter(string afterAlias, string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### 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 + +```cs +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 ```csharp -// Example withTreeConfig.AddContextAppAfter("umbContent", "Comments", "icon-chat", contextAppConfig => { ... }); ``` -## Changing a context app alias +## Changing a Context App Alias + +### Using the `SetAlias()` Method -### **SetAlias(string alias) : ContextAppConfigBuilder** +Sets the alias of the context app. By default, an alias is automatically generated from the context app's name. You can use the `SetAlias` method to specify a custom alias. + +#### Method Syntax -Sets the alias of the context app. +```cs +SetAlias(string alias) : ContextAppConfigBuilder +``` -**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 ```csharp -// Example contextAppConfig.SetAlias("comments"); ``` -## Changing a context app icon color +## Changing a Context App Icon Color + +### Using the `SetIconColor()` Method + +Sets the context app icon color to the given color. The available colors are: `black`, `green`, `yellow`, `orange`, `blue` or `red`. + +#### Method Syntax -### **SetIconColor(string color) : ContextAppConfigBuilder** +```cs +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 ````csharp -// Example contextAppConfig.SetIconColor("blue"); ```` -## Changing when a context app should display +## Changing Context App Visibility + +Context app visibility is controlled by a delegate that takes a `ContextAppVisibilityContext` instance. This method contains a `Source` property which holds a reference to the source object that the content app is being displayed on (i.e., an `IContent` instance). It also holds a reference to a `UserGroups` collection of the currently logged-in user's user groups. You can use these values to determine when the context app should be displayed. + +By default, context apps are pre-filtered to only appear on the tree they are defined in. This default behavior is combined with the SetVisibility configuration to control visibility. -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. +### Using the `SetIconColor()` Method -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. +Defines the visibility of the context app based on a delegate expression. -### **SetVisibility(Func<ContextAppVisibilityContext, bool> visibilityExpression) : ContextAppConfigBuilder** +#### Method Syntax -Sets the context app visibility delegate. +```cs +SetVisibility(Func<ContextAppVisibilityContext, bool> visibilityExpression) : ContextAppConfigBuilder +``` + +#### Example ````csharp -// Example contextAppConfig.SetVisibility(appCtx => appCtx.Source is IContent content && content.ContentType.Alias == "blogPost"); ```` -## Adding a collection to a context app +## 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** +### Using the `AddCollection<>()` Method + +Adds a collection to the current context app with the specified names, descriptions, and default icons. Each collection requires an ID field and a foreign key field, linking to Umbraco node UDI values. For more details, see the [Collections](../collections/overview.md) article. -Adds a collection to the current content app with the given names, descriptions and default icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. A foreign key property accessor is also required so that the Umbraco UI Builder knows which property holds the Umbraco nodes UDI value. You can read more about this in the [Collections documentation](../collections/overview.md). +#### Method Syntax + +```cs +AddCollection( + Lambda idFieldExpression, + Lambda fkFieldExpression, + string nameSingular, + string namePlural, + string description, + Lambda collectionConfig = null +) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example -contextAppConfig.AddCollection(p => p.Id, p=> "Comment", "Comments", "A collection of comments", collectionConfig => { - ... -}); +contextAppConfig.AddCollection( + p => p.Id, + p => "Comment", + "Comments", + "A collection of comments", + collectionConfig => { + // Collection configuration here + } +); ``` -### **AddCollection<TEntityType>(Lambda idFieldExpression, Lambda fkFieldExpression, string nameSingular, string namePlural, string description, string iconSingular, string iconPlural, Lambda collectionConfig = null) : ContextAppConfigBuilder** +### Using the `AddCollection<>()` Method with Custom Icon + +**AddCollection<TEntityType>(Lambda idFieldExpression, Lambda fkFieldExpression, string nameSingular, string namePlural, string description, string iconSingular, string iconPlural, Lambda collectionConfig = null) : ContextAppConfigBuilder** -Adds a collection to the current context app 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. A foreign key property accessor is also required so that Umbraco UI Builder knows which property holds the Umbraco nodes UDI value. You can read more about this in the [Collections documentation](../collections/overview.md). +Adds a collection to the current context app with the specified names, descriptions, and custom icons. Each collection requires an ID field and a foreign key field, linking to Umbraco node UDI values. For more details, see the [Collections](../collections/overview.md) article. + +#### Method Syntax + +```cs +AddCollection( + Lambda idFieldExpression, + Lambda fkFieldExpression, + string nameSingular, + string namePlural, + string description, + string iconSingular, + string iconPlural, + Lambda collectionConfig = null +) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example -contextAppConfig.AddCollection(p => p.Id, "Comment", "Comments", "A collection of comments", "icon-chat", "icon-chat", collectionConfig => { - ... -}); +contextAppConfig.AddCollection( + p => p.Id, + "Comment", + "Comments", + "A collection of comments", + "icon-chat", + "icon-chat", + collectionConfig => { + // Collection configuration here + } +); ``` diff --git a/15/umbraco-ui-builder/areas/dashboards.md b/15/umbraco-ui-builder/areas/dashboards.md index 3a84ba959ff..d753f2332e9 100644 --- a/15/umbraco-ui-builder/areas/dashboards.md +++ b/15/umbraco-ui-builder/areas/dashboards.md @@ -1,103 +1,180 @@ --- -description: Configuring dashboards in Umbraco UI Builder, the backoffice UI builder for Umbraco. +description: Configuring Dashboards in Umbraco UI Builder. --- # Dashboards -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. +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. ![Dashboards](../images/dashboards.png) -## Defining a dashboard +## Defining a Dashboard -You can define a dashboard by calling one of the `AddDashboard` methods on either a [`SectionConfigBuilder`](sections.md) or a [`WithSectionConfigBuilder`](sections.md#extending-an-existing-section) instance. +You can define a dashboard by calling one of the `AddDashboard` methods on a [`SectionConfigBuilder`](sections.md) or a [`WithSectionConfigBuilder`](sections.md#extending-an-existing-section) instance. -### **AddDashboard(string name, Lambda dashboardConfig = null) : DashboardConfigBuilder** +### Using the `AddDashboard()` Method -Adds a dashboard with the given name. +Adds a dashboard with the specified name. + +#### Method Syntax + +```cs +AddDashboard(string name, Lambda dashboardConfig = null) : DashboardConfigBuilder +``` + +#### Example ```csharp -// Example sectionConfig.AddDashboard("Team", dashboardConfig => { ... }); ``` -### **AddDashboardBefore(string beforeAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder** +### Using the `AddDashboardBefore()` Method + +Adds a dashboard with the specified name before the dashboard with the given alias. -Adds a dashboard with the given name **before** the dashboard with the given alias. +#### Method Syntax + +```cs +AddDashboardBefore(string beforeAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder +``` + +#### Example ```csharp -// Example sectionConfig.AddDashboardBefore("contentIntro", "Team", dashboardConfig => { ... }); ``` -### **AddDashboardAfter(string afterAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder** +### Using the `AddDashboardAfter()` Method + +Adds a dashboard with the specified name after the dashboard with the given alias. -Adds a dashboard with the given name **after** the dashboard with the given alias. +#### Method Syntax + +```cs +AddDashboardAfter(string afterAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder +``` + +#### Example ```csharp -// Example sectionConfig.AddDashboardAfter("contentIntro", "Team", dashboardConfig => { ... }); ``` -## Changing a dashboard alias +## Setting a Custom Dashboard Alias + +### Using the `SetAlias()` Method -### **SetAlias(string alias) : DashboardConfigBuilder** +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. -Sets the alias of the dashboard. +#### Method Syntax -**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. +```cs +SetAlias(string alias) : DashboardConfigBuilder +``` + +#### Example ```csharp -// Example dashboardConfig.SetAlias("team"); ``` -## Changing when a dashboard should display +## Controlling Dashboard Visibility -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. +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, 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. +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. -### **SetVisibility(Lambda visibilityConfig) : DashboardConfigBuilder** +### Using the `SetVisibility()` Method -Sets the dashboard visibility config. +Defines visibility rules for the dashboard. + +#### Method Syntax + +```cs +SetVisibility(Lambda visibilityConfig) : DashboardConfigBuilder +``` + +#### Example ````csharp -// Example dashboardConfig.SetVisibility(visibilityConfig => visibilityConfig .ShowForUserGroup("admin") .HideForUserGroup("translator") ); ```` -## Setting the collection of a dashboard +## 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 -Dashboards are only able to display a single collection. If you need to display multiple collections, then you need to configure multiple dashboards. +Assigns a collection to the dashboard with the specified names, descriptions, and default icons. The ID property must be defined. For more details, see the [Collections](../collections/overview.md) article. -### **SetCollection<TEntityType>(Lambda idFieldExpression, string nameSingular, string namePlural, string description, Lambda collectionConfig = null) : ContextAppConfigBuilder** +#### Method Syntax -Sets the collection of the current dashboard with the given names, descriptions, and default icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. For more information check the [Collections documentation](../collections/overview.md). +```cs +SetCollection( + Lambda idFieldExpression, + string nameSingular, + string namePlural, + string description, + Lambda collectionConfig = null +) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example -dashboardConfig.SetCollection(p => p.Id, p=> "Team Member", "Team Members", "A collection of team members", collectionConfig => { - ... -}); +dashboardConfig.SetCollection( + p => p.Id, + "Team Member", + "Team Members", + "A collection of team members", + collectionConfig => { + ... + } +); ``` -### **SetCollection<TEntityType>(Lambda idFieldExpression, Lambda fkFieldExpression, string nameSingular, string namePlural, string description, string iconSingular, string iconPlural, Lambda collectionConfig = null) : ContextAppConfigBuilder** +### Using the `SetCollection<>()` Method with Custom Icons + +Assigns a collection to the dashboard with the specified names, descriptions, and custom icons. The ID property must be defined. For more details, see the [Collections](../collections/overview.md) article. + +#### Method Syntax + +```cs +SetCollection( + Lambda idFieldExpression, + Lambda fkFieldExpression, + string nameSingular, + string namePlural, + string description, + string iconSingular, + string iconPlural, + Lambda collectionConfig = null +) : ContextAppConfigBuilder +``` -Sets the collection of the current dashboard 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. For more information check the [Collections documentation](../collections/overview.md). +#### Example ```csharp -// Example -dashboardConfig.SetCollection(p => p.Id, "Team Member", "Team Members", "A collection of team members", "icon-umm-user", "icon-umb-user", collectionConfig => { - ... -}); +dashboardConfig.SetCollection( + p => p.Id, + p => p.ForeignKey, + "Team Member", + "Team Members", + "A collection of team members", + "icon-umm-user", + "icon-umb-user", + collectionConfig => { + ... + } +); ``` diff --git a/15/umbraco-ui-builder/areas/folders.md b/15/umbraco-ui-builder/areas/folders.md index 4f9017346fd..0077bf0861e 100644 --- a/15/umbraco-ui-builder/areas/folders.md +++ b/15/umbraco-ui-builder/areas/folders.md @@ -1,107 +1,193 @@ --- -description: Configuring folders to organise trees in Umbraco UI Builder, the backoffice UI builder for Umbraco. +description: Configuring folders to organise trees in Umbraco UI Builder. --- # Folders -A folder can appear in either a tree or as a sub folder to other folders. Folders can contain either other (sub)folders or [collections](../collections/overview.md). +Folders help organize trees in Umbraco UI Builder, allowing you to structure content with nested folders and collections. A folder can exist within a tree or as a sub-folder within another folder. Folders can contain either sub-folders or [Collections](../collections/overview.md). ![Tree with Settings folder](../images/tree.png) -## Defining a folder +## Defining a Folder -You can define a folder by calling one of the `AddFolder` methods on a given [`Tree`](trees.md) or parent `Folder` config builder instance. +To define a folder, use one of the `AddFolder` methods on a [`Tree`](trees.md) or parent `Folder` config builder instance. -### **AddFolder(string name, Lambda folderConfig = null) : FolderConfigBuilder** +### Using the `AddFolder()` Method -Adds a folder to the current tree with the given name and a default folder icon. +Adds a folder to the current tree with the specified name and a default folder icon. + +#### Method Syntax + +```cs +AddFolder(string name, Lambda folderConfig = null) : FolderConfigBuilder +``` + +#### Example ````csharp -// Example treeConfig.AddFolder("Settings", folderConfig => { ... }); ```` -### **AddFolder(string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder** +### Using the `AddFolder()` Method with Custom Icon + +Adds a folder to the current tree with a specified name and icon. -Adds a folder to the current tree with the given name + icon. +#### Method Syntax + +```cs +AddFolder(string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder +``` + +#### Example ````csharp -// Example treeConfig.AddFolder("Settings", "icon-settings", folderConfig => { ... }); ```` -## Changing a folder alias +## 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 -### **SetAlias(string alias) : FolderConfigBuilder** +Sets a custom alias for a folder. -Sets the alias of the folder. +#### Method Syntax -**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. +```cs +SetAlias(string alias) : FolderConfigBuilder +``` + +#### Example ````csharp -// Example folderConfig.SetAlias("settings"); ```` -## Changing a folder icon color +## Changing a Folder Icon Color + +### Using the `SetIconColor()` Method + +Sets the folder icon color to the given color. The available colors are: `black`, `green`, `yellow`, `orange`, `blue`, or `red`. + +#### Method Syntax -### **SetIconColor(string color) : FolderConfigBuilder** +```cs +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`. +#### Example ````csharp -// Example folderConfig.SetIconColor("blue"); ```` -## Adding a sub folder to a folder +## Adding a Sub-Folder To a Folder + +### Using the `AddFolder()` Method for Sub-Folders + +Adds a sub-folder inside the current folder with a specified name and a default folder icon. + +#### Method Syntax -### **AddFolder (string name, Lambda folderConfig = null) : FolderConfigBuilder** +```cs +AddFolder (string name, Lambda folderConfig = null) : FolderConfigBuilder +``` -Adds a sub folder to the current folder with the given name and a default folder icon. +#### Example ````csharp -// Example folderConfig.AddFolder("Categories", subFolderConfig => { ... }); ```` -### **AddFolder (string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder** +### Using the `AddFolder()` Method for Sub-Folders with Custom Icon -Adds a sub folder to the current folder with the given name + icon. +Adds a sub folder to the current folder with a specified name and custom icon. + +#### Method Syntax + +```cs +AddFolder (string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder +``` + +#### Example ````csharp -// Example folderConfig.AddFolder("Categories", "icon-tags", subFolderConfig => { ... }); ```` -## Adding a collection to a folder +## Adding a Collection to a Folder + +### Using the `AddCollection<>()` Method -### **AddCollection<TEntityType>(Lambda idFieldExpression, string nameSingular, string namePlural, string description, Lambda collectionConfig = null) : CollectionConfigBuilder<TEntityType>** +Adds a collection to the current folder with the given names, descriptions, and default icons. The ID property must be defined. For more details, see the [Collections](../collections/overview.md) article. -Adds a collection to the current folder with the given names, descriptions, and default icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. For more information check the [Collections documentation](../collections/overview.md). +#### Method Syntax + +```cs +AddCollection( + Lambda idFieldExpression, + string nameSingular, + string namePlural, + string description, + Lambda collectionConfig = null +) : CollectionConfigBuilder + +``` + +#### Example ````csharp -// Example -folderConfig.AddCollection(p => p.Id, "Person", "People", "A collection of people", collectionConfig => { - ... -}); +folderConfig.AddCollection( + 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>** +### Using the `AddCollection<>()` Method with Custom Icons + +Adds a collection to the current folder with the given names, description and icons. The ID property must be defined. For more details, see the [Collections](../collections/overview.md) article. + +#### Method Syntax + +```cs +AddCollection( + Lambda idFieldExpression, + string nameSingular, + string namePlural, + string description, + string iconSingular, + string iconPlural, + Lambda collectionConfig = null +) : CollectionConfigBuilder -Adds a collection to the current folder 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. For more information check the [Collections documentation](../collections/overview.md). +``` + +#### Example ````csharp -// Example -folderConfig.AddCollection(p => p.Id, "Person", "People", "A collection of people", "icon-umb-users", "icon-umb-users", collectionConfig => { - ... -}); +folderConfig.AddCollection( + p => p.Id, + "Person", + "People", + "A collection of people", + "icon-umb-users", + "icon-umb-users", + collectionConfig => { + ... + } +); ```` diff --git a/15/umbraco-ui-builder/areas/trees.md b/15/umbraco-ui-builder/areas/trees.md index 551f95bbc4d..b7e232aaaef 100644 --- a/15/umbraco-ui-builder/areas/trees.md +++ b/15/umbraco-ui-builder/areas/trees.md @@ -1,234 +1,393 @@ --- -description: Configuring trees in Umbraco UI Builder, the backoffice UI builder for Umbraco. +description: Configuring and customizing Trees to organize and manage the backoffice interface effectively. --- -# Trees +# Tree -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. +A tree is a hierarchical structure that organizes sections into sub-sections. It appears in the main side panel of the Umbraco interface. In Umbraco UI Builder, each section can only have one tree definition, but you can use folder nodes to organize the tree. ![Tree](../images/tree.png) -## Configuring a Umbraco UI Builder section tree +## Configuring a Umbraco UI Builder Section Tree -The tree configuration for Umbraco UI Builder sections is a sub-configuration of a [`Section`](sections.md) config builder instance and is accessed via its `Tree` method. +The tree configuration for Umbraco UI Builder sections is part of the [`Section`](sections.md) config builder and is accessed via its `Tree` method. -### **Tree(Lambda treeConfig = null) : TreeConfigBuilder** +### Using the `Tree()` Method -Accesses the tree config of the given section. +This method defines the structure and behavior of a tree within a section. + +#### Method Syntax + +```cs +Tree(Lambda treeConfig = null) : TreeConfigBuilder +``` + +#### Example + +```csharp -````csharp -// Example sectionConfig.Tree(treeConfig => { ... }); -```` +``` -## Adding a tree to an existing section +## Adding a Tree to an Existing Section -The tree configuration for existing sections is a sub-configuration of a [`WithSection`](sections.md#extending-an-existing-section) config builder instance and is accessed via one of its `AddTree` methods. +To add a tree to an existing section, use one of the `AddTree` methods from the [`WithSection`](sections.md#extending-an-existing-section) config builder. -### **AddTree(string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder** +### Using the `AddTree()` method -Adds a tree to the current section. +This method adds a tree to the current section, specifying its name and icon. + +#### Method Syntax + +```cs +AddTree(string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder +``` + +#### Example ````csharp -// Example withSectionConfig.AddTree("My Tree", "icon-folder", treeConfig => { ... }); ```` -### **AddTree(string groupName, string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder** +### Grouping Trees with `AddTree()` Method + +This method adds a tree to the current section under a specified group. + +#### Method Syntax + +```cs +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. +#### Example ````csharp -// Example withSectionConfig.AddTree("My Group", "My Tree", "icon-folder", treeConfig => { ... }); ```` -### **AddTreeBefore(string treeAlias, string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder** +### Using `AddTreeBefore()` to Position a Tree + +This method adds a tree to the current section before the tree with the specified alias. + +#### Method Syntax + +```cs +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. +#### Example ````csharp -// Example withSectionConfig.AddTreeBefore("member", "My Tree", "icon-folder", treeConfig => { ... }); ```` -### **AddTreeAfter(string treeAlias, string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder** +### Using `AddTreeAfter()` to Position a Tree -Adds a tree to the current section **after** the tree with the given alias. +This method adds a tree to the current section after the tree with the specified alias. + +#### Method Syntax + +```cs +AddTreeAfter(string treeAlias, string name, string icon, Lambda treeConfig = null) : TreeConfigBuilder +``` + +#### Example ````csharp -// Example withSectionConfig.AddTreeAfter("member", "My Tree", "icon-folder", treeConfig => { ... }); ```` -## Changing the tree icon color +## Changing the Tree Icon Color -### **SetIconColor(string color) : TreeConfigBuilder** +### Using the `SetIconColor()` Method -Sets the trees icon color to the given color. The options that are possible are `black`, `green`, `yellow`, `orange`, `blue` or `red`. +This method changes the color of the tree’s icon. The available options are `black`, `green`, `yellow`, `orange`, `blue`, or `red`. {% hint style="warning" %} -Only trees added to existing sections have an icon. Trees added to Umbraco UI Builder sections don't show a tree icon instead they go straight into displaying the tree contents. +Only trees in existing sections have an icon. Trees in Umbraco UI Builder sections display the tree contents directly. {% endhint %} +#### Method Syntax + +```cs +SetIconColor(string color) : TreeConfigBuilder +``` + +#### Example + ````csharp -// Example collectionConfig.SetIconColor("blue"); ```` -## Adding a group to a tree +## Adding a Group to a Tree -### **AddGroup(string name, Lambda groupConfig = null) : GroupConfigBuilder** +### Using the `AddGroup()` Method -Adds a group to the current tree with the given name. +This method adds a group to the current tree with the specified name. {% hint style="warning" %} -Only Umbraco UI Builder section trees can configure groups, where trees added to existing sections cannot. +Only trees in Umbraco UI Builder sections support groups. {% endhint %} +#### Method Syntax + +```cs +AddGroup(string name, Lambda groupConfig = null) : GroupConfigBuilder +``` + +#### Example + ```csharp -// Example treeConfig.AddGroup("Settings", groupConfig => { ... }); ``` -## Adding a folder to a tree/group +## Adding a Folder to a Tree or Group + +### Using the `AddFolder()` Method + +This method adds a folder node inside a tree or group, using the default folder icon. For more details, see the [Folders](folders.md) article. -### **AddFolder(string name, Lambda folderConfig = null) : FolderConfigBuilder** +#### Method Syntax + +```cs +AddFolder(string name, Lambda folderConfig = null) : FolderConfigBuilder +``` -Adds a folder to the current tree/group with the given name and a default folder icon. For more information check the [Folders documentation](folders.md). +#### Example ```csharp -// Example treeConfig.AddFolder("Settings", folderConfig => { ... }); ``` -### **AddFolder(string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder** +### Using the `AddFolder()` Method with Custom Icon -Adds a folder to the current tree/group with the given name + icon. For more information check the [Folders documentation](folders.md). +This method adds a folder with a specified icon inside a tree or group. For more details, see the [Folders](folders.md) article. + +#### Method Syntax + +```cs +AddFolder(string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder +``` + +#### Example ```csharp -// Example treeConfig.AddFolder("Settings", "icon-settings", folderConfig => { ... }); ``` -## Adding a collection to a tree/group +## Adding a Collection to a Tree or Group + +### Using the `AddCollection<>()` Method -### **AddCollection<TEntityType>(Lambda idFieldExpression, string nameSingular, string namePlural, string description, Lambda collectionConfig = null) : CollectionConfigBuilder<TEntityType>** +This method adds a collection to the current tree or group, specifying its names, descriptions, and default icons. The ID property must be defined. For more details, see the [Collections](../collections/overview.md) article. -Adds a collection to the current tree/group with the given names, descriptions, and default icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. For more information check the [Collections documentation](../collections/overview.md). +#### Method Syntax + +```cs +AddCollection( + Lambda idFieldExpression, + string nameSingular, + string namePlural, + string description, + Lambda collectionConfig = null +) : CollectionConfigBuilder + +``` + +#### Example ```csharp -// Example -treeConfig.AddCollection(p => p.Id, "Person", "People", "A collection of people", collectionConfig => { - ... -}); +treeConfig.AddCollection( + 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>** +#### Using the `AddCollection<>()` Method with Icons + +This method adds a collection to the current tree or group, specifying its names, descriptions, and custom icons. The ID property must be defined. For more details, see the [Collections](../collections/overview.md) article. + +#### Method Syntax + +```cs +AddCollection( + Lambda idFieldExpression, + string nameSingular, + string namePlural, + string description, + string iconSingular, + string iconPlural, + Lambda collectionConfig = null +) : CollectionConfigBuilder + +``` -Adds a collection to the current tree/group 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. For more information check the [Collections documentation](../collections/overview.md). +#### Example ```csharp -// Example -treeConfig.AddCollection(p => p.Id, "Person", "People", "A collection of people", "icon-umb-users", "icon-umb-users", collectionConfig => { - ... -}); +treeConfig.AddCollection( + p => p.Id, + "Person", + "People", + "A collection of people", + "icon-umb-users", + "icon-umb-users", + collectionConfig => { + ... + } +); ``` -## Extending an existing tree +## Extending an Existing Tree + +To extend existing trees, call the `WithTree` method on a [`WithSectionConfigBuilder`](sections.md#extending-an-existing-section) instance. + +### Using the `WithTree()` Method + +This method starts a sub-configuration for an existing tree with the specified alias. -You can extend existing trees adding Umbraco UI Builder context apps and virtual sub trees by calling the `WithTree` method of a [`WithSectionConfigBuilder`](sections.md#extending-an-existing-section) instance. +#### Method Syntax -### **WithTree(string alias, Lambda treeConfig = null) : WithTreeConfigBuilder** +```cs +WithTree(string alias, Lambda treeConfig = null) : WithTreeConfigBuilder +``` -Starts a sub-configuration for the existing Umbraco tree with the given alias. +#### Example ```csharp -// Example sectionConfig.WithTree("content", withTreeConfig => { ... }); ``` -## Adding a context app to an existing tree +## Adding a Context App to an Existing Tree + +### Using the `AddContextApp()` Method + +This method adds a context app with the specified name and default icon. For more details, see the [Context Apps](context-apps.md) article. -### **AddContextApp(string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +#### Method Syntax + +```cs +AddContextApp(string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder +``` -Adds a context app with the given name and default icon. For more information check the [Context App documentation](context-apps.md). +#### Example ```csharp -// Example withTreeConfig.AddContextApp("Comments", contextAppConfig => { ... }); ``` -### **AddContextApp(string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### Using the `AddContextApp()` Method with Custom Icon -Adds a context app to the Umbraco menu with the given name and icon. For more information check the [Context App documentation](context-apps.md). +This method adds a context app with the specified name and custom icon. For more details, see the [Context Apps](context-apps.md) article. + +#### Method Syntax + +```cs +AddContextApp(string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example withTreeConfig.AddContextApp("Comments", "icon-chat", contextAppConfig => { ... }); ``` -### **AddContextAppBefore(string beforeAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +## Adding a Context App Before or After Another Context App + +### Using the `AddContextApp()` Method Before Another Context App + +This method adds a context app with the specified name and default icon before the specified context app alias. For more information, see the [Context Apps](context-apps.md) article. -Adds a context app with the given name and default icon **before** the context app with the given alias. For more information check the [Context App documentation](context-apps.md). +#### Method Syntax + +```cs +AddContextAppBefore(string beforeAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example withTreeConfig.AddContextAppBefore("umbContent", "Comments", contextAppConfig => { ... }); ``` -### **AddContextAppBefore(string beforeAlias, string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### Using the `AddContextApp()` Method with Custom Icon Before Another Context App -Adds a context app to the Umbraco menu with the given name and icon **before** the context app with the given alias. For more information check the [Context App documentation](context-apps.md). +This method adds a context app with the specified name and custom icon before the specified context app alias. For more information, see the [Context Apps](context-apps.md) article. + +#### Method Syntax + +```cs +AddContextAppBefore(string beforeAlias, string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder +``` + +#### Example ```csharp -// Example withTreeConfig.AddContextAppBefore("umbContent", "Comments", "icon-chat", contextAppConfig => { ... }); ``` -### **AddContextAppAfter(string afterAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### Using the `AddContextApp()` Method After Another Context App + +This method adds a context app with the specified name and default icon after the specified context app alias. For more information, see the [Context Apps](context-apps.md) article. + +#### Method Syntax + +```cs +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. For more information check the [Context App documentation](context-apps.md). +#### Example ```csharp -// Example withTreeConfig.AddContextAppAfter("umbContent", "Comments", contextAppConfig => { ... }); ``` -### **AddContextAppAfter(string afterAlias, string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder** +### Using the `AddContextApp()` Method with Custom Icon After Another Context App + +This method adds a context app with the specified name and custom icon after the specified context app alias. For more information, see the [Context Apps](context-apps.md) article. + +#### Method Syntax + +```cs +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. For more information check the [Context App documentation](context-apps.md). +#### Example ```csharp -// Example withTreeConfig.AddContextAppAfter("umbContent", "Comments", "icon-chat", contextAppConfig => { ... }); From c580e36a06b2934020021687a42733119326a952 Mon Sep 17 00:00:00 2001 From: Esha Noronha Date: Fri, 28 Feb 2025 11:33:21 +0100 Subject: [PATCH 2/2] Fixed minor format issues --- 15/umbraco-ui-builder/areas/context-apps.md | 2 +- 15/umbraco-ui-builder/areas/trees.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/15/umbraco-ui-builder/areas/context-apps.md b/15/umbraco-ui-builder/areas/context-apps.md index 224bcdf1dd6..7bcbbdd209d 100644 --- a/15/umbraco-ui-builder/areas/context-apps.md +++ b/15/umbraco-ui-builder/areas/context-apps.md @@ -170,7 +170,7 @@ Defines the visibility of the context app based on a delegate expression. #### Method Syntax ```cs -SetVisibility(Func<ContextAppVisibilityContext, bool> visibilityExpression) : ContextAppConfigBuilder +SetVisibility(Func visibilityExpression) : ContextAppConfigBuilder ``` #### Example diff --git a/15/umbraco-ui-builder/areas/trees.md b/15/umbraco-ui-builder/areas/trees.md index b7e232aaaef..b05de36b90f 100644 --- a/15/umbraco-ui-builder/areas/trees.md +++ b/15/umbraco-ui-builder/areas/trees.md @@ -25,7 +25,6 @@ Tree(Lambda treeConfig = null) : TreeConfigBuilder #### Example ```csharp - sectionConfig.Tree(treeConfig => { ... });