From a332d79dfcfbe90f760832eafeca58a1edecb1a3 Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Sun, 27 Jul 2025 22:16:56 -0500 Subject: [PATCH 1/2] Refine documentation for Section, Section View, and Section Sidebar extensions. Expanded details on manifest configurations and best practices, clarified user group permissions, and introduced examples for extending with dashboards, menus, and custom elements. --- .../extension-types/sections/README.md | 2 +- .../sections/section-sidebar.md | 176 +++++++++++++----- .../extension-types/sections/section-view.md | 119 ++++++++++-- .../extension-types/sections/section.md | 61 +++--- 4 files changed, 273 insertions(+), 85 deletions(-) diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/README.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/README.md index b3c2aa0ce97..498954cfad1 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/README.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/README.md @@ -1,6 +1,6 @@ --- description: >- - An overview of the availabe extension types related to sections. + A comprehensive summary of the available extension types associated with sections. --- # Extension Types: Sections diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-sidebar.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-sidebar.md index 3b008c02fe2..db9e3da5dee 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-sidebar.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-sidebar.md @@ -1,75 +1,157 @@ +--- +description: >- + Leverage Section Sidebar extensions to add deeper navigation and coordination of Section Views, and additional + Section-wide functionality inside Section extensions. +--- + # Section Sidebar -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} +[Section extensions](./section.md) can add deeper navigation and coordination of subviews, like +[Section View extensions](./section-view.md), as well as add additional Section-wide functionality, by declaring a +Section Sidebar extension. + +Section Sidebar extensions are optional; if not defined, the Section extension defaults to a single full-screen subview.

Section Sidebar

-## Section Sidebar Apps +## Section Sidebar Apps + +Section Sidebar extensions can be composed of **one or more** section sidebar apps. Extension authors can include common +Umbraco-provided extension types, such as menus and trees, or create entirely custom sidebar apps through the use of +web components.

Section Sidebar Apps

-**Manifest** +### Custom Sidebar App Example -```typescript -{ - "type": "sectionSidebarApp", - "alias": "My.SectionSidebarApp", - "name": "My Section Sidebar App", - "meta": { - "sections": ["My.Section"] - } -} -``` +Section Sidebar extension authors can place any custom web component into the sidebar. Extension authors will need to +supply the `element` property with the path of their custom web component. We recommend specifying the full path, +starting from the Umbraco project root. -**Default Element** +Sidebar Section extension authors may specify placement of the Section Sidebar app using +[extension conditions](../condition.md). -```typescript -interface UmbSectionSidebarAppElement {} +```json +{ + "type": "sectionSidebarApp", + "alias": "My.SectionSidebarApp", + "name": "My Section Sidebar App", + "element": "/App_Plugins//sidebar-app.js", + "conditions": [{ + "alias": "Umb.Condition.SectionAlias", + "match": "My.Section" + }] +} ``` -## **Menu Sidebar App** +### Menu Sidebar App Examples -**Sidebar Menu**: - -* The Backoffice comes with a menu sidebar app that can be used to create a menu in the sidebar. -* To register a new menu sidebar app, add the following to your manifest -* The menu sidebar app will reference a menu that you have registered in the menu with a menu manifest +The menu sidebar app is provided by the Umbraco backoffice and can be placed into Section Sidebar extensions. This +sidebar app will attach itself to a menu defined elsewhere in your manifest through the `meta:menu` property, where +this value must match the `alias` value of the menu.

Menu Sidebar App

-**Manifest** - -```typescript +```json { - "type": "sectionSidebarApp", - "kind": "menu", - "alias": "My.SectionSidebarApp.MyMenu", - "name": "My Menu Section Sidebar App", - "meta": { - "label": "My Sidebar Menu", - "menu": "My.Menu" - }, - "conditions": [ - { - "alias": "Umb.Condition.SectionAlias", - "match": "My.Section" - } - ] + "type": "sectionSidebarApp", + "kind": "menu", + "alias": "My.SectionSidebarApp.MyMenu", + "name": "My Menu Section Sidebar App", + "meta": { + "label": "My Sidebar Menu", + "menu": "My.Menu" + }, + "conditions": [{ + "alias": "Umb.Condition.SectionAlias", + "match": "My.Section" + }] } ``` -**Default Element** +In the example below, we continue by creating a menu extension and binding the `meta:menu` (My.Menu) property to the +menu extensions' `alias` property. The *My.Menu* alias is also used to attach a menu item extension to the menu +extension. + +```json +[ + { + "type": "menu", + "alias": "My.Menu", + "name": "Section Sidebar Menu" + }, + { + "type": "menuItem", + "alias": "SectionSidebar.MenuItem1", + "name": "Menu Item 1", + "meta": { + "label": "Menu Item 1", + "menus": ["My.Menu"] + } + } +] +``` -```typescript -interface UmbMenuSectionSidebarAppElement {} +For more information, see the documentation for the [menus](../menu.md) extension. + +#### Coordinating subviews with menu items + +Menu sidebar apps can coordinate navigation between subviews in the section extension by referencing +[workspace extensions](../workspaces/workspace.md). Modify the menu item extension to include the `meta:entityType` +property, and assign it the same value as a workspace view extensions' own `meta:entityType` property. + +```json +[ + { + "type": "menuItem", + "alias": "SectionSidebar.MenuItem1", + "name": "Menu Item 1", + "meta": { + "label": "Menu Item 1", + "menus": ["My.Menu"], + "entityType": "myCustomWorkspaceView" + } + }, + { + "type": "workspace", + "name": "Workspace 1", + "alias": "SectionSidebar.Workspace1", + "element": "/App_Plugins//my-custom-workspace.js", + "meta": { + "entityType": "myCustomWorkspaceView" + } + } +] ``` -**Adding Items to an existing menu** +#### Adding items to an existing menu -This will make it possible to compose a sidebar menu from multiple Apps: +Section Sidebar extension authors can place their extensions in the sidebar of any Umbraco-provided section, such as +Content, Media, Settings, etc., by configuring the `conditions` property with the appropriate `SectionAlias` condition.

Composed sidebar menu

-You can read more about this in the [Menu](../menu.md) article. +```json +{ + "type": "sectionSidebarApp", + "alias": "My.SectionSidebarApp", + "name": "My Section Sidebar App", + "element": "/App_Plugins//sidebar-app.js", + "conditions": [{ + "alias": "Umb.Condition.SectionAlias", + "match": "Umb.Section.Settings" + }] +} +``` + +Common Umbraco-provided section aliases: + +| Section Aliases | +|-------------------------| +| Umb.Section.Content | +| Umb.Section.Media | +| Umb.Section.Settings | +| Umb.Section.Packages | +| Umb.Section.Users | +| Umb.Section.Members | +| Umb.Section.Translation | diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md index 39be2284a63..d1064c6412b 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md @@ -1,35 +1,40 @@ --- description: >- - Append a secondary view for a Section, use it for additional features or - information. + Add auxiliary views to your own Umbraco packages, or to other areas of the Umbraco backoffice. --- # Section View -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} +Section View extensions serve as containers that can be integrated into custom Umbraco packages or extended other areas +of the Umbraco backoffice, including the Settings, User, or Member management sections. These extensions can contain +other Umbraco extensions, such as dashboards or web components, enabling package authors to populate the section with +virtually any content or custom interface they envision.

Section View

## Creating a custom Section View -In this section, you can learn how to register and create a custom Section View for the Umbraco backoffice. +Custom Section View extensions are straightforward to create. Extension authors register the Section View extension and +subsequently implement the content or interface they desire to display within the Section View. -### Manifest +### Registering Section View extensions -The manifest file can be created using either JSON or TypeScript. Both methods are shown below. +Extension authors have the option of registering custom Section View extensions using two methods: declarative +registration via manifests or imperative registration using TypeScript and [Backoffice Entry Points](../backoffice-entry-point.md). Both methods +are shown below. + +#### Registering by manifest {% tabs %} {% tab title="Json" %} -We can create the manifest using json in the `umbraco-package.json`. +Extensions authors can register the Section View extension using a JSON declaration in the `umbraco-package.json` file. ```json { "type": "sectionView", "alias": "My.SectionView", "name": "My Section View", - "element": "./my-section.element.js", + "element": "/App_Plugins//my-section.element.js", "meta": { "label": "My View", "icon": "icon-add", @@ -38,11 +43,15 @@ We can create the manifest using json in the `umbraco-package.json`. "conditions": [ { "alias": "Umb.Condition.SectionAlias", - "match": "My.Section", + "match": "My.Section" } ] } ``` + +Tip: We recommend using the absolute path, starting from the root of your Umbraco project, in the `element` property for +JSON declarations. TypeScript declarations are capable of employing relative paths. + {% endtab %} {% tab title="TypeScript" %} @@ -115,5 +124,93 @@ declare global { 'my-sectionview-element': MySectionViewElement; } } +``` + +## Adding Section Views to your own package + +When developing a Section View extension for their own package, an extension author must create a Section extension to +host the Section View extension. + +Guidelines on creating Section extensions can be found at [this link](./section.md). + +To associate the Section View extension with the Section extension, authors must set the `match` property of the Section +Extension’s condition definition to the same value as the `alias` property of their desired Section extension. In the +provided example, this value is `NetworkServices.Section`. + +```json +[ + { + "type": "section", + "alias": "NetworkServices.Section", + "name": "Network Services", + "meta": { + "label": "Network Services", + "pathname": "network-services" + } + }, + { + "type": "sectionView", + "alias": "NetworkServices.Section.Overview", + "name": "Network Services Overview", + "element": "/App_Plugins/NetworkServices/overview-dashboard.js", + "meta": { + "label": "Overview", + "icon": "icon-add", + "pathname": "overview" + }, + "conditions": [ + { + "alias": "Umb.Condition.SectionAlias", + "match": "NetworkServices.Section" + } + ] + } +] +``` + +## Adding Section Views to somewhere else in the backoffice + +The Umbraco backoffice architecture places a strong emphasis on composing. Extension authors can extend existing +sections, including those built by Umbraco and included in the core (such as Content, Media, and Settings), using +Section View extensions. +After an author has completed their Section View extension, they can control the placement of the extension using +conditions in the manifest definition. + +The `match` property demonstrates how an extension author can incorporate a custom Section View within the Content +section. + +```json +{ + "type": "sectionView", + "alias": "My.SectionView", + "name": "My Section View", + "element": "/App_Plugins//my-section.element.js", + "meta": { + "label": "My View", + "icon": "icon-add", + "pathname": "my-view" + }, + "conditions": [ + { + "alias": "Umb.Condition.SectionAlias", + "match": "Umb.Section.Content" + } + ] +} ``` + +Common Umbraco-provided section aliases: + +| Section Aliases | +|-------------------------| +| Umb.Section.Content | +| Umb.Section.Media | +| Umb.Section.Settings | +| Umb.Section.Packages | +| Umb.Section.Users | +| Umb.Section.Members | +| Umb.Section.Translation | + +Section view extensions can also be made available within the Sidebar extensions in Umbraco-provided sections, along +with a custom sidebar composed by the extension author. diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section.md index ea01a688e02..16e7533a6ba 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section.md @@ -1,18 +1,14 @@ --- -description: A guide to creating a section +description: Introducing Section extensions, a home for custom content and functionality. --- # Sections -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -The Umbraco backoffice consists of Sections. Section is the main division shown in the top navigation. +Umbraco extension authors can place their extension in the top-level navigation of the backoffice using Sections. The +extension will be placed among the default options such as Content, Media, Settings, etc. -For example, when you load the backoffice, you'll see the 'Content' section, 'Settings' section, and so on. - -You can create your own sections to extend Umbraco with room for more features. +Within the section, authors can add menus, section views, workspace views, or any other content or interface they +desire.

Section

@@ -20,11 +16,9 @@ You can create your own sections to extend Umbraco with room for more features. ### **Manifests** -When creating a new section it's recommended to use a [Entry Point](../backoffice-entry-point.md)-extension in your [Umbraco Package Manifest](../../../umbraco-package.md). This is to get better control over all the additional extensions required for the new section. - -Create a section by defining a manifest for it: +Sections can be created by adding a definition in the extension's manifest file. -```typescript +```json { "type": "section", "alias": "My.Section", @@ -36,30 +30,43 @@ Create a section by defining a manifest for it: } ``` -Once registered, you will be able to select this action for your User Group Permissions. Once that is permitted, you can view your section. +### **Group permissions** + +To enable custom sections for backoffice users, site administrators must first assign permissions to those users. This +involves configuring the permission for a user group and assigning users to that group. + +To grant access to the custom section, open the Umbraco backoffice, navigate to the **Users** section, and select the +**User groups** menu item. Site administrators can create a new user group or modify an existing one. + +Once the user group is open, click the **Choose** button under the Sections section. Select the custom section from the +slide-out modal to enable access. + +After assigning permission, users may need to reload the backoffice for the changes to take effect.

Section

-#### **Extend with Sidebar, Dashboards and more** +### **Entry points** -Once a section is registered, it can be extended like any other section. +When creating a new section, it is recommended to create am [Entry Point](../backoffice-entry-point.md)-extension in the +[Umbraco Package Manifest](../../../umbraco-package.md) to complement. Entry Point extensions add initialization and +teardown lifecycle events that may be helpful in coordinating behavior inside the section. -Here is a list of appropriate extensions to append to your section: +## **Extend with Sidebar, Dashboards, and more** -* [Creating a Custom Dashboard](../../../../tutorials/creating-a-custom-dashboard/) -* [Section Sidebar](section-sidebar.md) -* [Section View](section-view.md) +Sections serve as blank canvases within the Umbraco backoffice. Extension authors can integrate other Umbraco extensions +into sections, including [custom dashboards](../../../../tutorials/creating-a-custom-dashboard/), +[sidebars](section-sidebar.md), and [section views](section-view.md). -#### **Manifest with empty element** +Section authors can also eschew Umbraco-provided backoffice components and construct a fully customized view for full +control by creating a custom/empty element. -If you prefer full control over the content of your section you can choose to define an element for the content of your section. +### **Manifest with empty element** {% hint style="warning" %} -This is not recommended as it limits the content of your section to this element. Instead, it is recommended to use a single Dashboard or Section View. +This approach is not recommended as it restricts the content of your section to this element. Instead, it is advisable +to use a single Dashboard or Section View. {% endhint %} -If you like to have full control, you can define an element like this: - ```typescript const section : UmbExtensionManifest = { type: "section", @@ -73,4 +80,6 @@ const section : UmbExtensionManifest = { } ``` -The element file must have an `element` or `default` export, or specify the element name in the `elementName` field. +The element file must contain either an `element` or `default` export, or explicitly specify the element name in the +`elementName` field. + From 03d3b7cb10ea6d675185f98202cde5f85c65d03c Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Sun, 27 Jul 2025 22:22:54 -0500 Subject: [PATCH 2/2] Expand documentation to include additional areas for Section View extensions, highlighting Content, Media, and Translations sections. --- .../extension-types/sections/section-view.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md index d1064c6412b..811ed6d1035 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md @@ -5,10 +5,10 @@ description: >- # Section View -Section View extensions serve as containers that can be integrated into custom Umbraco packages or extended other areas -of the Umbraco backoffice, including the Settings, User, or Member management sections. These extensions can contain -other Umbraco extensions, such as dashboards or web components, enabling package authors to populate the section with -virtually any content or custom interface they envision. +Section View extensions serve as containers that can be integrated into custom Umbraco packages or extended to other +areas of the Umbraco backoffice, including the Content, Media, Settings, User, Member, or Translations sections. These +extensions can contain other Umbraco extensions, such as dashboards or web components, enabling package authors to +populate the section with virtually any content or custom interface they envision.

Section View